Intent Lifecycle

Overview

An intent represents a buyer’s commitment to pay off-chain fiat currency in exchange for on-chain tokens. This page walks through the complete lifecycle from signal to fulfillment, showing all contract interactions and state changes.

The intent lifecycle is the core workflow of the zkp2p protocol, coordinating between Orchestrator, Escrow, payment verifiers, and registries.

Lifecycle Stages

Stage 1: Discovery

The buyer browses available deposits (off-chain indexing or on-chain queries) to find one matching their requirements:

// Off-chain: Query deposits via event indexing or ProtocolViewer
const deposits = await protocolViewer.getActiveDeposits();

// Find deposits that:
// - Accept the buyer's payment method (e.g., Venmo)
// - Support the buyer's currency (e.g., USD)
// - Have sufficient liquidity
// - Offer acceptable conversion rates
const matchingDeposits = deposits.filter(d => 
    d.paymentMethods.includes(venmoHash) &&
    d.currencies[venmoHash].includes(usdHash) &&
    d.remainingDeposits >= desiredAmount &&
    d.conversionRates[venmoHash][usdHash] >= minAcceptableRate
);

Stage 2: Gating Service (Optional)

If the deposit has a intentGatingService, the buyer must obtain a signature:

Request Signature

// Buyer calls gating service API (off-chain)
const gatingRequest = {
    orchestrator: orchestratorAddress,
    escrow: escrowAddress,
    depositId: depositId,
    amount: intentAmount,
    to: buyerAddress,
    paymentMethod: venmoHash,
    fiatCurrency: usdHash,
    conversionRate: agreedRate,
    signatureExpiration: timestamp + 3600, // 1 hour validity
    chainId: chainId
};

const signature = await gatingService.requestSignature(gatingRequest);

Gating Service Validation

The gating service may:

Perform KYC/AML checks
Verify the buyer is on an allowlist
Check reputation scores
Rate-limit signaling frequency
Enforce geographic restrictions

If the deposit has no gating service (intentGatingService == address(0)), this stage is skipped.

Stage 3: Signal Intent

The buyer calls signalIntent() on the Orchestrator.

Transaction Flow

Code Example

IOrchestrator.SignalIntentParams memory params = IOrchestrator.SignalIntentParams({
    escrow: escrowAddress,
    depositId: depositId,
    amount: 1000e6,  // 1000 USDC
    to: buyerAddress,
    paymentMethod: keccak256("venmo"),
    fiatCurrency: keccak256("USD"),
    conversionRate: 1.02e18,  // 1.02 USD per USDC
    referrer: referrerAddress,
    referrerFee: 1e16,  // 1%
    gatingServiceSignature: signature,
    signatureExpiration: expiration,
    postIntentHook: IPostIntentHook(bridgeHook),
    data: bridgeHookData
});

orchestrator.signalIntent(params);

State Changes

Orchestrator:

Creates Intent struct with all parameters
Adds intent hash to accountIntents[buyer]
Stores intentMinAtSignal[intentHash] (deposit’s min amount at signal time)
Increments intentCounter

Escrow:

Validates deposit is accepting intents
Validates amount is within deposit’s intentAmountRange
Prunes expired intents if liquidity is needed
Moves amount from remainingDeposits to outstandingIntentAmount
Creates Intent struct with expiryTime = timestamp + intentExpirationPeriod
Adds intent hash to depositIntentHashes[depositId]

Validation Checks

The Orchestrator performs extensive validation:

Multiple Intent Check: Buyer must be whitelisted relayer OR allowMultipleIntents == true
Zero Address Check: to address must not be zero
Fee Validation: Referrer fee ≤ 50%, and must be 0 if no referrer
Hook Validation: If post-intent hook set, must be whitelisted
Escrow Validation: Must be whitelisted OR registry accepts all escrows
Payment Method: Must exist in PaymentVerifierRegistry and be active on deposit
Currency: Must be supported by payment method with non-zero min rate
Conversion Rate: Must be ≥ deposit’s min conversion rate
Gating Signature: If deposit has gating service, signature must be valid and not expired

Stage 4: Awaiting Payment

After signaling, the buyer has intentExpirationPeriod (configured on Escrow) to complete the off-chain payment.

Buyer Actions

Make Off-Chain Payment: Send fiat to the depositor’s payment account (Venmo username, PayPal email, etc.)
Include Intent Hash: Some payment methods allow notes/memos - buyer should include intent hash
Wait for Confirmation: Payment service confirms transaction

Intent Status

// Query intent on Orchestrator
IOrchestrator.Intent memory intent = orchestrator.getIntent(intentHash);

// Check if expired
IEscrow.Intent memory escrowIntent = escrow.getDepositIntent(depositId, intentHash);
bool isExpired = block.timestamp > escrowIntent.expiryTime;

Stage 5: Payment Attestation

Once the off-chain payment is confirmed, an attestation service generates a cryptographic proof.

Attestation Service Flow

Constructing the Attestation

