stellar / soroban-cli

CLI for Soroban contracts.

Stellar CLI (stellar-cli)

This repo is home to the Stellar CLI, the command-line multi-tool for running and deploying Stellar contracts on the Stellar network.

Documentation

For installation options see below, for usage instructions see the full help docs.

Install

Install the latest version from source:

cargo install --locked stellar-cli --features opt

Install with cargo-binstall:

cargo install --locked cargo-binstall
cargo binstall -y stellar-cli

Install with Homebrew:

brew install stellar/tap/stellar-cli

Setup Autocomplete

stellar completion --shell <SHELL>

Possible SHELL values are bash, elvish, fish, powershell, zsh, etc.

To enable autocomplete in the current bash shell, run:

source <(stellar completion --shell bash)

To enable autocomplete permanently, run:

echo "source <(stellar completion --shell bash)" >> ~/.bashrc

Latest Release

For latest releases, see releases.

Upcoming Features

For upcoming features, please see the project board.

To Contribute

Find issues to contribute to here and review CONTRIBUTING.md.

Developer Docs: https://developers.stellar.org/docs

soroban-cli's Issues

CLI: Print events during invoke

I think we should output events, including any DebugEvents the system has generated to stdout, or somewhere, when the invoke command is used.

This behavior was previously described here: #39 (comment)

Local dapp serving and dev environment

A local way for devs to manually test their entire dapp e2e with a browser. They will want a way to have a local mock stellar network, running their contract, so that their javascript web app has something to talk to.

TODO

• add stellar-contract-cli serve or stellar-contract-cli sandbox? command
• Design sandbox storage (json file on-disk?)
• Serve the contract RPC endpoint for queries
• Simulate txn submission & applying in the sandbox

CLI: Simulate and Invoke a contract on a network

Comprehensive Val <=> String conversion for command line args and output

CLI: CLI Event Streaming Tool for local sandbox

Idea is a local CLI tool to stream events for devs, such as something like:

$ cli events --contract-id 01
{"type": "Transfer", "data": {...}}

Relevant CAP: stellar/stellar-protocol#1280
Soroban-RPC API: https://docs.google.com/document/d/1TZUDgo_3zPz7TiPMMHVW_mtogjLyPL0plvzGMsxSz6A/edit#heading=h.t03hji406t76

TODO

Background & Planning work

• Design a storage format and file for events in the local sandbox
  • .soroban/events.json with a list of events serialized to json might be fine. or xdr?
  • The storage and transfer mechanism here should support linux/mac/windows
• Add the command to the CLI
  • soroban-cli events
  • Default behaviour is to print the latest N messages from the sandbox. (or all messages? see what kubectl logs does).
  • Figure out a nice human-friendly format to print the events in.
• stream events from the sandbox as they come in.
  • soroban-cli events -f
• add --id CONTRACT_ID flag for per-contract filtering (or --id to match other functions?)
• Add getEvents method support in soroban serve

Nice-to-haves

• allow output in json (strval) format, as well as xdr?

CLI: CLI Event Streaming Tool for remote core (futurenet)

Extend the cli event streaming tool from #39 to work with a remote core (e.g. futurenet).

This depends on stellar/go#4554 from soroban rpc first to provide the service endpoint.

• Allow filtering by contract id

Nice-to-haves

• Allow filtering by other parts of the topic
• Allow config to push events to a message broker (e.g. sqs?)
  • How would devs like to use this? Maybe package it as a docker image with ENV-var flags?

CLI: Deploy native token contract

What problem does your feature solve?

The deployment path for native contracts is different from WASM contracts.

What would you like to see?

A nice interface to deploying the native token contract.

What alternatives are there?

TODO

CLI: Add CORS headers to cli serve

This will let local webpack servers make direct requests to it without getting CORS errors.

There's a thing in the warp webserver for this. https://docs.rs/warp/0.1.19/warp/filters/cors/fn.cors.html

CLI: Figure out how to support signatures args

We need to figure out what the story should be for how to produce signatures for the CLI when invoking contracts and deploying contracts, which requires a signature also. The CLI is intended for quick testing, interactive playing around and general experimenting, so we need to keep this simple and convenient, while trying not to produce something that isn't true to what will be required on chain.

Additionally because contracts, like the token contract, do their own signature checking we can't avoid signature checking like some tools in other ecosystems might do.

CLI: getAccount method in cli serve v2 (balances + sequence tracking)

