Cambrian CLI

Prerequisites

• node.js >= 22.0.0

• docker >= 20.0.0

Installing Cambrian utility

npm i --global @cambrianone/camb-client@latest

Initialization

Scaffold AVS and initialize PoA onchain

camb init -t avs <AVS directory>

Explaining wizard:

• Enter AVS IP address to bind to - provide an IP address to bind to, it should be reachable from all the operators

• Enter AVS HTTP port to bind to - provide an HTTP port to bind to, it should be reachable from all the operators

• Enter AVS WS port to bind to - provide a WebSockers port to bind to, it should be reachable from all the operators

• Enter admin private key or press enter to generate a new one - admin private key / keypair as array of uint8 or as base58-encoded string

• Enter Solana API URL or press enter to use default - Solana JSON RPC endpoint

• Enter Solana API WS URL or press enter to use default - Solana WebSockets endpoint

• Enter Cambrian Consensus Program name or press enter to generate a new one - string identifier (name) of the Cambrian Consensus Program (CCP) instance (aka PoA name)

• Enter proposal storage key or press enter to generate a new one - unique string key for the proposal storage

• Enter storage space - common oracle storage space, in bytes

• Enter consensus threshold - The minimum number of operators required to approve a proposal before execution

• Enter stake threshold - The minimum stake required for an operator to participate in CCP

List installed AVS instances

camb avs list

Start AVS:

camb avs run -u <AVS pubkey>

Scaffold operators and initialize them onchain

Updating oracle data

There are 4 ways of updating oracle data:

• [RECOMMENDED] Streaming container (container-stream option while scaffolding operator) - container periodically writes string data to stdout, operator stores this chunks of data on-chain

• Running container (container-run option while scaffolding operator) - operator starts container with periods specified by a cron spec. Container should write some string data into stdout and then it exits with code 0. Operator stores this data on-chain.

Build Oracle Update Container image:

git clone https://github.com/cambrianone/oracle-update-examples
cd ./oracle-update-examples/current-date/container-stream
docker build -t oracle-update-current-date .

Scaffolding operators

Before scaffolding the operators make sure instance of AVS is already running.

camb init -t operator <operator 1 directory>
camb init -t operator <operator 2 directory>
camb init -t operator <operator 3 directory>

Explaining wizard:

• Enter AVS HTTP URL - AVS HTTP endpoint

• Enter AVS WS URL - AVS WebSockets endpoint

• Enter oracle update method - one of the oracle update methods explained in Updating oracle data

• Enter image for oracle update container - image name for the oracle update container (oracle-update-current-date from the example in Updating oracle data)

• Enter cron specification for oracle update (applicable to container-run update method) - CRON specification for running oracle update container

• Enter optional command for oracle update container - (optional) command for running oracle update container

• Enter optional env for oracle update container - (optional) environment for oracle update container in format VAR1=VAL1 VAR2=VAL2

Running components

List installed operator nodes (outputs voter public keys)

camb operator list -a <AVS public key>

Start operators:

camb operator run -u <voter public key>

• After start each operator run its own Oracle Datasource Container (ODC)

• ODC streams string data into stdout. Every chunk of this data operator will store onchain invoking Oracle Program

Executing proposal

Running payload

There are two ways of executing payload:

• From a container (recommended way, using camb payload run-container command)

• From a typescript/javascript code (deprecated way, using camb payload run-file)

Container receives a parameter serialized as JSON-object. It's type is:

type TPayloadInput = {
  executorPDA: string;
  apiUrl: string;
  extraSigners: Array<string>;
  poaName: string;
  proposalStorageKey: string;
}

extraSigners represents an optional array of serialized private keys used for signing transaction.

Container should write a JSON-stringified object. It's type is:

type TPayloadOutput = {
  proposalInstructions: Array<{
    accounts: Array<{
      address: string;
      role: 0 | 1 | 2 | 3    
    }>,
    data: string;
    programmAddress: string;
  }>;
}

where data is base58-serialized data buffer and role is the following enum:

enum AccountRole {
    // Bitflag guide: is signer ⌄⌄ is writable
    WRITABLE_SIGNER = /* 3 */ 0b11,
    READONLY_SIGNER = /* 2 */ 0b10,
    WRITABLE =        /* 1 */ 0b01,
    READONLY =        /* 0 */ 0b00,
}

Build payload container image

git clone https://github.com/cambrianone/payload-images
cd ./payload-images/check-oracle
docker build -t payload-check-oracle .

Run payload

Send image name of payload container from the previous step (payload-check-oracle) to the AVS instance

camb payload run-container -a <AVS public key | AVS URL> -p [period in seconds] payload-check-oracle

• AVS broadcasts payload container image name to running operators

• Operators run payload containers

• Payload containers return proposal instructions

• Operators invoke handle_proposal instruction in PoA program with these proposal instructions

• If -p/--period option has been specified, this command will run handling a repeatable proposal with specified locking period (which means you cannot execute another proposal within this period). Otherwise this command will run one-shot proposal (which means you can only execute a proposal once).