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) (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-distribution/ - CLIs for generating Settlement and Merkle Tree JSON data, which serve as the foundation for on-chain initialization and claim settlement transactions
• 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-*: Creates JSON data that reflects bidding and PSR events, 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: Creating the Settlement accounts based on the generated JSON data, settlements are created by public key bnwBM3RBrvnVmEJJAWEGXe81wtkzGvb9MMWjXcu99KR
• fund-settlements: Funds the Settlement accounts from the Bonds account based on data loaded by init-settlements
• claim-settlements: Claims the Settlement accounts to distribute SOL to holders affected by PSR (protected events), bidding or other settlement events or other reasons of creating the settlement
• close-settlements Reset (close) the Settlement accounts when they expire (defined in Config by value of field epochs_to_claim_settlement)

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 bid-psr-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}\'