soroban-cli
soroban-cli copied to clipboard
stellar
Proposal: add a new `contract info` command
What problem does your feature solve?
Currently, there's no (easy) way to fetch Stellar Asset contract spec. It'd be nice to be able to see the spec in Json/XDR format.
We do have an inspect command, but the major issue with inspect is produced result is inconsistent:
- By default it produces human readable message, that contains Env Meta, Contract Meta, and Contract Spec.
- Passing
--xdr-base64it produces desired output (XDR), but omits env meta/contract meta which is confusing (and might be useful in some cases)
What would you like to see?
This issue proposes to deprecate contract inspect and add a new successor command stellar contract info:
stellar contract info
$ stellar contract info
Access info about contracts.
Usage: stellar contract info [OPTIONS]
Commands:
interface Outputs a contracts interface
meta Outputs a contracts meta
env-meta Outputs a contracts env-meta
Options:
-h, --help Print help
$ stellar contract info interface --help
Output the interface of a contract.
A contract's interface describes the functions, parameters, and
types that the contract makes accessible to be called.
The data outputted by this command is a stream of `SCSpecEntry` XDR values.
See the type definitions in https://github.com/stellar/stellar-xdr.
See also https://developers.stellar.org/docs/learn/encyclopedia/data-format/xdr.
Outputs no data when no data is present in the contract.
Usage: stellar contract info interface [OPTIONS]
Options:
--id <CONTRACT_ID> Contract ID to get the interface for
--wasm-hash <WASM_HASH> Wasm hash to get the interface for
--wasm <PATH> Wasm file to extract the interface from
--output <OUTPUT> [default: xdr-base64] [possible values: xdr-base64, json, json-formatted]
Other Options:
-h, --help Print help
$ stellar contract info meta --help
Output the metadata stored in a contract.
A contract's meta is a series of key-value pairs that the contract
developer can set with any values to provided metadata about the
contract. The meta also contains some information like the version
of Rust SDK, and Rust compiler version.
The data outputted by this command is a stream of `SCMetaEntry` XDR values.
See the type definitions in https://github.com/stellar/stellar-xdr.
See also https://developers.stellar.org/docs/learn/encyclopedia/data-format/xdr.
Outputs no data when no data is present in the contract.
Usage: stellar contract info meta [OPTIONS]
Options:
--id <CONTRACT_ID> Contract ID to get the meta for
--wasm-hash <WASM_HASH> Wasm hash to get the meta for
--wasm <PATH> Wasm file to extract the meta from
--output <OUTPUT> [default: xdr-base64] [possible values: xdr-base64, json, json-formatted]
Other Options:
-h, --help Print help
$ stellar contract info env-meta --help
Output the env required metadata stored in a contract.
Env-meta is information stored in all contracts, in the
`contractenvmetav0` WASM custom section, about the environment
that the contract was built for. Env-meta allows the Soroban Env
to know whether the contract is compatibility with the network in
its current configuration.
The data outputted by this command is a stream of `SCEnvMetaEntry` XDR values.
See the type definitions in https://github.com/stellar/stellar-xdr.
See also https://developers.stellar.org/docs/learn/encyclopedia/data-format/xdr.
Outputs no data when no data is present in the contract.
Usage: stellar contract info meta [OPTIONS]
Options:
--id <CONTRACT_ID> Contract ID to get the meta for
--wasm-hash <WASM_HASH> Wasm hash to get the meta for
--wasm <PATH> Wasm file to extract the meta from
--output <OUTPUT> [default: xdr-base64] [possible values: xdr-base64, json, json-formatted]
Other Options:
-h, --help Print help
What alternatives are there?
None (for Stellar Asset's spec)
contract inspect (for other mentioned usages)
cc @leighmcculloch @janewang @willemneal
The problem is worth solving and the proposal at a high-level looks good to me.
It takes a command that's existed for a long time inspect and organises the information in a way that is more usable, and extends it in ways that are natural and fills the gap of #1488 which has been reported more than once in other places.
Choice of info for the command is good, short, accurate. It may be too broad, as there might be other info the CLI wants to surface about contracts in the future that don't involve analyzing their wasm which will complicate the option structure. That's just thereotical, nothing obvious comes to mind as a concrete example. So I think info is good.
--output
We use this option name to choose the format of the xdr decoder (e.g. stellar xdr decode --type TransactionEnvelope --output json), so there is some inconsistency to use it for controlling what data itself rather than the format.
--format <FORMAT>...xdr-type... useful to understand which XDR type is the output
The need for access to meta-data like the xdr type hints at the complexity arising from a single command needing to support generating a variety of outputs.
The command structure may be simpler if we use the following format. The following format is less "DRY" because the same options are seen across multiple commands, but each command has a single job and a single purpose. Single purpose means the command can fully describe itself in its own command.
$ stellar contract info
Access info about contracts.
Usage: stellar contract info [OPTIONS]
Commands:
interface Outputs a contracts interface
meta Outputs a contracts meta
env-meta Outputs a contracts env-meta
Options:
-h, --help Print help
$ stellar contract info interface --help
Output the interface of a contract.
A contract's interface describes the functions, parameters, and
types that the contract makes accessible to be called.
The data outputted by this command is a stream of `SCSpecEntry` XDR values.
See the type definitions in https://github.com/stellar/stellar-xdr.
See also https://developers.stellar.org/docs/learn/encyclopedia/data-format/xdr.
Outputs no data when no data is present in the contract.
Usage: stellar contract info interface [OPTIONS]
Options:
--id <CONTRACT_ID> Contract ID to get the interface for
--wasm-hash <WASM_HASH> Wasm hash to get the interface for
--wasm <PATH> Wasm file to extract the interface from
--output <OUTPUT> [default: xdr-base64] [possible values: xdr-base64, json, json-formatted]
Other Options:
-h, --help Print help
$ stellar contract info meta --help
Output the metadata stored in a contract.
A contract's meta is a series of key-value pairs that the contract
developer can set with any values to provided metadata about the
contract. The meta also contains some information like the version
of Rust SDK, and Rust compiler version.
The data outputted by this command is a stream of `SCMetaEntry` XDR values.
See the type definitions in https://github.com/stellar/stellar-xdr.
See also https://developers.stellar.org/docs/learn/encyclopedia/data-format/xdr.
Outputs no data when no data is present in the contract.
Usage: stellar contract info meta [OPTIONS]
Options:
--id <CONTRACT_ID> Contract ID to get the meta for
--wasm-hash <WASM_HASH> Wasm hash to get the meta for
--wasm <PATH> Wasm file to extract the meta from
--output <OUTPUT> [default: xdr-base64] [possible values: xdr-base64, json, json-formatted]
Other Options:
-h, --help Print help
$ stellar contract info env-meta --help
Output the env required metadata stored in a contract.
Env-meta is information stored in all contracts, in the
`contractenvmetav0` WASM custom section, about the environment
that the contract was built for. Env-meta allows the Soroban Env
to know whether the contract is compatibility with the network in
its current configuration.
The data outputted by this command is a stream of `SCEnvMetaEntry` XDR values.
See the type definitions in https://github.com/stellar/stellar-xdr.
See also https://developers.stellar.org/docs/learn/encyclopedia/data-format/xdr.
Outputs no data when no data is present in the contract.
Usage: stellar contract info meta [OPTIONS]
Options:
--id <CONTRACT_ID> Contract ID to get the meta for
--wasm-hash <WASM_HASH> Wasm hash to get the meta for
--wasm <PATH> Wasm file to extract the meta from
--output <OUTPUT> [default: xdr-base64] [possible values: xdr-base64, json, json-formatted]
Other Options:
-h, --help Print help
Dear @Ifropc, do we have any time estimates for this feature (maybe in some reduced capacity)?
Hi @OlegJakushkin currently working on it, hopefully we can include it into the release coming in 2 weeks (or maybe even next week)