// Extract from payment service
const paymentDetails = {
    method: keccak256("venmo"),
    payeeId: keccak256(depositorVenmoUsername),
    amount: 1020, // 1020 cents = $10.20
    currency: keccak256("USD"),
    timestamp: paymentTimestampMillis,
    paymentId: keccak256(venmoTransactionId)
};

// Fetch intent data
const intent = await orchestrator.getIntent(intentHash);

// Create snapshot
const intentSnapshot = {
    intentHash: intentHash,
    amount: intent.amount,
    paymentMethod: intent.paymentMethod,
    fiatCurrency: intent.fiatCurrency,
    payeeDetails: intent.payeeId,
    conversionRate: intent.conversionRate,
    signalTimestamp: intent.timestamp,
    timestampBuffer: 3600000  // 1 hour in milliseconds
};

// Calculate release amount (FX conversion)
const fiatPaidCents = paymentDetails.amount;
const fiatPaidUnits = fiatPaidCents / 100;  // 10.20 USD
const conversionRate = intent.conversionRate / 1e18;  // 1.02
const releaseAmount = Math.floor((fiatPaidUnits / conversionRate) * 1e6);  // USDC (6 decimals)

// Encode data
const data = ethers.utils.defaultAbiCoder.encode(
    ["tuple(bytes32,bytes32,uint256,bytes32,uint256,bytes32)", 
     "tuple(bytes32,uint256,bytes32,bytes32,bytes32,uint256,uint256,uint256)"],
    [paymentDetails, intentSnapshot]
);
const dataHash = keccak256(data);

// Construct EIP-712 digest
const domain = {
    name: "UnifiedPaymentVerifier",
    version: "1",
    chainId: chainId,
    verifyingContract: verifierAddress
};

const types = {
    PaymentAttestation: [
        { name: "intentHash", type: "bytes32" },
        { name: "releaseAmount", type: "uint256" },
        { name: "dataHash", type: "bytes32" }
    ]
};

const value = {
    intentHash: intentHash,
    releaseAmount: releaseAmount,
    dataHash: dataHash
};

// Sign with attestor private key(s)
const signature = await attestor._signTypedData(domain, types, value);

// Construct final attestation
const attestation = {
    intentHash: intentHash,
    releaseAmount: releaseAmount,
    dataHash: dataHash,
    signatures: [signature],  // Can be multiple for threshold attestation
    data: data,
    metadata: "0x"  // Optional additional data not signed
};

Stage 6: Fulfill Intent

Anyone can submit the attestation to fulfill the intent.

Transaction Flow

Code Example

IOrchestrator.FulfillIntentParams memory params = IOrchestrator.FulfillIntentParams({
    paymentProof: abi.encode(attestation),
    intentHash: intentHash,
    verificationData: "",  // Additional data for verifier (if needed)
    postIntentHookData: bridgeData  // Data for post-intent hook
});

orchestrator.fulfillIntent(params);

State Changes

Verifier:

Validates attestation signatures
Adds payment ID to NullifierRegistry
Emits PaymentVerified event

Orchestrator:

Deletes Intent from storage
Removes intent hash from accountIntents
Deletes intentMinAtSignal
Emits IntentPruned and IntentFulfilled events

Escrow:

Moves amount from outstandingIntentAmount back to available balance
Deletes Intent struct
Removes intent hash from depositIntentHashes
Transfers tokens to Orchestrator
May close deposit if dust threshold reached
Emits FundsUnlockedAndTransferred event

Fee Distribution

// Protocol fee (e.g., 1%)
protocolFeeAmount = (releaseAmount * protocolFee) / 1e18;
transfer(protocolFeeRecipient, protocolFeeAmount);

// Referrer fee (e.g., 1%)
referrerFeeAmount = (releaseAmount * intent.referrerFee) / 1e18;
transfer(intent.referrer, referrerFeeAmount);

// Net amount to buyer
netAmount = releaseAmount - protocolFeeAmount - referrerFeeAmount;
transfer(intent.to, netAmount);  // Or to post-intent hook

Alternative Paths

Path A: Cancellation

If the buyer changes their mind before making payment:

orchestrator.cancelIntent(intentHash);

Flow:

Orchestrator validates caller is intent owner
Orchestrator deletes intent from storage
Orchestrator calls escrow.unlockFunds(depositId, intentHash)
Escrow returns amount to remainingDeposits
Escrow deletes intent from storage

Use Cases:

Buyer found better rate elsewhere
Payment service is down
Buyer doesn’t have sufficient fiat balance

Path B: Expiration

If the intent is not fulfilled before expiryTime:

// Anyone can call to cleanup expired intents
escrow.pruneExpiredIntents(depositId);

Flow:

Escrow iterates through depositIntentHashes[depositId]
For each expired intent (block.timestamp > expiryTime):
- Return amount to remainingDeposits
- Delete intent from storage
- Remove from depositIntentHashes
- Emit FundsUnlocked event
Escrow calls orchestrator.pruneIntents(expiredIntents)
Orchestrator deletes each intent from storage

Automatic Pruning: Expired intents are automatically pruned when:

