[SEP-47] Contract Interface Discovery

[leighmcculloch]

Hi all, below is a proposal for how a contract can claim to implement a SEP.

The idea captured in this proposal was first shared in conversation that happened here:

• Contract code entry provides catalog of app protocols and events supported #1596 (comment)

Feedback appreciated.

---

See:

• Add Standard Interface Discovery SEP #1687

[JakeUrban]

Overall I think this is valuable not just for clients who are trying to determine how to interact with the contract but also for clients looking to collect data on what SEPs are implemented on the network. Like you said in Security Concerns, I do think this SEPs should be accompanied by another that defines how to verify the claims contracts make about the SEPs they implement, but we can tackle that separately.

One thing I want to clarify is how SEPs relate to each other and what that means for this proposal. Lets say there is a Final SEP for some type of token (ex. NFTs). If I believe the SEP is insufficient, and that it should have another function for some additional functionality, do I propose a new SEP that contains the original interface in addition to my new function, or a SEP that references the original and only defines the new function?

If its the former, and SEP-1001 is a superset of SEP-1000, then I could see contract authors mistakenly defining their meta entry as sep: 1001, as opposed to sep: 1000,1001, and this would mean clients that aren't aware of the superset SEP wouldn't be able to determine if it complies with SEP-1000.

[leighmcculloch]

SEP-1001 is a superset of SEP-1000, then I could see contract authors mistakenly defining their meta entry as sep: 1001, as opposed to sep: 1000,1001

It's an interesting problem, but it also seems like a bug, and so maybe this is better addressed by tooling. I don't think there's much we could add to the proposal that would eliminate this problem?

I do think this SEPs should be accompanied by another that defines how to verify the claims contracts make about the SEPs they implement, but we can tackle that separately.

The main reason I didn't address this in the proposal is that it's reasonably fuzzy in the Soroban ecosystem compared to say Ethereum. In Ethereum implementing an interface requires implementing all the functions exactly. In Soroban we're in the process of adding new functions to SEP-41 (e.g. #1590), and this idea of incremental improvement necessitates that the method by which claims and proof are derived are somewhat imperfect.

I think the process of "verifying" that contracts impl a SEP should instead be the focus of a product or a tool, rather than a SEP, at least as a starting point. Something akin to the anchor verification tool. And that tool would address the first issue you mentioned also. Wdyt?

[JakeUrban]

don't think there's much we could add to the proposal that would eliminate this problem?

Not to this proposal, but it may be worth clarifying in materials we have that describe how to propose SEPs.

this idea of incremental improvement necessitates that the method by which claims and proof are derived are somewhat imperfect.

I think I agree. SEP41 is in draft, so even breaking changes are still technically fair game, and any tool (whether it implements a SEP or not) that attempts to determine whether a contract complies with SEP41 will naturally lag behind when changes are made.

But when SEPs are final, I would think the tool would be able to determine with certainty that a contract complies with a SEP if the definition of "comply" is that it must implement all functions defined in the SEP in order to be considered compliant.

However, I'd argue that the proper emission of events should also be included in the definition of "compliance", and I don't know if its possible to verify whether a contract emits events of the correct schema at the appropriate times.

Also, even including events in the definition of compliance, I don't know if thats sufficient. USDL for example implements the SEP41 functions and emits events appropriately for those functions, but because all balances change when a multiplier defined in contract storage is updated, and transfer events aren't emitted for all addresses that hold a balance, it breaks assumptions that SEP41 clients have.

[leighmcculloch]

But when SEPs are final, I would think the tool would be able to determine with certainty that a contract complies with a SEP if the definition of "comply" is that it must implement all functions defined in the SEP in order to be considered compliant.

When a SEP is final it is signalling that it won't change anymore, but there could be still meaningful contracts implementing different versions of that SEP with earlier versions that missed some functions. So I think the answer to this is SEP dependent. SEP-41 for example will very likely always allow some functions to be optional as it does today. This is because SEP-41 takes the approach of maximally specifying the token interface and allowing implementers to not implement chunks, rather than a narrow basic implementation that is extended.

I don't know if its possible to verify whether a contract emits events of the correct schema at the appropriate times.

I don't think it's realistic to do this, at least today.

[leighmcculloch]

This proposal, and the fact that SEPs provide optional functions, doesn't do a good job of providing a way to signal whether those sub-features of a SEP are supported by the token. For example, this proposal doesn't help you figure out if the SEP-41 implementation supports clawback, or allowances.

