OrchestratorV3

OrchestratorV3 extends the V2 intent and fee lifecycle with a per-deposit risk-hook boundary. It keeps the V2 signal, cancel, manual-release, verification, fee, and post-intent-hook behavior while letting a liquidity provider opt future intents into the canonical continuous stake-risk system.

The source of truth is OrchestratorV3.sol. See V3 Deployments for environment-specific addresses.

Risk-hook selection and snapshots

A depositor or its Escrow delegate calls:

setDepositRiskHook(address escrow, uint256 depositId, IIntentRiskHook hook)

The selection affects only future intents. At signalIntent, V3 snapshots the deposit's current risk hook into intentRiskHooks[intentHash], then calls onIntentCreated. Changing or removing the deposit hook later cannot rewrite an existing position.

The canonical RiskManager uses this callback to select one admission mode:

Mode	Pending-order backing	After settlement
NONE	No risk position, including deposits with no hook	No risk position
FREE	A whole configured free take; no stake reservation	Terminal on fulfilment
STAKE_BACKED	The larger of maximum griefing bond and chargeback reserve	Reservation released or resized to chargeback coverage
DEFERRED_PAYOUT	Stake covers the griefing bond	Net payout is routed into StakeVault for the chargeback window

If admission rejects, signalIntent reverts atomically: the intent, liquidity lock, free-take consumption, and reservation do not persist.

Signal intent

signalIntent(SignalIntentParams) retains the V2 parameters and validations:

struct SignalIntentParams {
  address escrow;
  uint256 depositId;
  uint256 amount;
  address to;
  bytes32 paymentMethod;
  bytes32 fiatCurrency;
  uint256 conversionRate;
  IReferralFee.ReferralFee[] referralFees;
  bytes gatingServiceSignature;
  uint256 signatureExpiration;
  IPostIntentHookV2 postIntentHook;
  bytes preIntentHookData;
  bytes data;
}

The lifecycle is:

1. Validate the Escrow, deposit, payment method, currency, conversion rate, gating signature, and fee bounds.
2. Run configured pre-intent and whitelist hooks.
3. Store the intent and lock its liquidity in EscrowV2.
4. Snapshot and call the deposit risk hook with bounded gas.
5. Revert the complete transaction if risk admission fails or if a required deferred-payout hook is missing.

Quotes are deliberately separate from risk admission. The quote service returns otherwise valid deposit candidates without filtering them by a taker's changing stake capacity. Clients should fetch capacity for warnings, but only signalIntent is authoritative.

Fulfilment and manual release

V3 uses the same payment-verifier registry and UnifiedPaymentVerifierV2 attestation path as V2. After verification, it unlocks the exact release amount, applies protocol, rate-manager, and referral fees, and sends the net amount to the intent recipient or selected post-intent hook.

When the snapshotted risk position requires deferred payout, V3 enforces the canonical DeferredPayoutHook even on manual release. The hook sends net proceeds directly from the Orchestrator to StakeVault and registers the beneficiary and maturity with RiskManager; the funds never pass through the manager.

Cancellation, expiry, and liveness

cancelIntent and orphan cleanup are non-reentrant because terminal resolution now includes an external risk callback. V3 records the time liquidity stopped being locked and invokes the snapshotted hook with bounded gas.

Terminal callbacks fail open so a broken hook cannot trap Escrow liquidity. When a cancellation or settlement callback fails, V3 stores durable recovery data:

• getIntentCancellation(intentHash) returns the original cancellation timestamp.
• getIntentSettlement(intentHash) returns the exact released amount and settlement timestamp.

Anyone can later call the RiskManager's reconciliation functions. A cancellation penalty uses the recorded cancellation time, not the later reconciliation time, so failure cannot increase liability or erase a reserved liability.

V2 coexistence

OrchestratorV2 and OrchestratorV3 are separate contracts authorized through the shared OrchestratorRegistry. Existing V2 deposits and intents continue under their snapshotted V2 rules. A deposit uses V3 risk only when the client routes to OrchestratorV3 and the depositor has selected the canonical risk hook; there is no in-place mutation of V2 intent state.

Operational controls

• The owner can update the bounded callback gas limit, subject to the contract minimum.
• RiskManager can pause new admission.
• StakeVault can pause deposits and new reservations independently.
• Pauses do not block cancellation reconciliation, maturity, compensation, or eligible withdrawals.
• allowMultipleIntents remains an Orchestrator operational setting. It is not a stake tier or economic capacity rule.

Selected V3 events

• DepositRiskHookSet
• IntentRiskHookSnapshotted
• RiskHookCallbackFailed
• IntentSettlementRecorded
• IntentCancellationRecorded
• RiskCallbackGasLimitUpdated

V2 lifecycle events such as IntentSignaled, IntentFulfilled, IntentPruned, IntentReferralFeeDistributed, and IntentManagerFeeSnapshotted remain available.