sdk/revdist: add multi-language revenue distribution SDK#2774
Closed
sdk/revdist: add multi-language revenue distribution SDK#2774
Conversation
Add the revdist package providing programmatic read-only access to all revenue distribution program on-chain accounts (ProgramConfig, Distribution, SolanaValidatorDeposit, ContributorRewards, Journal) with zero-copy deserialization via encoding/binary, PDA derivation, typed discriminator validation, off-chain Borsh record support for validator debts and Shapley rewards, and a SOL/2Z oracle client. Wire the new client into the top-level SDK and add the mainnet program ID to config.
Add revdist-cli with commands for viewing on-chain revenue distribution data: config, journal, distribution, deposits, contributors, swap-rate. Uses --solana-env flag to select the Solana network (defaults to mainnet) via config.NetworkConfigForEnv. Fix oracle SwapRate struct to match the actual API response format (camelCase JSON fields, additional price/timestamp fields).
DistributionParameters has StorageGap<8> (256 bytes), not 48 bytes. This was causing all fields after it in ProgramConfig to be read from the wrong offset — notably DebtWriteOffFeatureActivationEpoch and RelayParameters.DistributeRewardsLamports were reading zeros instead of their actual values. Validated against the Rust CLI output.
Consolidate deserialization into a generic deserializeAccount helper that validates the discriminator, checks minimum data size, and tolerates trailing bytes for forward compatibility with on-chain struct extensions. Add compat_test.go that fetches live mainnet accounts and verifies deserialized struct fields match raw byte reads at known offsets.
…ompat Add a Rust fixture generator that creates binary test data using bytemuck::bytes_of on real #[repr(C)] struct instances. The byte layout is determined by the Rust compiler, making fixtures authoritative for verifying Go deserialization matches the on-chain Rust struct layout. Go fixture tests read each .bin/.json pair, deserialize with the SDK, and assert field values match the expected values from the JSON sidecar.
Replace MustPublicKeyFromBase58 with error-returning variant in CLI, add 30s HTTP timeout to oracle client, display u128 high bits when non-zero, and switch fixture generator deps from SSH to HTTPS URLs.
Move fixtures from sdk/go/revdist/testdata/ to sdk/testdata/fixtures/revdist/ so all three languages share the same Rust-generated binary test data. Add Python SDK (uv + solders) and TypeScript SDK (bun + @solana/web3.js) with state deserialization, discriminator validation, PDA derivation, and fixture-based compatibility tests. Both SDKs tolerate extra trailing bytes for forward compatibility when structs are extended. Add Makefile targets (sdk-test, python-test-revdist, typescript-test-revdist, generate-fixtures) and a CI job in rust.yml.
Move the revenue distribution SDK out of smartcontract/sdk/ into a top-level sdk/revdist/ directory with go/, python/, typescript/, and shared testdata/fixtures/ subdirectories. Update all import paths, fixture references, and Makefile targets accordingly. Move the CI sdk-test job from rust.yml into its own sdk.yml workflow.
Not worth maintaining a CLI for one language; users can use the library directly.
snormore
changed the title
Add ledger record types (ComputedSolanaValidatorDebts, ShapleyOutputStorage) and their PDA derivation to Python and TypeScript SDKs. Update clients to take both Solana RPC and DZ Ledger RPC connections, with environment constructors wiring both. Add LEDGER_RPC_URLS to config modules. Update README to document the two data sources.
snormore
force-pushed
the
snor/revdist-go-sdk
branch
from
9272853 to
2603024
Compare
Add missing compat test coverage for FetchValidatorDebts and FetchRewardShares across all three SDKs (Go, Python, TypeScript). These hit the DZ Ledger RPC, not Solana public RPC. Also switch Go compat tests to use the global config package instead of hardcoded RPC URLs.
Ledger records for validator debts and reward shares may not exist for the most recent epoch. Use NextCompletedDZEpoch - 5 instead of - 1 to target an epoch that has finalized ledger records.
Use create-with-seed (matching Rust create_record_key) instead of FindProgramAddress for validator debt and reward share ledger records. Fix reward share seeds to use ["dz_contributor_rewards", epoch, "shapley_output"]. Skip 33-byte RecordData header before deserializing. Add record key derivation unit tests with Rust test vectors. Fix TypeScript base58 encoding bug in fetchAllByDiscriminator. Add tsc --noEmit to CI for TypeScript type-checking.
Add NewRPCClient helper for Go and new_rpc_client for Python that automatically retry on HTTP 429 Too Many Requests with exponential backoff. TypeScript already retries via @solana/web3.js built-in behavior. Use retry clients in SDK convenience constructors and compat tests.
Add release.sdk-revdist.yml triggered by sdk-revdist/v* tags, using OIDC trusted publishing for both npm and PyPI. Update TypeScript package.json for public publishing under @doublezero scope.
Contributor
Author
|
Superseded by #2776 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
sdk/revdist/Client.mainnet_beta(), etc.) with preconfigured Solana RPC and DZ Ledger RPC endpointssdk.ymlCI workflow for SDK testsTesting Verification
#[repr(C)]byte layoutsREVDIST_COMPAT_TEST=1) that validate deserialized fields against raw byte offsets on live accounts