The initial basic version of getAccount in #134 doesn't include account balances, nor does it increment/check the account sequence numbers. For completeness, it should do both. Ideally the account sequences should be persisted across restarts (.soroban/ledger.json maybe?)

Add descriptions to CLI help messages

stellar-core: Smart Contracts: Contract Storage Read Endpoint for remote core (futurenet)

Follows on from #60

Provide a way to read raw storage xdr from contracts, as a tertiary option for dapp devs. Probably the least used, so the lowest priority.

Access via HTTP, with something like:
/contracts/user:contractId/data/xdrstorageKey -> xdr storage value

Access via console, with something like:
cli read <contract_id> <key>
(Note: see if we can use strval for the key)

TODO

CLI: Deploying a contract should fail and warn if the interface version is incorrect

What problem does your feature solve?

I deployed a contract, but have to call it to see if the interface version it was built with is correct.

What would you like to see?

We could check that and fail the deployment if that is the case.

What alternatives are there?

• Don't do that.
• Warn, but not fail.

CLI: Add logging output to serve subcommand

What problem does your feature solve?

soroban-cli serve would be slightly nicer to use if you could tell what is going on. It would help debug clients, as you could tell if they actually made the request you expected.

What would you like to see?

Some sort of logging output when serve handles a request.

What alternatives are there?

CLI: Add outside-in tests using assert_cmd

We're reaching the point where not having tests in this repo is going to start to hurt, especially approaching new releases.

The assert_cmd crate is a very helpful tool for writing tests for CLIs that work outside-in, by actually executing the binary with arguments and asserting on the stdout, stderr, and file system.

There's an example of an assert_cmd using test that I wrote recently here:
https://github.com/leighmcculloch/cargo-set-rust-version/blob/21e011eaa52dcc8857f60cf0b4dcca7815b06faa/tests/update.rs#L5-L35

CLI: Initialize an example pulled from example GitHub repo

CLI: Boilerplate

CLI: Sandbox local http server for preflight

What problem does your feature solve?

Allowing running your client (web) app against the local sandbox, so you can click around in your app and test things manually while developing.

This is the CLI sandbox partner to stellar/stellar-core#3484

What would you like to see?

cli serve which serves a mock http api (mimicking the planned pubnet one), allowing preflight and RPC calls for contracts (to start with).

Given core is implementing the gas estimation endpoint and preflight requests, @graydon has offered to do this for production. 🙏 So this is just about the local CLI tooling offering a mock equivalent HTTP API server against the sandbox (ledger.json), for local development.

TODO

• add cli serve or cli start to start http server
• mirror the planned core http API (might not exist yet, make something up)
  • Super janky first pass for now (mirrors what I had before in the prototype so my demo app continues to work)
• Run vm, and invoke contract calls in rust
• Req/resp serialization (might not exist yet, make something up)
• load state from ledger.json and invoke against that
• more proper jsonrpc implementation

Nice-to-haves

• Consider if/how to integrate this work with remote core backends instead of just local sandbox
• Gas estimation endpoint
  • needs input from @MonsieurNicolas on fees, so let's delay this for now.

Questions

• Where is core storing contract code/data? In buckets? Sounds large.

Create API Spec for RPC Node

As discussed on Discord. This is to get everyone on the same page wrt the RPC API

Related to #58

(not sure if it belongs in this repo or somewhere else)

CLI: Sandbox local http server for txn submission

What problem does your feature solve?

A way to locally test web clients' txn submission

This follows on from #58

What would you like to see?

Local HTTP server should support txn submission against local sandbox

What alternatives are there?

CLI: Expose a ledger to the invoke contract so we can get ledger info in contracts

Currently if you try to get ledger info in a contract called via invoke, it panics with "missing ledger info". We should inject a pseudo-ledger for the sandbox. It would be good if the ledger timestamp and sequence number incremented to more closely simulate a network.

Note: This should probably also apply to invoke's via cli serve

CLI: Invoke a contract in a local mock (e.g. MemHost) sandbox

CLI: requestAirdrop method in cli serve for local sandbox

Add a requestAirdrop method to cli serve (and cli command?), which will trigger a friendbot-equivalent funding to the specified new account. This is for the local sandbox development

soroban-cli inspect should generate human-readable output

What problem does your feature solve?

inspect doesn't render names as strings, doesn't give pretty (possibly rust-like?) representations of structs and unions, etc.

What would you like to see?

Easy to read output.

What alternatives are there?

TODO

