Skip to content

js: query the ledger over /rpc - #282

Draft
rvolosatovs wants to merge 1 commit into
mainfrom
roman/js/ledger-client
Draft

rvolosatovs wants to merge 1 commit into
mainfrom
roman/js/ledger-client

Conversation

@rvolosatovs

Copy link
Copy Markdown
Contributor

The Ledger interface predated starstream-ledger and its only implementation, InMemoryLedger, threw todo from every method.

Redesign Ledger around the ledger's model: outputs are referenced by TransactionInput, a (transaction digest, index) pair with an empty transaction meaning genesis, as in the Rust client; contracts and transactions are fetched by digest along with the signed envelopes they were submitted in; and fund, publish and transaction submission take an Ed25519 Account and, for fund and publish, an explicit nonce. The publish doc comment now says that republishing fails with 409 Conflict, which is what the server does.

Add RpcLedger, which implements the read-only queries over POST /rpc with application/x.wrpc: network name, block height and block envelopes, admin nonce, account balance and nonce, contract Wasm and envelopes, transactions and their envelopes, genesis outputs, and UTXO method calls. A relative base URL resolves against location, when there is one. Contract Wasm is checked against its digest, and responses must carry the wRPC content type. Submission still throws todo.

Invocations go through invoke from @bytecodealliance/wrpc, over a transport that buffers the request into a single POST body and streams the response body back. UTXO method calls take their parameter and result types from the caller, built with the re-exported t, and check the argument count against them before adding the output reference.

Add digest, computing the ledger's multibase base32-lower sha2-256 multihash, in its own module so that ledger_rpc.ts does not import index.ts at runtime. Contract.getId now computes that digest on each call.

InMemoryLedger keeps throwing todo, now against the new interface, and takes genesis outputs instead of Utxo instances. The API sketch in test/example.ts follows the new interface: it reads an output, wraps UTXO method calls in its pseudocode bindings, fetches and publishes contracts by digest and Wasm, and posts a Transaction.

The new vitest compiles examples/score.star, spawns starstream node on port 0 with a genesis script, reading the bound address and keeping the node's log from its stderr, funds an account and publishes the contract with starstream ledger, and runs every query, including genesis UTXO method calls, against it. Each test only relies on ledger state it creates itself. It runs starstream through the repository's cargo run wrapper, so the CLI is built from the current source; STARSTREAM overrides it with a prebuilt binary.

Breaking: Ledger drops getUtxo, getContract, uploadContract and the UploadContractOptions and PostTransactionOptions types, Transaction is now an interface mirroring the ledger's, and Contract.getId returns the ledger digest instead of a hex sha-256.

Assisted-by: anthropic:claude-opus-5-5

The `Ledger` interface predated `starstream-ledger` and its only
implementation, `InMemoryLedger`, threw `todo` from every method.

Redesign `Ledger` around the ledger's model: outputs are referenced by
`TransactionInput`, a `(transaction digest, index)` pair with an empty
transaction meaning genesis, as in the Rust client; contracts and
transactions are fetched by digest along with the signed envelopes they
were submitted in; and fund, publish and transaction submission take an
Ed25519 `Account` and, for fund and publish, an explicit nonce. The
publish doc comment now says that republishing fails with
`409 Conflict`, which is what the server does.

Add `RpcLedger`, which implements the read-only queries over
`POST /rpc` with `application/x.wrpc`: network name, block height and
block envelopes, admin nonce, account balance and nonce, contract Wasm
and envelopes, transactions and their envelopes, genesis outputs, and
UTXO method calls. A relative base URL resolves against `location`, when
there is one. Contract Wasm is checked against its digest, and
responses must carry the wRPC content type. Submission still throws
`todo`.

Invocations go through `invoke` from `@bytecodealliance/wrpc`, over a
transport that buffers the request into a single POST body and streams
the response body back. UTXO method calls take their parameter and
result types from the caller, built with the re-exported `t`, and check
the argument count against them before adding the output reference.

Add `digest`, computing the ledger's multibase base32-lower sha2-256
multihash, in its own module so that `ledger_rpc.ts` does not import
`index.ts` at runtime. `Contract.getId` now computes that digest on
each call.

`InMemoryLedger` keeps throwing `todo`, now against the new interface,
and takes genesis outputs instead of `Utxo` instances. The API sketch
in `test/example.ts` follows the new interface: it reads an output,
wraps UTXO method calls in its pseudocode bindings, fetches and
publishes contracts by digest and Wasm, and posts a `Transaction`.

The new vitest compiles `examples/score.star`, spawns
`starstream node` on port 0 with a genesis script, reading the
bound address and keeping the node's log from its stderr, funds an
account and publishes the contract with `starstream ledger`, and runs
every query, including genesis UTXO method calls, against it. Each test
only relies on ledger state it creates itself. It runs `starstream`
through the repository's `cargo run` wrapper, so the CLI is built from
the current source; `STARSTREAM` overrides it with a prebuilt binary.

Breaking: `Ledger` drops `getUtxo`, `getContract`, `uploadContract` and
the `UploadContractOptions` and `PostTransactionOptions` types,
`Transaction` is now an interface mirroring the ledger's, and
`Contract.getId` returns the ledger digest instead of a hex sha-256.

Assisted-by: anthropic:claude-opus-5-5
Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

This branch has not been deployed

No deployments
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