[leighmcculloch]

I think the way we've thought about this problem before is that you'd try to call the function, and handle the error and assume any error means it is unsupported. Although that may not be specific enough to correctly handle errors, so I hesitate to suggest that approach.

[orbitlens]

Is there any specific reason why you prefer using contractmeta!() macro instead of the contract meta section that you proposed here?

Also, is there any example contract deployed on Testnet/Pubnet which contains such metadata? Would be nice to take a check how it will look from the parser perspective.

[leighmcculloch]

The contractmeta!() macro writes the key-value to the Wasm custom section with name contractmetav0. The meta can also be added via the CLI, with the --meta option on the stellar contract build command. They're the same thing, the meta is written into the same place with the same format. For something like this proposal, I think using the macro is preferred because the claim about the SEP implementation can be placed very close to the implementation itself. It also means someone doesn't need to remember to add the --meta option. But the proposal just demonstrates the macro as an example, it doesn't matter to the proposal how the meta is added, just that it is added.

All contracts build with the Soroban Rust SDK contain meta. There are some fields that the Rust SDK injects by default, the rsver that is the Rust version, and the rssdkver that is the Rust SDK version. Contracts can then add any other meta they'd like.

For example:

$ stellar contract info meta --network testnet --wasm-hash bf7adb09076853eb3aa569278754111d86e161e35e7dc6a984ecde2b9d6700ae
ℹ️ Network: Test SDF Network ; September 2015
🌎 Downloading contract spec for wasm hash: bf7adb09076853eb3aa569278754111d86e161e35e7dc6a984ecde2b9d6700ae
Contract meta:
 • rsver: 1.77.2 (Rust version)
 • rssdkver: 20.5.0#9e2c3022b4355b224a7a814e13ba51761eeb14bb (Soroban SDK version and it's commit hash)

[orbitlens]

Ah, sorry, didn't know that the macro saves the meta in the same section as CLI --meta option, thought it was something different. Then everything looks straightforward. It seems like this proposal is not opinionated about the actual SEP implementation while providing good flexibility and discoverability.

[leighmcculloch]

I should modify it to make this clearer. It specifies a dependence on "SEP-META", which discusses the custom section, but this proposal could make that clearer still.

[leighmcculloch]

I've added this section to the SEP at the top of the discussion to clarify the current intent of this proposal to only provide access to the meta off-chain.

No Support for On-Chain Access

This proposal stores the SEP in the contract meta, which is not available to contracts to inspect. This proposal is primarily solving the problem of off-chain systems evaluating whether contracts intend to implement a SEP, and not on-chain contracts evaluating the same.

However, I am now questioning if that is appropriate.

On Ethereum the approach used is documented in ERC-165 and it is a runtime evaluation, not a static value. Being a runtime evaluation a contract can ask another contracts if they implement certain interfaces.

❓ If Soroban also wanted a runtime evaluation, should this proposal be that too, so there's a single way to evaluate and it requires calling the contract.

❓ Or, should both approaches co-exist, so there's a simple static way to identify SEP-41 tokens from the outside looking in, and contracts can also call a function to ask a contract as well about if it has specific functions.

[orbitlens]

Is it possible to expose a standard function in the contract client to read information defined with the contractmeta! macro? This way a contract can read the meta from another contract in runtime (e.g. to determine supported standards) and off-chain systems also will be able to read the same data directly from the WASM binary.

My primary concern for supporting two standards is that people tend to make mistakes, so they may define the interface but will forget to set contractmeta!, or simply provide not-matching specifications which may lead to confusion.

so there's a single way to evaluate and it requires calling the contract

That's not a viable approach for stream ledger processing from the perspective of indexers. We need to be able to categorize a contract without contract invocations.

[leighmcculloch]

These are all great points, which lead me to think we should run with this proposal as is, as it is most accessible for indexers and offchain systems, and offchain SDK clients could be updated to query it as well relatively easily.

If the need arises for contracts to also query this information, we should do as you say and add a host function that a contract can use to test if a SEP is supported by looking up the value in the meta. There's no way to access that information today from within the contract, so adding a host function would probably be what we'd need to do to expose it.

[leighmcculloch]

Hi all, I'd like to move ahead with this SEP. The feedback above has been positive, and no new concerns have arisen.

Here is the PR:

• Add Standard Interface Discovery SEP #1687