CLI: Output resource usage and measured execution cost

Smart Contracts: Contract Storage Read Endpoint for local sandbox

Provide a way to read raw storage xdr from contracts, as a tertiary option for dapp devs. Probably the least used, so the lowest priority.

Access via HTTP, with something like:
/contracts/user:contractId/data/xdrstorageKey -> xdr storage value

Access via console, with something like:
cli read <contract_id> <key>
(Note: see if we can use strval for the key)

TODO

services/soroban-rpc: Write API docs and getting started guide

CLI: Generate shell autocompletion configuration

What problem does your feature solve?

It would be nice if there were shell completions to help quickly enter commands and explore command options. Coming from Kubernetes/kubectl, I find autocompletion indispensable once you have a decent number of commands/subcommands/args in your CLI tool.

What would you like to see?

Initially bash support would probably be sufficient, though clap completions are supported via https://crates.io/crates/clap_complete which supports common shells (bash, zsh, etc.).

What alternatives are there?

• no completions
• manually generated completion scripts

Neither of these alternatives seem like good options to me.

I have a basic working implementation using clap_complete I can wrap up into a PR if this sounds like a desirable feature.

Add support for `--output` to invoke command

We should add support for --output to invoke command.

It was previously added to the read command.

---

The --output thing is nice. Would be good for this to be consistent across other subcommands (e.g. invoke)

Originally posted by @paulbellamy in #108 (comment)

CLI: Storage to XDR file

Invoke contract with persistent storage/ledgerstate

CLI: Invoke a contract on network

What problem does your feature solve?

When deploying/managing a contract the dev may wish to call some setup functions (e.g. contract.init()). This way they can issue "management" commands and other contract calls to their live contract.

What would you like to see?

$ stellar-contract-cli --network testnet call <contract-id> init '<args>'
(or something)

What alternatives are there?

Don't do it? Make them use laboratory for now?

CLI: Support passing u64 as args to invoke contract functions.

If you try to use a u64 as a contract method param and pass it in from soroban-cli it panics with a very unclear message (just trap). We should support using u64 as a contract method param type.

Contract Spec: Add CLI command that generates a TypeScript type from .wasm.

We should:

• In js-stellar-base, add xdr.ScVal.toJSON(val, spec), and xdr.ScVal.fromJSON(json, spec), inspired by the strval.rs code in this repo
  • Having this in js-stellar-base allows people to use the conversions even without the client binding generation.
• Add typescript generation in rs-soroban-sdk, similar to how we generate rust, using the above js-stellar-base conversions to do parsing.
  • Similar to stellar/rs-soroban-sdk#881
• Add a soroban contract bindings --wasm contract.wasm --output typescript > contract.ts
• Future: Research other libraries in other ecosystems and figure out a light-weight, but usable way to parse transaction results based on the spec as well. Write a follow-up issue for this.
  (updated 2022-04-06)

Contract Spec: Add CLI command that generates a Rust trait from .wasm.

CLI: Allow short contractIDs

See #43 (comment)

CLI: Storage to JSON File

Dependent on stellar/xdrgen#112

CLI: Preflight + txsub proxying to remote core (futurenet)

• Figure out which repo this should live in
  • which component is doing this? cli? horizon?

CLI: Invoke a contract on network

Contract Spec: Add CLI command that extracts XDR from .wasm.

CLI: Map strkeys (e.g. G...) to FixedBinary<32>

People will naturally want to use Stellar's strkey format for keys as inputs to functions or arguments to things. We should map this to FixedBinary<32> or to some other type, so that people can continue to use those keys. Possibly now is the right time to finish implementing the PublicKey type that is still in the XDR.

cc @paulbellamy @jayz22 @jonjove

I'm revisiting this because of this question in Discord by @fsodano:
https://discord.com/channels/897514728459468821/966788672164855829/1003810451408306246

CLI: XDR Decoding

It would be helpful if the CLI offered a sub-command for decoding any XDR in the Stellar XDR. This is rather generic and so could benefit from being its own tool, but for developer experience it is better to include this in the contract CLI and if there are uses separately we can break it out at a later time.

Ideally the command would be used like:

$ stellar-contract-cli xdr -n ContractData -x <xdr>
$ echo <xdr> | stellar-contract-cli xdr -n ContractData -x -
$ stellar-contract-cli xdr -n ContractData -f file.xdr

CLI: Better error messages for different failure cases in the cli serve

Case in point all the errors here: #87

