SP1 Vector

Overview

Implementation of zero-knowledge proof circuits for Vector, Avail's Data Attestation Bridge in SP1.

  • /program: The SP1 Vector program.
  • /primitives: Libraries for types and helper functions used in the program.
  • /script: Scripts for getting the contract's genesis parameters and deploying the operator to update the light client.
  • /services: RPC fetcher for the script + the justification indexer.
  • /contracts: The contract's source code and deployment scripts.
  • /query: Contains the logic for querying data root proofs from the contracts. Automatically deploys to https://vectorx-query.succinct.xyz.

Components

An SP1 Vector implementation has a few key components:

  • An SP1Vector contract. Contains the logic for verifying SP1 Vector proofs, storing the latest data from the Avail chain, including the headers and data commitments. Matches the interface of the existing VectorX contract so it can be upgraded in-place.
  • An SP1Verifier contract. Verifies arbitrary SP1 programs. Most chains will have canonical deployments upon SP1's mainnet launch. Until then, users can deploy their own SP1Verifier contracts to verify SP1 programs on their chain. The SP1 Vector implementation will use the SP1Verifier contract to verify the proofs of the SP1 Vector programs.
  • The SP1 Vector program. An SP1 program that verifies the transition between two Avail headers and computes the data commitment of the intermediate blocks.
  • The operator. A Rust script that fetches the latest data from a deployed SP1Vector contract and an Avail chain, determines the block to request, requests for/generates a proof, and relays the proof to the SP1Vector contract.

Deployment

Overview

Here's how to deploy an SP1 Vector contract for an Avail chain.

Steps

  1. To deploy an SP1 Vector contract for an Avail chain do the following.

    Get the genesis parameters for the SP1Vector contract.

    cd script

# Example with Avail Turing Testnet.
AVAIL_URL=wss://turing-rpc.avail.so/ws cargo run --bin genesis --release

  2. Add the genesis parameters to /contracts/.env mirroring contracts/.env.example.

    | Parameter | Description | |-----------|-------------| | GENESIS_HEIGHT | The block height of the genesis block for the Avail chain | | GENESIS_HEADER | The header of the genesis block for the Avail chain | | GENESIS_AUTHORITY_SET_ID | The ID of the initial authority set for the Avail chain | | GENESIS_AUTHORITY_SET_HASH | The hash of the initial authority set for the Avail chain | | SP1_VECTOR_PROGRAM_VKEY | The verification key for the SP1 Vector program | | HEADER_RANGE_COMMITMENT_TREE_SIZE | The size of the Merkle tree used for header range commitments (Default 1024) |

  3. Deploy the SP1Vector contract with genesis parameters.

    cd ../contracts

forge install

SP1_PROVER={mock, network} CHAINS=sepolia forge script script/Deploy.s.sol --private-key $PRIVATE_KEY --multi --broadcast --verify

    If you see the following error, add --legacy to the command.

    Error: Failed to get EIP-1559 fees

  4. Your deployed contract address will be printed to the terminal.

    == Return ==
0: address <SP1_VECTOR_ADDRESS>

    This will be used when you run the operator in step 5.

  5. Export your SP1 Prover Network configuration

    # Export the PRIVATE_KEY you will use to relay proofs.
export PRIVATE_KEY=<PRIVATE_KEY>

# Optional
# If you're using the Succinct network, set SP1_PROVER to "network". Otherwise, set it to "local" or "mock".
export SP1_PROVER={network|local|mock}
# Only required if SP1_PROVER is set "network".
export SP1_PRIVATE_KEY=<SP1_PRIVATE_KEY>

  6. Run the SP1 Vector operator to update the LC continuously.

    cd ../script

AVAIL_URL=wss://turing-rpc.avail.so/ws AVAIL_CHAIN_ID=turing CHAIN_ID=11155111 RPC_URL=https://ethereum-sepolia.publicnode.com/ CONTRACT_ADDRESS=<SP1_VECTOR_ADDRESS> VECTORX_QUERY_URL=https://vectorx-query.succinct.xyz
cargo run --bin operator --release

