Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us