Validator Bonds

Mono repository for Validator Bonds product

Repository structure

• programs/validator-bonds - Anchor on-chain contract project
• packages/ - TypeScript packages related to on-chain program (SDK, CLI)
• api/ - in Rust developed OpenAPI service that publishes bonds data (API endpoint)
• .buildkite/ - automated pipelines that prepare data for bonds claiming, updating API data and similar
• settlement-engine/ - code for a CLI creating protected event data that is published in form of JSON and packed as a settlement on-chain
• merkle-tree/ - generic Rust library implementing the merkle tree data structure management
• migrations/ - SQL scripts to prepare and change DB schemas
• scripts/ - scripts used in pipeline and to manage and integrate various repository parts
• validator-bonds-cli - CLI used by operator to manage bonds (user related CLI is packages/CLI)
• settlement-pipelines - a set of CLI binaries that works as a pipeline off-chain management for the Validator Bonds Program

Validator Bonds Programs Flow

The system works with flow of data. The flow is encoded in code within buildkite pipelines

• scheduler checks the epoch and makes processing happens each one
• copy-parsed-snapshot gets data from gs://marinade-solana-snapshot-mainnet
• prepare-claims creates JSON data that reflects the protected events based on the performance of validators, the data is stored at GCloud (data is publicly available but google login is required) at https://console.cloud.google.com/storage/browser/marinade-validator-bonds-mainnet
• init-settlements the Settlement accounts are created based on the generated JSON data, settlements are created by public key bnwBM3RBrvnVmEJJAWEGXe81wtkzGvb9MMWjXcu99KR
• claim-settlements claiming the Settlement accounts to provides SOLs to holders affected by protected events

Development

User related CLI from source

To run the CLI you need to have installed Node.js in version 16+ and pnpm. For details on CLI options see validator-bonds-cli README.

# installing TS dependencies
pnpm install
# run CLI
pnpm cli --help

Validator Bonds data loading CLI

cargo build --release

# Collect bonds data in YAML format
./target/release/validator-bonds-cli \
  collect-bonds -u "$RPC_URL" > bonds.yaml

# Store YAML bonds data to a POSTGRES DB
./target/release/validator-bonds-api-cli \
  store-bonds --postgres-url "$POSTGRES_URL" --input-file bonds.yaml

Validator Bonds API

cargo build --release

# Run API on port 8000 (default) or set a custom one using --port
./target/release/api \
  --postgres-url "$POSTGRES_URL"

On-Chain related parts

For details for on-chain part see validator-bonds README.

Contract audits:

• Neodyme, tag contract-v1.4.0, commit 7e6d35e, see audit document

For information on tracking on-chain transactions, refer to the On-Chain Analysis document.

To build the Anchor program use the scripts of the pnpm.

# install TS dependencies
pnpm install

# building Anchor program + cli and sdk TS packages
pnpm build

# testing the SDK+CLI against the bankrun and local validator
pnpm test
# running single cargo test
cargo test --package protected-event-distribution ts_cross_check_hash_generate
# bankrun part of the tests
pnpm test:bankrun
# local validator part of the tests
pnpm test:validator
# cargo tests in rust code
pnpm test:cargo

Contract deployment

VERSION='v'`grep version programs/validator-bonds/Cargo.toml | sed 's/.*"\([^"]\+\)".*/\1/'`
echo "Building version $VERSION"
anchor build --verifiable \
  --env "GIT_REV=`git rev-parse --short HEAD`" --env "GIT_REV_NAME=${VERSION}"

# 1. DEPLOY
## deploy (devnet, hot wallet upgrade)
solana program deploy -v -ud \
   --program-id vBoNdEvzMrSai7is21XgVYik65mqtaKXuSdMBJ1xkW4 \
   -k [fee-payer-keypair]
   --upgrade-authority [path-to-keypair] \
   ./target/verifiable/validator_bonds.so

# deploy (mainnet, SPL Gov authority multisig, governance 7iUtT...wtBZY)
# NOTE: solana version 1.18.x; `--with-compute-unit-price --use-rpc --use-quic` fixing the congestion of the network
#       check the latest available Solana client version at https://docs.solanalabs.com/cli/install
solana -um -k [fee-payer-keypair] \
    program write-buffer target/verifiable/validator_bonds.so \
    --with-compute-unit-price 10 \
    --use-rpc --use-quic
solana -um -k [fee-payer-keypair] \
    program set-buffer-authority \
    --new-buffer-authority 6YAju4nd4t7kyuHV6NvVpMepMk11DgWyYjKVJUak2EEm <BUFFER_PUBKEY>


# 2. IDL UPDATE, idl account Du3XrzTNqhLt9gpui9LUogrLqCDrVC2HrtiNXHSJM58y)
# NOTE: 'Error processing Instruction 0: custom program error: 0x7d3' means wrong IDL authority
## publish IDL (devnet, hot wallet)
anchor --provider.cluster devnet idl \
  --provider.wallet [idl-authority-and-fee-payer-keypair] \
  # init vBoNdEvzMrSai7is21XgVYik65mqtaKXuSdMBJ1xkW4 \
  upgrade vBoNdEvzMrSai7is21XgVYik65mqtaKXuSdMBJ1xkW4 \
  -f ./target/idl/validator_bonds.json

## publish IDL (mainnet, spl gov)
anchor idl write-buffer --provider.cluster mainnet --provider.wallet [fee-payer-keypair] \
  --filepath target/idl/validator_bonds.json vBoNdEvzMrSai7is21XgVYik65mqtaKXuSdMBJ1xkW4
anchor idl set-authority --provider.cluster mainnet --provider.wallet [fee-payer-keypair] \
  --new-authority 6YAju4nd4t7kyuHV6NvVpMepMk11DgWyYjKVJUak2EEm --program-id vBoNdEvzMrSai7is21XgVYik65mqtaKXuSdMBJ1xkW4 \
  <BUFFER_PUBKEY>

## in case a need of base64 anchor update
anchor idl --provider.cluster mainnet set-buffer --print-only \
  --buffer <BUFFER_PUBKEY> vBoNdEvzMrSai7is21XgVYik65mqtaKXuSdMBJ1xkW4


# 3.check verifiable deployment (<BUFFER_PUBKEY> can be verified as well)
#   a) when the target/verifiable/.so has been built already use switch --skip-build
COMMIT_HASH=`git rev-parse --short HEAD`
anchor --provider.cluster mainnet \
   verify -p validator_bonds \
   --env "GIT_REV=${COMMIT_HASH}" --env "GIT_REV_NAME=${VERSION}" \
   # --skip-build \
   <PROGRAM_ID_or_BUFFER_ID>

# 3.b upload the verified build to OtterSec API to be considered a Verified Build
#     see https://github.com/Ellipsis-Labs/solana-verifiable-build
solana-verify verify-from-repo https://github.com/marinade-finance/validator-bonds \
  --library-name validator_bonds \
  --program-id vBoNdEvzMrSai7is21XgVYik65mqtaKXuSdMBJ1xkW4 --commit-hash "${COMMIT_HASH}" \
  -- --config env.GIT_REV=\'${COMMIT_HASH}\' --config env.GIT_REV_NAME=\'${VERSION}\'