Orchestrator

Core orchestrator contract managing intent lifecycle and P2P trading

Orchestrator Contract

The Orchestrator contract manages the intent (order) lifecycle and orchestrates P2P trading of fiat currency and onchain assets. It coordinates with the Escrow contract to lock/unlock funds and handles intent fulfillment.

Overview

• Contract: Orchestrator.sol
• Inherits: Ownable, Pausable, ReentrancyGuard, IOrchestrator
• Purpose: Manages intent lifecycle and orchestrates P2P trading

Key State Variables

escrowRegistry · IEscrowRegistry

Registry of escrow contracts

paymentVerifierRegistry · IPaymentVerifierRegistry

Registry of payment verifiers

postIntentHookRegistry · IPostIntentHookRegistry

Registry of post intent hooks

relayerRegistry · IRelayerRegistry

Registry of relayers

protocolFee · uint256

Protocol fee taken from taker (in preciseUnits, 1e16 = 1%)

protocolFeeRecipient · address

Address that receives protocol fees

allowMultipleIntents · bool

Whether to allow multiple intents per account

intentCounter · uint256

Counter for number of intents created; nonce for unique intent hashes

Core Functions

Intent Lifecycle

signalIntent

Signals intent to pay the depositor off-chain to unlock funds on-chain.

_params · SignalIntentParams

Struct containing all intent parameters:

• escrow: Address of the escrow contract
• depositId: The deposit ID to take from
• amount: Amount of tokens to receive
• to: Address to receive the funds
• paymentMethod: Payment method identifier
• fiatCurrency: Fiat currency code
• conversionRate: Conversion rate for the transaction
• referrer: Optional referrer address
• referrerFee: Fee for the referrer (in preciseUnits)
• postIntentHook: Optional post-intent hook contract
• data: Additional data for hooks
• gatingServiceSignature: Signature from the deposit’s gating service
• signatureExpiration: Expiration timestamp for the signature

function signalIntent(SignalIntentParams calldata _params) external whenNotPaused

Events Emitted:

• IntentSignaled(intentHash, escrow, depositId, paymentMethod, owner, to, amount, fiatCurrency, conversionRate, timestamp)

Example:

IOrchestrator.SignalIntentParams memory params = IOrchestrator.SignalIntentParams({
    escrow: escrowAddress,
    depositId: 1,
    amount: 100e6,
    to: msg.sender,
    paymentMethod: venmoHash,
    fiatCurrency: usdHash,
    conversionRate: 1e18,
    referrer: address(0),
    referrerFee: 0,
    postIntentHook: IPostIntentHook(address(0)),
    data: "",
    gatingServiceSignature: signature,
    signatureExpiration: block.timestamp + 3600
});

orchestrator.signalIntent(params);

cancelIntent

Cancels an outstanding intent. Only callable by the intent owner.

_intentHash · bytes32

Hash of intent being cancelled

function cancelIntent(bytes32 _intentHash) external

Events Emitted:

• IntentPruned(intentHash)

fulfillIntent

Fulfills an intent by verifying the off-chain payment proof.

_params · FulfillIntentParams

Struct containing all fulfillment parameters:

• intentHash: The intent hash to fulfill
• paymentProof: Proof of the off-chain payment
• verificationData: Additional data for payment verification
• postIntentHookData: Data to pass to the post-intent hook

function fulfillIntent(FulfillIntentParams calldata _params) 
    external nonReentrant whenNotPaused

Events Emitted:

• IntentFulfilled(intentHash, to, netAmount, isManualRelease)
• IntentPruned(intentHash)

Example:

IOrchestrator.FulfillIntentParams memory params = IOrchestrator.FulfillIntentParams({
    intentHash: intentHash,
    paymentProof: proofData,
    verificationData: additionalData,
    postIntentHookData: hookData
});

orchestrator.fulfillIntent(params);

releaseFundsToPayer

Allows depositor to release funds to the payer in case of failed fulfillment or other arrangement.

_intentHash · bytes32

Hash of intent to resolve by releasing the funds

function releaseFundsToPayer(bytes32 _intentHash) external nonReentrant

Events Emitted:

• IntentFulfilled(intentHash, to, netAmount, true)
• IntentPruned(intentHash)

Escrow Functions

pruneIntents

ESCROW ONLY: Called by escrow to prune specific expired intents.

