Skip to main content

​
ProtocolViewer Contract

The ProtocolViewer is a utility contract that provides convenient view functions to query deposit and intent data from the Escrow and Orchestrator contracts. It aggregates data from multiple contracts into structured views.

​
Overview

  • Contract: ProtocolViewer.sol
  • Inherits: IProtocolViewer
  • Purpose: Aggregates and provides structured views of deposits and intents

​
Key State Variables

​
escrowContract
IEscrow
required
Immutable reference to the Escrow contract
​
orchestrator
IOrchestrator
required
Immutable reference to the Orchestrator contract

​
Constructor

constructor(address _escrow, address _orchestrator)
​
_escrow
address
required
Address of the Escrow contract
​
_orchestrator
address
required
Address of the Orchestrator contract

​
View Functions

​
getDeposit

Gets details for a single deposit including payment methods, currencies, and available liquidity.
​
_depositId
uint256
The ID of the deposit
function getDeposit(uint256 _depositId) 
    public view 
    returns (IProtocolViewer.DepositView memory depositView)
​
depositId
uint256
The deposit ID
​
deposit
IEscrow.Deposit
The core deposit struct from Escrow
​
availableLiquidity
uint256
Total available liquidity (remainingDeposits + reclaimable from expired intents)
​
paymentMethods
PaymentMethodDataView[]
Array of payment method configurations including:
  • paymentMethod: Payment method identifier
  • verificationData: Payment verification data
  • currencies: Array of supported currencies with min conversion rates
​
intentHashes
bytes32[]
Array of active intent hashes for this deposit
Example: 
IProtocolViewer.DepositView memory depositView = viewer.getDeposit(1);
console.log("Available liquidity:", depositView.availableLiquidity);
console.log("Number of payment methods:", depositView.paymentMethods.length);

​
getDepositFromIds

Gets deposit details for a list of deposit IDs.
​
_depositIds
uint256[]
Array of deposit IDs
function getDepositFromIds(uint256[] memory _depositIds) 
    external view 
    returns (IProtocolViewer.DepositView[] memory depositArray)
Example: 
uint256[] memory depositIds = new uint256[](3);
depositIds[0] = 1;
depositIds[1] = 2;
depositIds[2] = 5;

IProtocolViewer.DepositView[] memory deposits = viewer.getDepositFromIds(depositIds);
for (uint256 i = 0; i < deposits.length; i++) {
    console.log("Deposit", deposits[i].depositId, "liquidity:", deposits[i].availableLiquidity);
}

​
getIntent

Gets details for a single intent including the associated deposit.
​
_intentHash
bytes32
The hash of the intent
function getIntent(bytes32 _intentHash) 
    public view 
    returns (IProtocolViewer.IntentView memory intentView)
​
intentHash
bytes32
The intent hash
​
intent
IOrchestrator.Intent
The intent struct from Orchestrator containing:
  • owner: Intent owner address
  • to: Recipient address
  • escrow: Escrow contract address
  • depositId: Associated deposit ID
  • amount: Intent amount
  • paymentMethod: Payment method identifier
  • fiatCurrency: Fiat currency code
  • conversionRate: Conversion rate
  • payeeId: Payee identifier
  • timestamp: Creation timestamp
  • referrer: Referrer address
  • referrerFee: Referrer fee amount
  • postIntentHook: Post-intent hook address
  • data: Additional hook data
​
deposit
DepositView
Full deposit view for the deposit associated with this intent
Example: 
IProtocolViewer.IntentView memory intentView = viewer.getIntent(intentHash);
console.log("Intent owner:", intentView.intent.owner);
console.log("Intent amount:", intentView.intent.amount);
console.log("Deposit liquidity:", intentView.deposit.availableLiquidity);

​
getIntents

Gets details for a list of intent hashes.
​
_intentHashes
bytes32[]
Array of intent hashes
function getIntents(bytes32[] calldata _intentHashes) 
    external view 
    returns (IProtocolViewer.IntentView[] memory intentArray)
Example: 
bytes32[] memory intentHashes = new bytes32[](2);
intentHashes[0] = intentHash1;
intentHashes[1] = intentHash2;

IProtocolViewer.IntentView[] memory intents = viewer.getIntents(intentHashes);
for (uint256 i = 0; i < intents.length; i++) {
    console.log("Intent", i, "amount:", intents[i].intent.amount);
}

​
getAccountIntents

Gets the active intents for a specific account.
​
_account
address
The account address
function getAccountIntents(address _account) 
    external view 
    returns (IProtocolViewer.IntentView[] memory intentViews)
Example: 
IProtocolViewer.IntentView[] memory myIntents = viewer.getAccountIntents(msg.sender);
console.log("I have", myIntents.length, "active intents");
for (uint256 i = 0; i < myIntents.length; i++) {
    console.log("Intent", i, "expires at:", 
        IEscrow(myIntents[i].intent.escrow).getDepositIntent(
            myIntents[i].intent.depositId, 
            myIntents[i].intentHash
        ).expiryTime
    );
}

​
Data Structures

​
DepositView

struct DepositView {
    uint256 depositId;
    IEscrow.Deposit deposit;
    uint256 availableLiquidity;
    PaymentMethodDataView[] paymentMethods;
    bytes32[] intentHashes;
}

​
PaymentMethodDataView

struct PaymentMethodDataView {
    bytes32 paymentMethod;
    IEscrow.DepositPaymentMethodData verificationData;
    IEscrow.Currency[] currencies;
}

​
IntentView

struct IntentView {
    bytes32 intentHash;
    IOrchestrator.Intent intent;
    DepositView deposit;
}

​
Use Cases

​
Frontend Integration

The ProtocolViewer is ideal for frontend applications to:
  1. Display deposit listings with all payment methods and available liquidity
  2. Show intent details with full context about the underlying deposit
  3. Track user activity by fetching all active intents for an account
  4. Batch data fetching to reduce RPC calls

​
Example: Building a Deposit Explorer

// Get all deposits for an array of IDs
uint256[] memory depositIds = [1, 2, 3, 4, 5];
IProtocolViewer.DepositView[] memory deposits = viewer.getDepositFromIds(depositIds);

// Filter deposits with sufficient liquidity
for (uint256 i = 0; i < deposits.length; i++) {
    if (deposits[i].availableLiquidity >= minAmount && 
        deposits[i].deposit.acceptingIntents) {
        // Display this deposit to users
        displayDeposit(deposits[i]);
    }
}

​
Example: User Dashboard

// Get all user's active intents with full context
IProtocolViewer.IntentView[] memory myIntents = viewer.getAccountIntents(userAddress);

// Display each intent with deposit information
for (uint256 i = 0; i < myIntents.length; i++) {
    IntentView memory intentView = myIntents[i];
    
    console.log("Intent Amount:", intentView.intent.amount);
    console.log("Conversion Rate:", intentView.intent.conversionRate);
    console.log("Deposit Token:", address(intentView.deposit.deposit.token));
    console.log("Available Liquidity:", intentView.deposit.availableLiquidity);
}

​
Best Practices

  1. Batch Queries: Use getDepositFromIds and getIntents to fetch multiple records in a single call
  2. Check Availability: Always check availableLiquidity and acceptingIntents before allowing users to signal intents
  3. Cache Results: The view functions are read-only, so results can be cached for a short period to reduce RPC load
  4. Gas Optimization: For very large arrays, consider implementing pagination on your frontend

Build docs developers (and LLMs) love

Get started for freeTalk to us