# thruput-client
Reusable contract invocation and spec codec for Thruput clients.
The Thruput CLI and the experimental Stellar adapter supply their own configuration,
identity resolution, confirmation, runtime and output.
## Invocation phases
1. Resolve the trusted network hash and wallet identity: `Wallet::Native` for a
pubkey account, or `Wallet::Legacy` for an existing deployed wallet and its
configured entrypoint. Supply the target, calldata, gas limits, expiry and nonce.
2. Wrap the caller-owned transport in `NativeClient`, use `check_endpoint` to
require wire 14 and the methods the flow needs, then use `validate_network` to compare the endpoint with the trusted network identity.
`resolve_block_expiry_height` can derive expiry from the current chain tip.
3. `prepare_call(CallRequest, NetworkHash)` returns `UnsignedCall` for inspection.
4. `UnsignedCall::sign(&impl Signer)` returns `SignedCall`; inspect `tx_hex` and
`tx_hash` before submission if needed. For native accounts, a mismatched public
key is rejected before invoking the signer.
5. `SignedCall::submit(&client)` returns `SubmittedCall`, rejecting a server hash
that differs from the locally computed hash. Errors retain the original hash.
6. `SubmittedCall::wait(&client, network_hash, config, cancelled)` returns a typed receipt, including
unsuccessful execution. The caller interprets `receipt.execution` and formats it.
Native calls use `DefaultWallet.execute`; legacy calls use `doAction`. After
checking receipt success, `SignedCall::decode_return` extracts the single child
return for the selected wallet. Native return decoding bounds the complete encoded
buffer, including collection framing, to the protocol's return-buffer limit.
Native accounts supply pubkey authentication; legacy addresses remain explicit and
are never rederived. Network validation is explicit; `prepare_call` and `sign` do
not contact the network. Submission is not retried by this library. After an
ambiguous submission error or receipt timeout, reconcile by the retained hash
before deciding what to do next.
RPC selection is independent of wallet format: both pubkey wallets and existing
contract wallets use wire 14. There is no legacy RPC fallback. Submission errors
retain original RPC data and unfamiliar results; receipt waits retain commitment,
status and lookup evidence through timeout or cancellation.
## Native deployment
`prepare_deploy(DeployRequest, NetworkHash)` builds a `DefaultWallet` deployment
for a native account. The code is either attached, which registers the binary in
the same transaction, or an already registered `contract_hash`. The request can
also fund and initialize the new contract in that transaction. The deployment salt
is `deployment_nonce(nonce)`, so the new contract's address is known before
signing: `UnsignedDeploy::address`.
Deployment then follows the same sign, submit and wait phases as calls, through
`SignedDeploy` and `SubmittedDeploy`. `SubmittedDeploy::verify` requires the
receipt to match the transaction hash. It also requires a successful deployment
to return exactly the predicted address. The caller interprets `receipt.execution`.
`submit_signed_transaction` submits supplied signed bytes once and checks the
acknowledgement against their canonical hash. Observation never calls it.
## Codec
The `codec` module decodes canonical specs, resolves methods, derives selectors,
encodes positional arguments and decodes returns/declared aborts. The caller
loads any files and supplies the metadata. Best-effort return decoding can return
`None`; the receipt still contains raw data. Ambient SDK exception-registry lookup
stays in the Thruput CLI compatibility layer.
The crate owns no runtime, CLI parser, profiles, key store, project discovery,
terminal output or process lifecycle. Its normal dependencies exclude the
Thruput CLI, node supervisor, compiler/lowerer, toolchain manager, JSON-RPC
server crate and contract SDK. Existing RPC, signing, XDR and spec types are
re-exported so adapters can use matching versions.
Node management remains a separate capability based on `thruput-node-supervisor`.
Adding a node adapter to another CLI should not expand this crate's dependencies.
## Text encodings for host applications
`thruput_client::strkey` re-exports the encoding helpers from
`thruput-signing`. Use `parse_contract_address` / `format_contract_address`
for Z StrKeys, `parse_public_key` / `format_public_key` for G public keys, and
`parse_secret_seed` / `format_secret_seed` for explicit S seed import/export.
Parsing accepts base58 values of exactly 32 bytes as well as the corresponding
typed StrKey. Stellar C addresses and legacy hex identifiers are rejected. Invalid checksum, length or type is
rejected; errors never include the supplied input. Secret results use
`Zeroizing`; applications remain responsible for their own input buffers.
These helpers preserve bytes. G public keys do not become Thruput account or
wallet addresses. Z identifies Thruput but does not distinguish local, test, and
production networks. The spec codec
accepts base58 and Z addresses, including nested typed arguments. Its decoded
addresses, public keys and hashes and public RPC identifiers use base58. Raw
bytes, event topics, storage keys and entrypoint selectors retain hex.
A host that wants Z output can
call the formatter explicitly. Neither CLI needs its own StrKey conversion.