Skip to main content

Integeration Docs

Welcome to the LayerEdge Integeration Documentation. This comprehensive guide will help you integrate LayerEdge's Aggregation & Verification Layer into your applications and workflows.

Overview​

LayerEdge provides powerful integeration capabilities for developers looking to leverage our high-throughput architecture and verification system. This documentation covers various integeration scenarios and provides step-by-step guides for implementation.

Best Practices​

When integrating with LayerEdge, consider the following best practices:

  1. Security First: Always implement proper authentication and authorization
  2. Error Handling: Implement robust error handling and retry mechanisms
  3. Performance Optimization: Utilize LayerEdge's high-throughput capabilities efficiently
  4. Testing: Thoroughly test your integerations in development environments

Integrating Your Protocol with LayerEdge's Aggregation & Verification Layer​

This guide lives both in this repository and in a dedicated integerations repository. For the Rust Block Reader codebase, see the canonical repo:

  • https://github.com/Layer-Edge/rust-block-reader

Access & Billing​

The LayerEdge Sandbox provides a safe, isolated environment for testing and development:

  1. Sandbox Access:

    • Contact the LayerEdge team to request sandbox access
    • Reach out via Discord or GitHub
    • Access is free and requires no payment setup
    • Perfect for testing integrations without affecting mainnet

  2. Sandbox Features:

    • Full API functionality in a test environment
    • Testnet Bitcoin anchoring
    • Mock payment processing
    • Comprehensive logging and debugging tools
    • Rate limits designed for development

  3. Getting Started in Sandbox:

    • API endpoints and authentication credentials are provided by the team
    • You'll receive specific connection details after approval
    • All testing can be done safely in the isolated sandbox environment

Production API Key​

For production deployments:

  • Obtain an API key from LayerEdge to authorize submissions and ingestion requests
  • Create a wallet for payment in edgen so your proofs can be included
  • We recommend connecting with the LayerEdge team to finalize access, quotas, and settlement details before going live

Important: Always start with the Sandbox environment before moving to production!

What You Provide​

  • zk-proof artifacts or references to fetch (contract events, RPC endpoints)
  • Chain IDs, RPC URLs/methods for block/header retrieval
  • Contract addresses and event signatures (if event-driven)
  • Any authentication requirements (API keys, headers)

Integeration Options​

  1. REST push
  • Run: cargo run -- --mode REST
  • POST block numbers:
curl -X POST http://localhost:8080/add-block-by-number/12345
  1. Polling loop
  • Run: cargo run -- --mode LOOP
  • Configure block_fetch_params in src/main.rs
  1. Hybrid
  • Run: cargo run -- --mode BOTH

Extend the Reader for Your Protocol​

  • Add RPC-based fetch entries to block_fetch_params
  • Add contract-event entries and decode in src/block_reader.rs
  • Add SDK-based ingestion branches if you have a Rust SDK

Example contract entry:

(
    "contract",
    "yourchain",
    12345,
    "https://rpc.your.io",
    "YourEventName",
    "0xContractAddress",
    None,
),

Data Contracts​

  • Block number/hash formats, proof-root/commitment encoding, event ABI topics and fields

Testing​

  • TEST mode: cargo run -- --mode TEST
  • REST smoke test: cargo run -- --mode REST then POST
  • Loop validation: cargo run -- --mode LOOP

Operations​

  • Persistence under block_numbers/
  • Backoff between requests and cycles
  • Errors are logged; loop continues

Integrating Your Protocol with LayerEdge's Aggregation & Verification Layer​

This guide explains how to integrate a new protocol so LayerEdge can ingest your zk proofs and accompanying on-chain signals (headers, merkle roots, events) using this Rust Block Reader.

What You Provide​

  • zk-proof artifacts or references to fetch them (e.g., contract events, RPC endpoints)
  • Chain identifiers, RPC endpoints, and methods for block or header retrieval
  • Contract addresses and event signatures (if event-driven)
  • Any authentication requirements (API keys, headers)

Access & Billing​

  • Obtain an API key from LayerEdge to authorize your submissions and ingestion requests.
  • Create a wallet for payment in edgen so your proofs can be included in the Aggregation & Verification Layer.
  • We recommend you connect with the LayerEdge team to finalize access, quotas, and settlement details before going live.

Integeration Options​

You can integrate via one or more of the following:

  1. REST push (simple)
  • Run the reader in REST mode: cargo run -- --mode REST
  • POST block numbers to enqueue processing:
