ProtocolViewer

Utility contract for querying deposit and intent data

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