Demo Contract

An example contract using SP1 Vector can be found on Sepolia here.

Query Data Root Proofs

Overview

Whenever a new data root commitment is stored on-chain, the merkle proofs need to be made available for end-users to prove the data root's of blocks within those data commitments. This service listens for data root commitment events on-chain and stores the merkle proofs for each data root in the range, which is then exposed via a separate endpoint.

The indexed contracts are configured in deployments.json.

RPC Queries

Query for dataRoot Proof Data

Querying with a block number.

https://vectorx-query.succinct.xyz/api?chainName=hex&contractChainId=11155111&contractAddress=0xbc281367e1F2dB1c3e92255AA2F040B1c642ec75&blockNumber=247230

Example response:

{
  "data": {
    "blockNumber": 247230,
    "rangeHash": "0xafad54e98bdaebacc1f220dd919dda48b84ed0689906c288a4d93dae1ae9d7c5",
    ...
  }
}

Querying with a block hash.

https://vectorx-query.succinct.xyz/api?chainName=hex&contractChainId=11155111&contractAddress=0xbc281367e1F2dB1c3e92255AA2F040B1c642ec75&blockHash=0xad664ed32323c70e9c19333f6d7d6f855719f439bc0cb4cd92d89138c252d560

Example response:

{
  "data": {
    "rangeHash": "0xafad54e98bdaebacc1f220dd919dda48b84ed0689906c288a4d93dae1ae9d7c5",
    "dataCommitment": "0x7b0f5743191b390b3ba21cdda41b3940b37566a9f336b9e37cf0ad94c937242a",
    ...
  }
}

Health of the VectorX contract

Querying for the health of the VectorX contract deployed on Sepolia (chain ID: 11155111) at address 0xbc281367e1F2dB1c3e92255AA2F040B1c642ec75.

https://vectorx-query.succinct.xyz/api/health?chainName=hex&contractChainId=11155111&contractAddress=0xbc281367e1F2dB1c3e92255AA2F040B1c642ec75

Example response:

{"data":{"logEmitted":true,"ethBlocksSinceLastLog":35,"lastLogTimestamp":1717707768,"blocksBehindHead":50}}

Note: If logEmitted is false, the contract has not emitted a log in at least the last ethBlocksSinceLastLog blocks.

Range of the VectorX contract

Querying for the range of the VectorX contract deployed on Sepolia (chain ID: 11155111) at address 0xbc281367e1F2dB1c3e92255AA2F040B1c642ec75.

https://vectorx-query.succinct.xyz/api/range?contractChainId=11155111&contractAddress=0xbc281367e1F2dB1c3e92255AA2F040B1c642ec75

Example response:

{"data":{"start":63091,"end":304710}}

Launch the Query Service

Update query/.env with the corresponding variables from .env.example. Then launch the service with:

npm run dev

Deployed Contracts

You can find a list of actively deployed contracts in this deployments.json.

Reproducible Builds

Overview

When deploying SP1 Vector in production, it's important to ensure that the program used when generating proofs is reproducible.

Prerequisites

You first need to install the cargo prove toolchain.

Ensure that you have the latest version of the toolchain by running:

sp1up

Confirm that you have the toolchain installed by running:

cargo prove --version

Verify the SP1 Vector binary

To build the SP1 Vector binary, first ensure that Docker is running.

docker ps

Then build the binaries:

cd program

# Builds the SP1 Vector binary using the corresponding Docker tag, output directory and ELF name.
cargo prove build --docker --tag v3.0.0 --output-directory ../script --elf-name sp1-vector-docker

Now, verify the binaries by confirming the output of vkey matches the vkeys on the contract. The vkey program outputs the verification key based on the ELF in /elf.

cargo run --bin vkey --release