Contract metadata key registry

[ifropc]

Background

Soroban contracts have WASM metadata, defined in SEP-46. This SEP describes how metadata should be stored in the WASM. However, this SEP doesn't have any guidance on what metadata keys could be stored there.

Motivation

With lack of centralized document with common keys it's hard to find which keys are used by other SEPs (unless you search other SEPs trying to find if they it turn support SEP-46), and some common tools (such as Soroban SDK)

Proposal: standard metadata keys

We should add metadata key registry to SEP-46.
We should not make any attempts to strictly standardize it (i.e. it's okay for SEP to not list some fields using by some libraries or tools, but they are free to add the keys they are using to this list). With SEP-9 we discovered that it's sometimes hard to predict the usage of the SEP by the ecosystem, and very often people are using some fields that are not defined by the SEP. Given that, I strongly suggest we do not make any keys mandatory, at least not for the 'minimal' contract (or use case).
That being said, another SEPs (such as contract version SEP-49) should define mandatory (for this SEP) metadata keys, and I think it's a good idea to keep this "common" keys in once place.

We could add a table of 'commonly used keys':

Key name	Description	Required by SEP	Used by tool
rsver	Version of rust used to compile WASM	N/A	Soroban SDK
rssdkver	Soroban SDK dependency version used when compiling WASM	N/A	Soroban SDK
name	The name of the contract	N/A	N/A
authors	The author(s) of the contract, often with an email	N/A	N/A
homepage	The relevant domain to relate to this contract	N/A	N/A
repository	The source repository URL for the contract	N/A	N/A
binver	The version of the WASM bytecode of the contract	SEP-49	N/A
sep	Indicates which SEPs contract claims to implement	SEP-47	N/A

Proposal: Metadata keys in Cargo toml file

In addition, it would be nice to standardize following approach used in Scaffold Stellar -- it allows users to put contract metadata in the contract's Cargo toml file and I think it improves user experience and other tools could benefit from supporting this feature.
Example of Cargo toml:

[package.metadata.stellar]
rsver = "ignored" # It's set by Soroban SDK and can not be overridden 
rssdkver = "ignored"
cargo_inherit = true # Specific to Scaffold but could be standardized. When set to 'true' will inherit , authors, homepage, repository and version from Cargo toml file 
name = "my-soroban-contract" # Even if we inherit a field, we could always override it 
home_domain = "example.com" # can be defined either as `homepage` or `home_domain`
repository = "https://github.com" # will be renamed to source_repo
my_custom_string = "foo"
my_custom_bool = true
my_custom_int = 1

[package.metadata.stellar.object]
simple_array = ["a", 123, false]
complex_array = ["a", { inner_array = ["b", "c"] }]
my_custom_object = { field1 = "val1", field2 = [ "single element array" ] }

And this is how it looks like when running stellar contract info meta on it:

> stellar contract info meta --wasm target/stellar/registry.wasm
ℹ️ Loading contract spec from file...
Contract meta:
 • rsver: 1.86.0 (Rust version)
 • rssdkver: 22.0.4#1d4afb3b981a4f4b2bbc19f0ce38af85c4ab316a (Soroban SDK version and it's commit hash)
 • authors: Example Authors <[email protected]>
 • binver: 0.1.0
 • home_domain: example.com
 • my_custom_bool: true
 • my_custom_int: 1
 • my_custom_string: foo
 • name: soroban-registry
 • object.complex_array[0]: a
 • object.complex_array[1].inner_array: b,c
 • object.my_custom_object.field1: val1
 • object.my_custom_object.field2: single element array
 • object.simple_array: a,123,false
 • source_repo: https://github.com```

[leighmcculloch]

Re: Proposal: standard metadata keys

Some context on why SEP-46 doesn’t contain a registry: It is primarily so that the definition of meta is decentralised, avoiding the issue of permissioning with regard to whether SDF or the SEPs author (me in the case of SEP-46) thinks a meta entry is worthy enough to be included.

For the most part SEPs should be able to define meta keys they use and how they get used, and anyone needing to implement those SEPs will know how to use them and what they mean. Take the source_repo field for example.

For meta driven by tooling, SEPs may not even be necessary. The Rust SDK has injected meta for a couple years without a SEP, and has been put to use by folks in different ways.

If the proposal is some new meta fields like name, author, etc, that the hope is would be found on all contracts, that aren’t otherwise tied to any specific SEP or protocol but provides folks with a description (name, version, etc) of contracts, then that sounds like you could propose a new SEP focused on those meta, called something like “Descriptive Contract Meta”.

Thoughts @janewang and others?

[pselle]

@janewang This comment sub-thread is where we're looking for if we want to create a SEP related to specific contract metadata keys, given the intention of SEP-46 to not explicitly define them. What do you think?

[leighmcculloch]

Re: Proposal: Metadata keys in Cargo toml file

This look very cool.

It's possible for the Rust SDK to inject the meta from the toml, so we could consider adding that capability to the Rust SDK so it gets picked up automatically by any build. We discussed doing this for the Cargo.toml version field for SEP-49: #1670 (comment).

Something to consider and weigh is that meta via Cargo.toml creates a third way to define meta, so I wonder if the value in adding a third way outweighs the cost of having three ways to do something.

Contract meta can be injected today in two ways:

1. In code using contractmeta!(key = ..., val = ...), and in the next version of the Rust SDK it will support the use of environment variables, files, and concat!, with contractmeta!(key = ..., val = env!("...")) and contractmeta!(key = ..., val = include_str!("...")). Helpful in that modules and packages can define their own meta that gets included at build time, keeping definitions close to implementations.
2. In the terminal with stellar contract build --meta key=val.

[pselle]

It's reasonable to consider whether a third option is warranted; I like this version a lot though. Adding at the Cargo.toml layer is much more "configuration" where then I imagine adding contractmeta! macros in-code might be done more decision-based (such as if the wasm was built with a particular feature). Pro adding it as a default build behavior.