Depositor calls removeFunds() or withdrawDeposit()
New intent is signaled and liquidity is needed
Anyone calls pruneExpiredIntents()

Path C: Manual Release

If there’s a dispute or special arrangement, the depositor can manually release funds:

orchestrator.releaseFundsToPayer(intentHash);

Flow:

Orchestrator validates caller is the deposit’s depositor
Orchestrator deletes intent from storage
Orchestrator calls escrow.unlockAndTransferFunds() with full intent amount
Escrow transfers tokens to Orchestrator
Orchestrator calculates and transfers fees
Orchestrator transfers net amount to buyer
Emit IntentFulfilled(intentHash, to, netAmount, isManualRelease: true)

Security: Manual release still charges protocol and referrer fees. Depositors cannot bypass fee collection.

Intent States Summary

State	Description	Can Cancel?	Can Fulfill?	Liquidity
Signaled	Intent active, awaiting payment	Yes (owner)	Yes (anyone)	Locked
Expired	Past expiryTime, not yet pruned	No	No	Locked
Cancelled	Owner cancelled before fulfillment	N/A	N/A	Released
Fulfilled	Payment verified and released	N/A	N/A	Transferred
Pruned	Expired and cleaned up	N/A	N/A	Released
Released	Manually released by depositor	N/A	N/A	Transferred

Timeline Example

T=0:00    Buyer signals intent
          └─ Orchestrator: Intent created, hash = 0xabc...
          └─ Escrow: 1000 USDC locked

T=0:05    Buyer makes Venmo payment
          └─ Off-chain: $1020 sent to depositor

T=0:10    Attestation service detects payment
          └─ Off-chain: Verify payment matches intent
          └─ Off-chain: Generate EIP-712 signature

T=0:15    Relayer submits fulfillment
          └─ Orchestrator: verifyPayment()
          └─ Verifier: Validate attestation ✓
          └─ Nullifier: Add payment ID ✓
          └─ Escrow: Release 1000 USDC
          └─ Fees: 10 USDC protocol, 10 USDC referrer
          └─ Buyer receives: 980 USDC

T=0:15    Intent fulfilled ✓

Best Practices

Monitor Expiry

Buyers should complete payment well before expiryTime to account for attestation delays

Include Intent Hash

If payment service supports memos, include intent hash for faster attestation matching

Use Relayers

Buyers can outsource fulfillment submission to relayers to save gas and improve UX

Verify Deposit

Before signaling, verify deposit has sufficient liquidity and acceptable parameters

Orchestrator - Manages intent lifecycle
Escrow - Locks and releases liquidity
Payment Verification - Validates off-chain payments
Registry System - Whitelisting and configuration

Get Started

Core Concepts

Integration Guides

Deployment

Resources

Overview

Lifecycle Stages

Stage 1: Discovery

Stage 2: Gating Service (Optional)

Request Signature

Gating Service Validation

Stage 3: Signal Intent

Transaction Flow

Code Example

State Changes

Validation Checks

Stage 4: Awaiting Payment

Buyer Actions

Intent Status

Stage 5: Payment Attestation

Attestation Service Flow

Constructing the Attestation

Stage 6: Fulfill Intent

Transaction Flow

Code Example

State Changes

Fee Distribution

Alternative Paths

Path A: Cancellation

Path B: Expiration

Path C: Manual Release

Intent States Summary

Timeline Example

Best Practices

Monitor Expiry

Include Intent Hash

Use Relayers

Verify Deposit

Build docs developers (and LLMs) love

Get Started

Core Concepts

Integration Guides

Deployment

Resources

​Overview

​Lifecycle Stages

​Stage 1: Discovery

​Stage 2: Gating Service (Optional)

​Request Signature

​Gating Service Validation

​Stage 3: Signal Intent

​Transaction Flow

​Code Example

​State Changes

​Validation Checks

​Stage 4: Awaiting Payment

​Buyer Actions

​Intent Status

​Stage 5: Payment Attestation

​Attestation Service Flow

​Constructing the Attestation

​Stage 6: Fulfill Intent

​Transaction Flow

​Code Example

​State Changes

​Fee Distribution

​Alternative Paths

​Path A: Cancellation

​Path B: Expiration

​Path C: Manual Release

​Intent States Summary

​Timeline Example

​Best Practices

Monitor Expiry

Include Intent Hash

Use Relayers

Verify Deposit

​Related Contracts

Build docs developers (and LLMs) love

Overview

Lifecycle Stages

Stage 1: Discovery

Stage 2: Gating Service (Optional)

Request Signature

Gating Service Validation

Stage 3: Signal Intent

Transaction Flow

Code Example

State Changes

Validation Checks

Stage 4: Awaiting Payment

Buyer Actions

Intent Status

Stage 5: Payment Attestation

Attestation Service Flow

Constructing the Attestation

Stage 6: Fulfill Intent

Transaction Flow

Code Example

State Changes

Fee Distribution

Alternative Paths

Path A: Cancellation

Path B: Expiration

Path C: Manual Release

Intent States Summary

Timeline Example

Best Practices

Related Contracts