_intents · bytes32[]

Array of intent hashes to prune

function pruneIntents(bytes32[] calldata _intents) external

Governance Functions

setEscrowRegistry

Updates the escrow registry address.

_escrowRegistry · address

New escrow registry address

function setEscrowRegistry(address _escrowRegistry) external onlyOwner

setProtocolFee

Updates the protocol fee.

_protocolFee · uint256

New protocol fee in preciseUnits (1e16 = 1%)

function setProtocolFee(uint256 _protocolFee) external onlyOwner

Note: Fee must be less than or equal to MAX_PROTOCOL_FEE (10%)

setProtocolFeeRecipient

Updates the protocol fee recipient address.

_protocolFeeRecipient · address

New protocol fee recipient address

function setProtocolFeeRecipient(address _protocolFeeRecipient) external onlyOwner

setAllowMultipleIntents

Sets whether all accounts can signal multiple intents.

_allowMultiple · bool

True to allow all accounts to signal multiple intents

function setAllowMultipleIntents(bool _allowMultiple) external onlyOwner

Pause/Unpause

function pauseOrchestrator() external onlyOwner
function unpauseOrchestrator() external onlyOwner

Paused Functionalities:

• Intent creation (signalIntent)
• Intent fulfillment (fulfillIntent)

Unpaused Functionalities (for fund recovery):

• Intent cancellation (cancelIntent)
• Manual fund release (releaseFundsToPayer)
• Intent pruning by escrow (pruneIntents)

View Functions

getIntent

Returns the intent struct for a given intent hash.

function getIntent(bytes32 _intentHash) external view returns (Intent memory)

owner · address

Address of the intent owner

to · address

Address to receive the funds

escrow · address

Escrow contract address

depositId · uint256

Deposit ID being taken from

amount · uint256

Amount of tokens to receive

paymentMethod · bytes32

Payment method identifier

fiatCurrency · bytes32

Fiat currency code

conversionRate · uint256

Conversion rate for the transaction

payeeId · bytes32

Payee identifier hash

timestamp · uint256

Timestamp when the intent was signaled

referrer · address

Referrer address

referrerFee · uint256

Fee for the referrer

postIntentHook · IPostIntentHook

Post-intent hook contract

data · bytes

Additional data for hooks

getAccountIntents

Returns all active intent hashes for an account.

function getAccountIntents(address _account) external view returns (bytes32[] memory)

getIntentMinAtSignal

Returns the minimum intent amount that was enforced when the intent was signaled.

function getIntentMinAtSignal(bytes32 _intentHash) external view returns (uint256)

Events

IntentSignaled

Emitted when a new intent is signaled.

event IntentSignaled(
    bytes32 indexed intentHash,
    address indexed escrow,
    uint256 indexed depositId,
    bytes32 paymentMethod,
    address owner,
    address to,
    uint256 amount,
    bytes32 fiatCurrency,
    uint256 conversionRate,
    uint256 timestamp
)

IntentFulfilled

Emitted when an intent is fulfilled.

event IntentFulfilled(
    bytes32 indexed intentHash,
    address indexed to,
    uint256 netAmount,
    bool isManualRelease
)

IntentPruned

Emitted when an intent is pruned (cancelled or expired).

event IntentPruned(bytes32 indexed intentHash)

Constants

PRECISE_UNIT · uint256

1e18 - Precision unit for fee calculations

CIRCOM_PRIME_FIELD · uint256

21888242871839275222246405745257275088548364400416034343698204186575808495617 - Prime field for intent hash calculations

MAX_REFERRER_FEE · uint256

5e17 - Maximum referrer fee (50%)

MAX_PROTOCOL_FEE · uint256

1e17 - Maximum protocol fee (10%)

Fee Structure

Fees are deducted from the release amount in the following order:

1. Protocol Fee: Taken from the release amount and sent to protocolFeeRecipient
2. Referrer Fee: Taken from the release amount and sent to referrer
3. Net Amount: Remaining amount sent to the intent recipient or post-intent hook

protocolFeeAmount = (releaseAmount * protocolFee) / PRECISE_UNIT
referrerFeeAmount = (releaseAmount * referrerFee) / PRECISE_UNIT
netAmount = releaseAmount - protocolFeeAmount - referrerFeeAmount