curl -X POST http://localhost:8080/add-block-by-number/12345
  1. Polling loop (hands-off)
  • Run loop mode: cargo run -- --mode LOOP
  • Configure your chain(s) under block_fetch_params in src/main.rs
  1. Hybrid
  • Run both REST and Loop: cargo run -- --mode BOTH

Extending the Reader for Your Protocol​

Most integerations boil down to one or more of these:

  • Add/modify an RPC-based fetch entry
  • Add contract-event based ingestion
  • Add SDK-based ingestion if your protocol exposes a Rust SDK

1) RPC-based block/header fetch​

In src/main.rs, add an entry to block_fetch_params with your chain info:

(
    "rpc",                // type: "rpc" | "sdk" | "contract"
    "yourchain",          // short chain name
    12345,                 // chain id
    "https://rpc.your.io",// rpc url
    "eth_getBlockByNumber",// method or equivalent
    "",                   // unused for rpc
    None,                  // optional auth token
),

The reader calls into block_reader.rs → rpc_call.rs to fetch block hashes/headers. Update method names if your chain uses a non-EVM API (e.g., Tendermint/Celestia style endpoints).

2) Contract event-based ingestion​

Add a "contract" entry with your contract/event metadata:

(
    "contract",
    "yourchain",
    12345,
    "https://rpc.your.io",
    "YourEventName",      // e.g., L2MerkleRootAdded
    "0xContractAddress",  // event emitting contract
    None,                  // optional auth
),

Then implement or adapt the event reader in src/block_reader.rs to decode your event and extract the zk-proof root or commitment your verification pipeline needs.

3) SDK-based ingestion​

If you have a Rust SDK, add an entry of type "sdk" and implement a branch in src/block_reader.rs to use your SDK to fetch the required signals.

Data Contracts​

  • Block identifier: hex or decimal number as string (e.g., "0xabc..." or "12345")
  • Block hash: 32-byte hash hex (0x-prefixed)
  • Proof-root / commitment: hex or field element encoding used by your proof system
  • Event ABI: include topic signature and field types if EVM-compatible

Security & Auth​

Sandbox Authentication​

The Sandbox environment requires authentication tokens and API endpoints provided by the LayerEdge team:

# Sandbox API calls (credentials provided by team)
curl -X POST [SANDBOX_ENDPOINT] \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [TEAM_PROVIDED_TOKEN]" \
  -d '{"proof_data": "your_proof_here", "chain_id": "sandbox"}'

Production Authentication​

For production deployments:

  • Prefer read-only RPC keys with least privilege
  • For private endpoints, pass an auth token in the block_fetch_params tuple; wire it through rpc_call.rs
  • Validate and sanitize any data before forwarding to the aggregation layer
  • Use API keys for authenticated requests:
# Production API calls (authentication required)
curl -X POST https://api.layeredge.io/v1/submit-proof \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"proof_data": "your_proof_here", "chain_id": "mainnet"}'

Testing Your Integration​

Before testing locally, use the LayerEdge Sandbox:

  1. Sandbox API Testing:
# Test basic connectivity (credentials provided by team)
curl -X GET [SANDBOX_ENDPOINT]/status \
  -H "Authorization: Bearer [TEAM_PROVIDED_TOKEN]"

# Submit a test proof
curl -X POST [SANDBOX_ENDPOINT]/submit-proof \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [TEAM_PROVIDED_TOKEN]" \
  -d '{
    "proof_data": "test_proof_12345",
    "chain_id": "sandbox",
    "block_number": "12345"
  }'
  1. Sandbox Integration Validation:
    • Verify your proof format is accepted
    • Test error handling with invalid data
    • Monitor sandbox logs for debugging
    • Validate response formats match expectations

Local Testing​

After sandbox validation, test locally:

  1. Local run
cargo run -- --mode TEST
  • Adapt Mode::TEST in src/main.rs to exercise your fetch path
  1. REST smoke test
cargo run -- --mode REST
curl -X POST http://localhost:8080/add-block-by-number/12345
  1. Loop validation
cargo run -- --mode LOOP
  • Observe logs; ensure block hashes or proof roots are discovered and forwarded

Operational Notes​

  • Persistence: last processed block numbers are stored under block_numbers/
  • Backoff: loop mode sleeps briefly between requests and between cycles
  • Errors: network or decoding errors are logged and the loop continues

Checklist​

  • Chain ID and RPC URL added to block_fetch_params
  • Event contract and signature configured (if applicable)
  • Decoding logic implemented in block_reader.rs
  • Auth handled in rpc_call.rs (if needed)
  • Local tests pass in TEST/REST/LOOP modes