[rvolosatovs]

This is an in-progress draft of the ledger work, aiming to replace the mock-ledger

You can find the Wizer instrumentation here for snapshotting UTXO state (tested, works!)
Each coordination script invocation produces a "transaction" and UTXOs are identified as just (transaction index, UTXO index, assigned in order of construction)
Coordination scripts and UTXO methods can be invoked over HTTP using wRPC

A new wasmtime::Store is created per coordination script invocation; UTXOs are constructed into that top-level store and then snapshotted (producing a new Wasm component) once coordination script returns

LLM-generated description below:

This adds starstream-ledger: a standalone ledger server built on the starstream-runtime-next host,
aiming to replace the mock-ledger. docs/ledger.md (added here) is the authoritative spec for the
HTTP API, CLI flags, and ledger model — the summary below is just the tour.

• Contracts are content-addressed by the SHA-256 of their component Wasm, encoded as a multibase
  multihash (canonically base32-lower). The canonical form is also a valid component-model label, so it
  embeds verbatim in Wasm and wRPC instance names.
• Publishing is signed and paid for. PUT /contracts/<digest> takes a COSE_Sign1 envelope
  (Ed25519, kid = raw public key) over ["starstream:publish", network, nonce, wasm]. The admin account
  (--admin-key/--admin-balance, defaulting to a well-known pre-seeded key with u64::MAX) is charged
  one unit per Wasm byte; nonces are strictly increasing (replay protection).
• Coordination scripts and UTXO methods are invoked over wRPC via a single POST /rpc, dispatched
  on the instance: starstream:contract/<digest> for scripts, starstream:utxo/<digest> for
  persisted-UTXO methods. Script UTXO imports are bound via X-Starstream-Utxo: <instance>=<contract-digest> request headers.
• UTXO state is snapshotted with Wizer (tested, works!). A fresh wasmtime::Store is created per
  coordination-script invocation; UTXOs are constructed into it and snapshotted into new Wasm components
  when the script returns. UTXOs are content-addressed too: each successful script invocation is
  recorded as a transaction in a new block, and the persisted UTXO digests (output order) come back in
  X-Starstream-Utxo response headers alongside X-Starstream-Transaction/X-Starstream-Block. Blocks
  are recorded in memory but not (yet) addressable over HTTP.
• ABIs are served as WIT: GET /contracts/<digest>/rpc and GET /utxos/<digest>/rpc, as WIT text
  or a Wasm-encoded WIT package via Accept. The interface ID is exactly the wRPC instance to invoke, so
  a world importing it feeds straight into wit-bindgen-wrpc.
• A client CLI (starstream-ledger-cli) is gated behind the cli feature; arguments and results
  are WAVE-encoded. E2E tests drive the in-process server
  (tests/ledger.rs) and the compiled binaries (tests/cli.rs).
• Cardano context (block height, current slot) is injected into running contracts via the
  starstream:std/cardano host interface (--cardano-block-height, --cardano-current-slot).

Usage

Setup

# Build the server + CLI, compile the contract to a component
cargo build -p starstream-ledger --features cli
./starstream wasm -c examples/score.star --output-component score.wasm

# The default admin account: the Ed25519 key whose private key is SHA-256("admin")
KEY=$(printf admin | sha256sum | cut -d' ' -f1)
URL='http://[::1]:9000'

Terminal 1 — the ledger

# Admin account pre-funded with u64::MAX by default;
# override with --admin-key PUBKEY / --admin-balance N
target/debug/starstream-ledger --network dev

Terminal 2 — the flow

CLI=target/debug/starstream-ledger-cli    # talks to http://[::1]:9000 by default

# 1. Publish: signs the COSE_Sign1 envelope, prints the content-address
DIGEST=$($CLI publish --key $KEY --network dev --nonce 1 score.wasm)

# 2. What can this contract do? No script name -> the served WIT
$CLI script $DIGEST
#   package starstream:contract;
#
#   interface bciqfbwcy4cmf5td7mbayvlymywvvq72cyjlqvccaswu6rtfm2d3fixa {
#     example: func();
#   }

# 3. Run the coordination script; constructs the ScoreProgress UTXO.
#    The persisted UTXO digest, transaction index, and block height
#    are reported on stderr:
$CLI script --utxo score-progress=$DIGEST $DIGEST example
UTXO=bciq...   # the digest reported above — the UTXO's address

# 4. What can the UTXO do? No method name -> the served WIT
$CLI method $UTXO
#   package starstream:utxo;
#
#   interface bciqelzhvansl7qzql6bbqpkluky3ryapr2sf2aoewquyusjra2dfz4q {
#     plus-chips: func(chips2: u64);
#     plus-mult: func(mult2: u64);
#     mult-mult: func(mult-pct: u64);
#     finish: func();
#   }

# 5. Invoke methods (arguments are WAVE, one per parameter)
$CLI method $UTXO plus-chips 7
$CLI method $UTXO plus-mult 42
$CLI method $UTXO mult-mult 200
$CLI method $UTXO finish

The same data over plain HTTP

# The durable record: the COSE_Sign1 publish envelope (the default representation)
curl $URL/contracts/$DIGEST -o envelope.cose

#   }

# 5. Invoke methods (arguments are WAVE, one per parameter)
$CLI method $UTXO plus-chips 7
$CLI method $UTXO plus-mult 42
$CLI method $UTXO mult-mult 200
$CLI method $UTXO finish

The same data over plain HTTP

# The durable record: the COSE_Sign1 publish envelope (the default representation)
curl $URL/contracts/$DIGEST -o envelope.cose
# The raw contract component, disassembled on the fly
curl -H 'accept: application/wasm' $URL/contracts/$DIGEST | wasm-tools print | less

# The ABIs the CLI showed above are just GETs on the /rpc URLs
curl $URL/contracts/$DIGEST/rpc    # script ABI, WIT text
curl $URL/utxos/$UTXO/rpc          # UTXO ABI, WIT text

# The UTXO ABI as a Wasm-encoded WIT package, decoded back by wasm-tools
curl -H 'accept: application/wasm' $URL/utxos/$UTXO/rpc | wasm-tools component wit

Notes

• The fetched application/wasm contract bytes hash back to $DIGEST
  (curl -s -H 'accept: application/wasm' $URL/contracts/$DIGEST | sha256sum) —
  the content-addressing guarantee in action. Re-publishing an already-stored
  digest is an idempotent 200: nothing is charged, no nonce consumed.
• UTXO method invocations currently run against the persisted snapshot: mutated
  state is not (yet) written back as a new transaction, so every invocation
  observes the state captured at persistence time.

[SebastienGllmt]

I don't remember all the validation rules required for COSE, but just be careful to avoid bad keys, insecure keys, non-canonical keys, and a few other weird cases you have to deal with

[rvolosatovs]

Make --admin-account singular.
FundAccount can only be submitted signed by that key.
Add initial contracts
Add initial UTXOs

[rvolosatovs]

All of the relevant work from this branch has been already merged in main or in open PRs (#262 and #267). Closing