Skip to main content

Orchestrator

Overview​

OrchestratorV3 owns the current intent lifecycle and fee distribution. It verifies gating signatures, runs the deposit's optional pre-intent hook, snapshots and calls the active lifecycle hook, locks liquidity in EscrowV2, routes payment verification, and transfers funds net of protocol, referral, and manager fees. It also supports optional post-intent hooks through IPostIntentHookV2.

OrchestratorV2 remains registered only so existing V2 intents can complete against the contract that owns them. New production intents use OrchestratorV3.

Constants​

  • PRECISE_UNIT = 1e18
  • MAX_PROTOCOL_FEE = 5e16 (5%)
  • MAX_MANAGER_FEE = 5e16 (5%)
  • MAX_REFERRER_FEE = 5e17 (50% total across referral recipients)

Key state​

  • Active intents and per-account intent indexes.
  • Snapshotted manager fee recipient and amount per intent.
  • One depositPreIntentHooks[escrow][depositId] entry per deposit.
  • One governance-selected lifecycleHook, plus a snapshotted lifecycle hook per intent.
  • Escrow, payment-verifier, and relayer registries.
  • Protocol fee, protocol fee recipient, and the multiple-intents setting.

Signal intent​

signalIntent(SignalIntentParams params) accepts:

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 call is atomic:

  1. Validate the escrow, deposit, payment method, currency, rate, fees, and gating-service signature.
  2. Run the deposit's generic pre-intent hook, if configured. A revert rejects the intent.
  3. Snapshot manager-fee data and create the intent state.
  4. Snapshot the current global lifecycle hook and call onIntentSignaled. Production's WhitelistLifecycleHook rejects takers who do not satisfy an enabled deposit access policy.
  5. Lock funds in EscrowV2 and emit IntentSignaled.

If any hook or later operation reverts, the whole transaction rolls back.

Fulfill intent​

fulfillIntent(FulfillIntentParams params) accepts:

struct FulfillIntentParams {
  bytes paymentProof;
  bytes32 intentHash;
  bytes verificationData;
  bytes postIntentHookData;
}

The orchestrator resolves the payment method's registered verifier. Every current production payment method resolves to UnifiedPaymentVerifierV2. After successful verification, it unlocks the verifier-authorized release amount, distributes protocol, manager, and referral fees, and sends the net amount to the recipient or post-intent hook. A partial release returns unused locked liquidity to the deposit.

The lifecycle hook snapshotted at signal time receives the settlement callback; changing the global hook cannot redirect an existing intent.

Other operations​

  • cancelIntent(intentHash) prunes an eligible intent, calls its snapshotted cancellation hook, then unlocks funds in EscrowV2. A revert rolls back the complete operation.
  • releaseFundsToPayer(intentHash) performs the depositor's manual release path and distributes configured fees.
  • pruneIntents(intentHashes) lets Escrow prune expired intents.
  • cleanupOrphanedIntents(intentHashes) permissionlessly removes intents whose deposits no longer exist.

Hook management​

  • setDepositPreIntentHook(escrow, depositId, hook) sets or clears the one generic pre-intent hook slot. The depositor or delegate controls it.
  • Governance selects the global lifecycle hook with setLifecycleHook(hook). Depositors do not choose this hook.
  • OrchestratorV3 has no separate deposit whitelist-hook slot. Current Groups and direct-wallet access use WhitelistPolicy, enforced by the active WhitelistLifecycleHook.

See Pre-Intent Hooks and Access Groups.

Selected events​

  • IntentSignaled
  • IntentFulfilled
  • IntentPruned
  • IntentReferralFeeDistributed
  • IntentManagerFeeSnapshotted
  • DepositPreIntentHookSet
  • LifecycleHookUpdated
  • IntentLifecycleHookSnapshotted
  • ProtocolFeeUpdated
  • ProtocolFeeRecipientUpdated

Reference: zkp2p-contracts/contracts/OrchestratorV3.sol