Repository navigation
ledger: query accounts, admin, network and blocks - #271
Merged
Merged
Conversation
rvolosatovs
added this pull request to stack #272
October 20, 2026 16:54
rvolosatovs
commented
Oct 20, 2026
rvolosatovs
force-pushed
the
roman/ledger/queries
branch
2 times, most recently
from
October 20, 2026 17:09
a3e533c to
ec2aec6
Compare
rvolosatovs
commented
Oct 20, 2026
rvolosatovs
force-pushed
the
roman/ledger/queries
branch
2 times, most recently
from
October 20, 2026 17:25
91e135e to
5de2728
Compare
rvolosatovs
marked this pull request as ready for review
October 20, 2026 17:26
rvolosatovs
force-pushed
the
roman/ledger/queries
branch
from
October 21, 2026 15:10
5de2728 to
e8d32c5
Compare
rvolosatovs
force-pushed
the
roman/ledger/queries
branch
from
October 21, 2026 15:28
e8d32c5 to
009c5d8
Compare
Add `account`, `admin`, `network` and `block.get-block` queries to
`starstream:ledger`, served over `POST /rpc` like the existing ones:
- `account.get-balance(key: list<u8>)` and `account.get-nonce(key)`
return the balance and last publish nonce of the account identified by
its raw Ed25519 public key.
- `admin.get-nonce()` returns the last nonce used by the admin key to
fund accounts, which is tracked separately from its publish nonce.
- `network.get-name()` returns the network every envelope is bound to.
- `block.get-block(height)` returns the envelopes of the block at
`height`, in order, or `none` if there is no such block. Heights match
`block.get-height`: block 1 holds the first envelope, and height 0
(genesis, served by `genesis.get-outputs`) is `none`.
The client gains `get_account_balance`, `get_account_nonce`,
`get_admin_nonce`, `get_network` and `get_block`, and the CLI gains
`account balance`, `account nonce`, `admin nonce`, `block get` and
`network name`. `--nonce` of `contract publish` and `account fund` is
now optional and defaults to the last account or admin nonce reported
by the ledger plus one, respectively.
The client no longer carries a network: `fund`, `publish_contract` and
`transact` take the network to bind the signed envelope to, and fetched
envelopes are no longer checked against it. Reading a block, contract or
transaction from a ledger thus works regardless of its network. The CLI
drops the global `--network` argument and declares it only on the
commands that sign envelopes: `account fund`, `contract publish` and
`contract script call`. It defaults to the network reported by the
ledger. `contract script call` rejects both `--network` and `--key`
together with `--simulate`.
The `contract.get-envelope`, `contract.get-wasm`,
`transaction.get-envelope` and `transaction.get-transaction` handlers
now clone the stored `Bytes` under the `contracts` or `transactions`
read lock and release it before encoding the result, and UTXO method
calls release the `contracts` read lock before merging the UTXO state
into the contract Wasm, so writers are not stalled by large contracts.
`get-error` is shared by all lookups: its `invalid-digest` variant is
renamed to `malformed`, which also covers keys that are not valid
Ed25519 public keys.
API break: the generated `GetError::InvalidDigest` is now
`GetError::Malformed`. `ClientBuilder::network` and `DEFAULT_NETWORK`
are removed, and `Client::{fund, publish_contract, transact}` gain a
`network` parameter.
Assisted-by: anthropic:claude-opus-5-5
Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>
rvolosatovs
force-pushed
the
roman/ledger/queries
branch
from
October 21, 2026 15:29
009c5d8 to
5d1eb0e
Compare
Contributor
Author
|
See #268 (comment) |
rvolosatovs
added a commit
that referenced
this pull request
Oct 21, 2026
Add `docs/ledger.md`, a usage-focused page for the development ledger:
- a quick start that compiles the `require_hash_preimage` example, runs
a
node with a genesis output created by `create-hash 42`, and spends it
with
`consume-hash`, first with a wrong preimage (traps, nothing submitted)
and
then with the right one;
- `starstream node` flags and the genesis TOML format;
- the `starstream ledger` client commands, including the `account`,
`admin`,
`block get` and `network` queries from #271;
- the ledger model: digests, accounts, nonces, UTXOs and blocks;
- the HTTP API: `POST /rpc` (COSE envelopes and wRPC queries against
`ledger.wit`, plus UTXO method calls), `GET /rpc` (ledger and per-UTXO
WIT,
from #262), `GET /contracts/<digest>`, `GET /transactions/<digest>`, the
envelope format and the error status codes.
A warning near the top says this is not a secure ledger: only genesis
outputs
need authorization, proofs are not checked, and state lives in memory.
`docs/cli.md` now has a short `starstream node` / `starstream ledger`
section
that links to the new page.
Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>
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
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.
Add
account,admin,networkandblock.get-blockqueries tostarstream:ledger, served overPOST /rpclike the existing ones:account.get-balance(key: list<u8>)andaccount.get-nonce(key)return the balance and last publish nonce of the account identified by
its raw Ed25519 public key.
admin.get-nonce()returns the last nonce used by the admin key tofund accounts, which is tracked separately from its publish nonce.
network.get-name()returns the network every envelope is bound to.block.get-block(height)returns the envelopes of the block atheight, in order, ornoneif there is no such block. Heights matchblock.get-height: block 1 holds the first envelope, and height 0(genesis, served by
genesis.get-outputs) isnone.The client gains
get_account_balance,get_account_nonce,get_admin_nonce,get_networkandget_block, and the CLI gainsaccount balance,account nonce,admin nonce,block getandnetwork name.--nonceofcontract publishandaccount fundisnow optional and defaults to the last account or admin nonce reported
by the ledger plus one, respectively.
The client no longer carries a network:
fund,publish_contractandtransacttake the network to bind the signed envelope to, and fetchedenvelopes are no longer checked against it. Reading a block, contract or
transaction from a ledger thus works regardless of its network. The CLI
drops the global
--networkargument and declares it only on thecommands that sign envelopes:
account fund,contract publishandcontract script call. It defaults to the network reported by theledger.
contract script callrejects both--networkand--keytogether with
--simulate.The
contract.get-envelope,contract.get-wasm,transaction.get-envelopeandtransaction.get-transactionhandlersnow clone the stored
Bytesunder thecontractsortransactionsread lock and release it before encoding the result, and UTXO method
calls release the
contractsread lock before merging the UTXO stateinto the contract Wasm, so writers are not stalled by large contracts.
get-erroris shared by all lookups: itsinvalid-digestvariant isrenamed to
malformed, which also covers keys that are not validEd25519 public keys.
API break: the generated
GetError::InvalidDigestis nowGetError::Malformed.ClientBuilder::networkandDEFAULT_NETWORKare removed, and
Client::{fund, publish_contract, transact}gain anetworkparameter.