CLI: Packaging & Distribution

What problem does your feature solve?

How will normal users install and run the CLI?

What would you like to see?

We should figure out the release process for this project.
We should do a CI pipeline (of some sort) which builds the CLI for installation.
We should build binaries for:

• amd64/x86 (arm?)
• windows/mac/linux

Should we build a deb?

What alternatives are there?

CLI: Allow deploying and invoking a contract in CLI storage

What problem does your feature solve?

There is no way to create a contract or call an existing contract without invoking a function in a WASM contract.

What would you like to see?

A command stores a WASM contract to storage, and another command that allows invoking the stored contract through a contract ID.

CLI: Fix issues passing UDTs as an arg

What problem does your feature solve?

It is hard/impossible to pass an Identifier via the --arg flag. In the spec it is generated as a UDT. Output format is ["Account", [0,...,0]], which makes me expect that either the output format or ["Account", "G...KEY"] would work as an input. But it doesn't.

What would you like to see?

There are a few options here:

• Add a special-case for Identifier
• Make the UDT input format match the UDT output format
• Make complex types format easier to use in general

CLI: Deploy a Contract via RPC

This is a high-level epic for the "deploy a contract to testnet/pubnet" user journey.

Meta question: Should this be a CLI tool, or a web UI like Laboratory?

• @paulbellamy, I'd vote for a CLI tool as that will be easier to wrap and use from VSCode later.

We'll need:

• Generate a new wallet locally (for now)
• Print the wallet address so the dev can fund it (or get funding from friendbot)
• Build/sign/broadcast the contract deployment transaction
• Send/receive lumen transfers, so the dev can manage their balance

Nice-to-haves:

• Switch between multiple local wallet/identites
• Integrate with HW wallets like ledger/trezor so devs can be more secure
• Storage-management tools
  • For managing a contract storage. e.g. "fee-bump" to top up a storage location to prevent expiry (as per cap-55)

CLI: Faucet sub-command

Horizon and the soroban-rpc (and soroban-cli) all provide faucet endpoints.

• Horizon provides a friendbot backed endpoint which is pre-existing.

• Soroban-rpc (and soroban-cli) provide a requestAirdrop endpoint (#100).

We should add a command that developers can use to create a new account on test networks and on soroban-cli serve.

The command should take the form:

soroban-cli account new [--ledger-file <FILE>] [--horizon-url <URL>] [--rpc-url <URL>] [--id G...]

• A new account subcommand would be added.
• A new new subcommand of the account subcommand would be added.
• An --id would be optional:
  • If provided the command attempts to create and fund that account.
  • If not provided we could randomly generate one.
• A --ledger-file, --horizon-url, or --rpc-url would be required:
  • If a --ledger-file was provided, an account would be written into the ledger file.
  • If a --horizon-url was provided, a fund request will be sent to Horizon's Friendbot endpoint.
  • If a --rpc-url was provided, a request will be sent to the RPC server's requestAirdrop endpoint.
• The command would output:
  • Success / failure. (Exit code non-zero for failure.)
  • In the case that --id was not provided, it should also output the S... secret key that was generated.

This command would not be usable with the sandbox.

A developer would need to use this command before doing things like using the deploy command (captured in #41). For deployed networks a user could use this command or use the Stellar laboratory. For local networks or for soroban-cli serve this command would be the primary way to get an account.

I think we should keep any persistent wallet experience out-of-scope for now and think about adding that later.

Contract Spec: Add CLI command that generates JSON from .wasm

Print version information including environment version

CLI: Events are printed with incorrect newlines

When events are printed news lines are in the wrong places.

In the example below event 0 has a new line after the line prefix, but not after the line itself. This causes the prefix for event number 1, Event #1, to appear at the end of event 0.

$ soroban-cli invoke --wasm target/wasm32-unknown-unknown/release/example_events.wasm --id 1 --fn hello
null
Event #0:
{"ext":"v0","contractId":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1],"type":"contract","body":{"v0":{"topics":[{"symbol":[103,114,101,101,116,105,110,103,115]},{"symbol":[116,111,112,105,99,50]}],"data":{"symbol":[104,101,108,108,111]}}}}Event #1:
{"ext":"v0","contractId":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1],"type":"contract","body":{"v0":{"topics":[{"symbol":[102,97,114,101,119,101,108,108,115]},{"symbol":[116,111,112,105,99,50]}],"data":{"symbol":[98,121,101]}}}}%