Solidity SDK

SDK for verifying certificates generated by pod validators.

Introduction

The pod Solidity SDK enables smart contracts to verify pod transaction receipts and validator attestations on another EVM-based chain, such as Ethereum. This document provides a comprehensive reference for the SDK's verification capabilities, including aggregate signature verification and merkle proof validation.

Core Components

Receipt Verification

The SDK centers around the verification of pod network receipts, which contain both transaction data and validator attestations. The receipt data is organized in a merkle tree structure, with validator signatures attesting to the root hash of this tree.

Verification Interface

The IPodVerifier interface provides three core verification methods:

Attestation Verification

function verifyCertificate(
    bytes32 receiptHash, 
    bytes calldata aggregateSignature,
    uint256 bitmask
) external pure returns (bool);

Parameters:

• receiptHash: The hash of the receipt that was signed

• aggregateSignature: The aggregate signature generated by the committee of pod validators.

• bitmask: A bitmask signifying which validators signed the aggregate signature. The first bit is 1 if the first validator signed the receipt, otherwise 0, The second bit for the second validator, etc.

Returns:

• bool: True if the attestation is valid

Errors:

• InvalidSignature: Aggregate signature verification failed

• Insufficient: Committee quorum size was not reached

This method verifies that a receipt has received a sufficient number of valid signatures from the current validator committee.

Log Verification

function verifyLog(
    bytes32 receiptHash,
    bytes32 logHash,
    uint256 logIndex,
    bytes32[] calldata proof
) external pure returns (bool);

Parameters:

• receiptHash: The hash of the transaction receipt containing the log

• logHash: The hash of the log (containging addres, topics and data).

• logIndex: Index of the log to verify

• proof: Merkle proof for the log

Returns:

• bool: True if the log proof is valid

Errors:

• InvalidProof: Merkle proof verification failed

• InvalidLogIndex: Log index is out of bounds

This method verifies individual event logs within a receipt using their index and a merkle proof.

Field Verification

function verifyField(
    Receipt calldata receipt,
    uint256 generalizedIndex, 
    bytes32 expectedValue,
    bytes32[] calldata proof
) external pure returns (bool);

Parameters:

• receipt: The transaction receipt containing the field

• generalizedIndex: Position of the field in the receipt tree

• expectedValue: Expected hash of the field value

• proof: Merkle proof for the field

Returns:

• bool: True if the field proof is valid

Errors:

• InvalidProof: Merkle proof verification failed

• InvalidGeneralizedIndex: Invalid generalized index

This method enables verification of any field in the receipt using its generalized index in the merkle tree.

Error Handling

The SDK defines the following standard error conditions:

error InvalidSignatures();         // Aggregate signature validation failed
error InvalidProof();             // Merkle proof validation failed  
error InvalidLogIndex();          // Log index out of bounds
error InvalidGeneralizedIndex();   // Invalid generalized index
error InvalidQuorumSize();        // Invalid committee quorum size

Implementation Guidelines

A complete implementation of receipt verification should:

1. First verify the aggregate signature using verifyAttestation()

2. Then verify any specific fields or logs using the appropriate verification method

3. Only proceed with receipt processing if all verifications succeed

Security Considerations

Developers implementing receipt verification should:

1. Always validate both attestations and proofs before accepting a receipt as valid.

2. Ensure the committee data matches the current validator set.

3. Validate that quorum requirements meet network specifications.

4. Use correct generalized indices when verifying specific fields.

5. Implement proper error handling for all verification failure cases.

6. Maintain secure access controls for any contracts implementing verification.

Dependencies

The SDK requires:

• Solidity compiler version 0.8.12 or later

External Resources

• GitHub Repository: https://github.com/pod-network/solidity-sdk