Skip to main content

Fully-Typed Contracts

When you compile a contract created with soroban-sdk, the Wasm file ends up with a custom section containing a machine-readable description of your contract's interface types, sometimes called its spec or its API. This is similar to ABIs in Ethereum, except that Soroban will store every single one of them on-chain from day one, and they include the comments from the contract's author.

Today, these interface types are formatted using XDR, but this may change down the road.

The important part is that tooling can fetch these interface types to make your life easier. Soroban CLI is the first tool to do so. Specifically, one subcommand:

soroban contract invoke

Really, every smart contract is its own program, and deserves its own CLI.

So that's what Soroban CLI gives you.

A unique CLI for each smart contract. Constructed on-the-fly, right from the on-chain interface types. Including the author's comments. An implicit CLI.

With aliases in your shell, you can also easily make explicit CLIs out of your most-used contracts. For example, if you use the Smart Deploy contract:

$ alias smartdeploy="soroban contract invoke --id 6808e8e2cce73cfca472a8197080938b320d72e7b696e34eb52ebf17070f4ee --"
$ smartdeploy --help
Usage: 6808e8e2cce73cfca472a8197080938b320d72e7b696e34eb52ebf17070f4ee [COMMAND]

register_name Register a contract name to allow publishing.
publish Publish a contract.
Currently a contract's version is a `u32` and publishing will increment it.
If no repo is provided, then the previously published binary's repo will be used. If it's the first
time then it will be empty.
fetch Fetch the hash for a given contract_name.
If version is not provided, it is the most recent version.
fetch_metadata Fetch metadata for a given contract_name.
If version is not provided, it is the most recent version.
deploy Deploys a new published contract returning the deployed contract's id.
help Print this message or the help of the given subcommand(s)

-h, --help Print help

Like any other CLI, you can also get help for any of these subcommands using something like smartdeploy deploy --help. Soroban CLI again fetches the on-chain interface types, this time using it to generate a full list of all arguments to the function, and even generates examples. And just to be totally clear, you don't need to alias these commands. This would work, too:

soroban contract invoke --id 6808e8e2cce73cfca472a8197080938b320d72e7b696e34eb52ebf17070f4ee -- deploy --help

Or, if you clone soroban-examples and make build them all, you can get CLI help for any individual contract or a specific function within a contract:

$ soroban contract invoke --id 1 --wasm target/wasm32-unknown-unknown/release/soroban_hello_world_contract.wasm -- hello --help
Usage: hello [OPTIONS]

--to <Symbol>
--to hello

-h, --help
Print help (see a summary with '-h')

If you're unfamiliar with the -- double dash separator, this is a pattern used by other CLIs. Everything after the double dash, sometimes called the slop, gets passed to the child process. An example of another CLI that makes use of this is cargo run.

Of course, the exact way that that Soroban CLI parses arguments is an ongoing design discussion. Representing complex custom arguments on the command line is a design challenge no blockchain CLI gets perfect yet; many, including Soroban CLI, currently use JSON. But this has downsides, and other options are possible. How would you like to see it work?

Already the best; just getting started

We love that Soroban will have all contract interface types available on-chain right from day one. No secondary API calls to external services, no secondary API token management, no signing in or creating an account anywhere else, and near-perfect reliability. It's a game-changer within the blockchain space.

Soroban CLI already shows how this can be built into foundational tooling to give developers delightful experiences. And this is only the beginning. At every level of the stack, you can expect—and build—tooling that makes interacting with any contract predictable and seamless.

Soon we'll have TypeScript/JavaScript libraries that mirror the behavior of soroban contract invoke, customized for browser & nodejs environments. You can expect GUIs that adapt to any given contract on-the-fly, functioning as interactive documentation. If you're writing contracts that make cross-contract calls, most of the code you need can also be auto-generated.

And that's still all just the beginning. With those as the foundations, what else can we build? What else can you imagine? What is the future of components, now that one small program, aka smart contract, can be easily interacted with at all layers of the software stack? When considered in combination with Wasm—on-chain, in-browser, and elsewhere—what possibilities for interop can we imagine and co-create?

We can't wait to see what you build.