> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zkp2p/zkp2p-contracts/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField path="escrowRegistry" type="IEscrowRegistry">
  Registry of escrow contracts
</ParamField>

<ParamField path="paymentVerifierRegistry" type="IPaymentVerifierRegistry">
  Registry of payment verifiers
</ParamField>

<ParamField path="postIntentHookRegistry" type="IPostIntentHookRegistry">
  Registry of post intent hooks
</ParamField>

<ParamField path="relayerRegistry" type="IRelayerRegistry">
  Registry of relayers
</ParamField>

<ParamField path="protocolFee" type="uint256">
  Protocol fee taken from taker (in preciseUnits, 1e16 = 1%)
</ParamField>

<ParamField path="protocolFeeRecipient" type="address">
  Address that receives protocol fees
</ParamField>

<ParamField path="allowMultipleIntents" type="bool">
  Whether to allow multiple intents per account
</ParamField>

<ParamField path="intentCounter" type="uint256">
  Counter for number of intents created; nonce for unique intent hashes
</ParamField>

## Core Functions

### Intent Lifecycle

#### signalIntent

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

<ParamField path="_params" type="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
</ParamField>

```solidity theme={null}
function signalIntent(SignalIntentParams calldata _params) external whenNotPaused
```

**Events Emitted:**

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

**Example:**

```solidity theme={null}
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.

<ParamField path="_intentHash" type="bytes32">
  Hash of intent being cancelled
</ParamField>

```solidity theme={null}
function cancelIntent(bytes32 _intentHash) external
```

**Events Emitted:**

* `IntentPruned(intentHash)`

#### fulfillIntent

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

<ParamField path="_params" type="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
</ParamField>

```solidity theme={null}
function fulfillIntent(FulfillIntentParams calldata _params) 
    external nonReentrant whenNotPaused
```

**Events Emitted:**

* `IntentFulfilled(intentHash, to, netAmount, isManualRelease)`
* `IntentPruned(intentHash)`

**Example:**

```solidity theme={null}
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.

<ParamField path="_intentHash" type="bytes32">
  Hash of intent to resolve by releasing the funds
</ParamField>

```solidity theme={null}
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.

<ParamField path="_intents" type="bytes32[]">
  Array of intent hashes to prune
</ParamField>

```solidity theme={null}
function pruneIntents(bytes32[] calldata _intents) external
```

## Governance Functions

### setEscrowRegistry

Updates the escrow registry address.

<ParamField path="_escrowRegistry" type="address">
  New escrow registry address
</ParamField>

```solidity theme={null}
function setEscrowRegistry(address _escrowRegistry) external onlyOwner
```

### setProtocolFee

Updates the protocol fee.

<ParamField path="_protocolFee" type="uint256">
  New protocol fee in preciseUnits (1e16 = 1%)
</ParamField>

```solidity theme={null}
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.

<ParamField path="_protocolFeeRecipient" type="address">
  New protocol fee recipient address
</ParamField>

```solidity theme={null}
function setProtocolFeeRecipient(address _protocolFeeRecipient) external onlyOwner
```

### setAllowMultipleIntents

Sets whether all accounts can signal multiple intents.

<ParamField path="_allowMultiple" type="bool">
  True to allow all accounts to signal multiple intents
</ParamField>

```solidity theme={null}
function setAllowMultipleIntents(bool _allowMultiple) external onlyOwner
```

### Pause/Unpause

```solidity theme={null}
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.

```solidity theme={null}
function getIntent(bytes32 _intentHash) external view returns (Intent memory)
```

<ResponseField name="owner" type="address">
  Address of the intent owner
</ResponseField>

<ResponseField name="to" type="address">
  Address to receive the funds
</ResponseField>

<ResponseField name="escrow" type="address">
  Escrow contract address
</ResponseField>

<ResponseField name="depositId" type="uint256">
  Deposit ID being taken from
</ResponseField>

<ResponseField name="amount" type="uint256">
  Amount of tokens to receive
</ResponseField>

<ResponseField name="paymentMethod" type="bytes32">
  Payment method identifier
</ResponseField>

<ResponseField name="fiatCurrency" type="bytes32">
  Fiat currency code
</ResponseField>

<ResponseField name="conversionRate" type="uint256">
  Conversion rate for the transaction
</ResponseField>

<ResponseField name="payeeId" type="bytes32">
  Payee identifier hash
</ResponseField>

<ResponseField name="timestamp" type="uint256">
  Timestamp when the intent was signaled
</ResponseField>

<ResponseField name="referrer" type="address">
  Referrer address
</ResponseField>

<ResponseField name="referrerFee" type="uint256">
  Fee for the referrer
</ResponseField>

<ResponseField name="postIntentHook" type="IPostIntentHook">
  Post-intent hook contract
</ResponseField>

<ResponseField name="data" type="bytes">
  Additional data for hooks
</ResponseField>

#### getAccountIntents

Returns all active intent hashes for an account.

```solidity theme={null}
function getAccountIntents(address _account) external view returns (bytes32[] memory)
```

#### getIntentMinAtSignal

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

```solidity theme={null}
function getIntentMinAtSignal(bytes32 _intentHash) external view returns (uint256)
```

## Events

### IntentSignaled

Emitted when a new intent is signaled.

```solidity theme={null}
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.

```solidity theme={null}
event IntentFulfilled(
    bytes32 indexed intentHash,
    address indexed to,
    uint256 netAmount,
    bool isManualRelease
)
```

### IntentPruned

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

```solidity theme={null}
event IntentPruned(bytes32 indexed intentHash)
```

## Constants

<ParamField path="PRECISE_UNIT" type="uint256">
  `1e18` - Precision unit for fee calculations
</ParamField>

<ParamField path="CIRCOM_PRIME_FIELD" type="uint256">
  `21888242871839275222246405745257275088548364400416034343698204186575808495617` - Prime field for intent hash calculations
</ParamField>

<ParamField path="MAX_REFERRER_FEE" type="uint256">
  `5e17` - Maximum referrer fee (50%)
</ParamField>

<ParamField path="MAX_PROTOCOL_FEE" type="uint256">
  `1e17` - Maximum protocol fee (10%)
</ParamField>

## 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

```solidity theme={null}
protocolFeeAmount = (releaseAmount * protocolFee) / PRECISE_UNIT
referrerFeeAmount = (releaseAmount * referrerFee) / PRECISE_UNIT
netAmount = releaseAmount - protocolFeeAmount - referrerFeeAmount
```