Skip to content

ledger: query accounts, admin, network and blocks - #271

Merged
rvolosatovs merged 1 commit into
mainfrom
roman/ledger/queries
Oct 21, 2026
Merged

rvolosatovs merged 1 commit into
mainfrom
roman/ledger/queries

Conversation

@rvolosatovs

@rvolosatovs rvolosatovs commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

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.

@rvolosatovs
rvolosatovs added this pull request to stack #272 October 20, 2026 16:54
Comment thread starstream-ledger-cli/src/lib.rs Outdated
Comment thread starstream-ledger-cli/src/lib.rs Outdated
Comment thread starstream-ledger/src/client/http.rs Outdated
Comment thread starstream-ledger/tests/ledger.rs Outdated
@rvolosatovs
rvolosatovs force-pushed the roman/ledger/queries branch 2 times, most recently from a3e533c to ec2aec6 Compare October 20, 2026 17:09
Comment thread starstream-ledger/src/server/http/mod.rs Outdated
Comment thread starstream-ledger/src/server/http/mod.rs Outdated
@rvolosatovs
rvolosatovs force-pushed the roman/ledger/queries branch 2 times, most recently from 91e135e to 5de2728 Compare October 20, 2026 17:25
@rvolosatovs
rvolosatovs marked this pull request as ready for review October 20, 2026 17:26
Base automatically changed from roman/ledger/utxo-wit to main October 21, 2026 15:28
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

Copy link
Copy Markdown
Contributor Author

See #268 (comment)

@rvolosatovs
rvolosatovs merged commit 778e789 into main Oct 21, 2026
5 checks passed
@rvolosatovs
rvolosatovs deleted the roman/ledger/queries branch October 21, 2026 17:34
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant