[SEP] Contract Home Domain Interface: a home_domain() getter for Soroban contracts

[farbodghasemlu]

What I'm proposing

A minimal, optional SEP defining a single read-only getter, home_domain() -> String, that lets any Soroban contract declare the domain hosting its SEP-1 stellar.toml. The goal is to restore, for contract-based assets, the on-chain to off-chain metadata link that classic Stellar assets already get from the issuing account's home_domain field.

Prior context

This has come up twice as something that deserves its own standalone SEP, and I'd like to write it:

• In the SEP-50 (Non-Fungible Tokens) discussion ([SEP-50] Non-Fungible Tokens #1674), the single-function shape fn home_domain() -> String was suggested, with the note that SEP-41 and SEP-50 could reference it so certain stellar.toml fields become relevant when it is implemented.
• In the SEP-55 (Contract Build Verification) discussion (Contract Source Validation SEP #1573), reviewers observed that this home_domain linking "could be an independent SEP," and that it is better reported at the contract instance level than at the Wasm hash / meta level, since not all deployments of one Wasm hash should share a single home domain.

The gap

SEP-41 intentionally exposes only name, symbol, and decimals on-chain and is disconnected from stellar.toml. As a result, a Soroban-native token or NFT has no standard way to point back to a domain for the richer, updatable, human-facing metadata (description, image, organization and legal info) that classic assets resolve through SEP-1 today. Every project reinvents discovery, and wallets, explorers, and indexers cannot resolve contract-asset metadata uniformly.

Sketch of the interface

/// Returns the home domain hosting this contract's SEP-1 `stellar.toml`.
/// The value is a fully-qualified domain with no scheme or path, e.g. "example.com".
/// Returns an empty string if the contract declares no home domain.
fn home_domain(env: Env) -> String;

Consumer resolution flow for a contract address C:

1. Call C.home_domain(). If empty, no off-chain metadata is declared; stop.
2. Fetch https://{home_domain}/.well-known/stellar.toml over HTTPS.
3. Parse SEP-1 and select the [[CURRENCY]] entry that identifies this contract by its contract address.
4. Read the SEP-1 currency fields (name, desc, image, organization info) as authoritative off-chain metadata for C.

The function is a getter: no authorization, no state requirement. How a contract stores the value (constant, instance storage, or admin-settable) is left to the implementer.

Open questions I'd like feedback on before drafting

1. Instance-level getter versus a SEP-46 contract-meta entry, or both? SEP-46 standardizes Wasm-level metadata but states it does not cover per-deployment metadata, which seems to favor a function for this case. I'd like to confirm that reading.
2. Can a SEP-1 [[CURRENCY]] entry already be matched to a contract address, or is a small SEP-1 companion change needed to make step 3 unambiguous?
3. Should bidirectional verification (the domain's stellar.toml also listing the contract address, for anti-spoofing) be in scope here, or kept as a separate SEP?

Reference implementation

If there's appetite, I'll provide a soroban-sdk reference implementation of home_domain() plus a consumer-side resolver that returns the SEP-1 metadata for a given contract address.

@leighmcculloch you sketched this home_domain() shape in #1674. Does a standalone SEP match what you had in mind, and is the instance-level getter the design you'd prefer over a contract-meta key?

[tupui]

Good idea 👍

For SEP-50, we do have token_uri which can serve that role though there is not yet a concept of collection and generic information.

We could have a common function to point to a SEP-1 file. Though the SEP-1 spec is too me a bit outdated. We could have more on NFT and contract based assets. I also found myself wanting to use this file for something else.

(Also leaving a note here with my vandeta about https to say that we should generalize and even promote other protocols such as IPFS or even Iroh now that there is a v1.)

[tupui]

The other use case is just having a way to store generic metadata for a contract. Links to docs, what this is about, etc. In Tansu (my DAO-like project if you want) I use the SEP-1 format to describe projects which are registered. At the time I thought it could be good to not re-invente the wheel and base my stuff onto an established SEP. In hindsight, it was not very helpful and I could just have rolled my own version. SEP-1 is just a bit too focused on assets and not generic enough.

There was some discussions on SEP-1 a while back and that motivated the creation of https://sorobandomains.org/docs/key_value_db

[farbodghasemlu]

That makes it clearer, thanks. Sounds like the real issue is just that there's no generic contract metadata format. SEP-1 is asset-focused, and SEP-46 is Wasm-level and fixed at build time, so for mutable per-contract info (docs, description, what it is) you're left bending SEP-1 or rolling your own. You hitting that in Tansu, and Soroban Domains building a key-value db for a similar need, is probably the strongest argument that it's worth standardizing.

The way I'm seeing it, maybe two layers:

1. The pointer: a small function returning a URI to the contract's metadata, whatever format that ends up being.
2. The payload: a generic, non-asset metadata format for the cases SEP-1 doesn't fit.

The pointer's small enough to stand on its own. The generic format is the harder and more useful half, and the part you'd know better than me, since you've already run into where it breaks.

Curious whether you'd lean toward something close to the Soroban Domains key-value model or something more structured. I'll go through Tansu to see how you used SEP-1 there, probably tells me more than guessing would.

[tupui]

I would also go that direction 👍 @overcat this convo could also interest you.

I think there are a few ways to go about this. I think first we can gather use cases and see if there is any point in having a common vocabulary in some places or not. This could also help for things like ERC-8004 (agent reputation) or ERC-7496 (dynamic traits, which I am trying to get into SEP-50.)

[farbodghasemlu]

Makes sense, gathering use cases first feels right rather than jumping to a schema.

The ERC-8004 link is a good one. Its agent card is basically this same shape: an ERC-721 whose URI points to an off-chain JSON describing the agent. So a Soroban agent registry would want exactly the pointer plus a metadata doc we're discussing, which is a nice sign the layering holds up beyond assets. ERC-7496 is a bit different since the traits live on-chain, but its trait-metadata URI part overlaps with the vocabulary question, so worth keeping in view (and good luck with the SEP-50 push).

To get the ball rolling, a rough list of what's come up so far:
asset info (the SEP-1 case)
generic project/contract docs and description (Tansu)
naming records (Soroban Domains key-value db)
agent cards (ERC-8004)
dynamic trait definitions (ERC-7496)

If a few of these end up wanting the same fields (name, description, links, image), that's where a shared vocabulary earns its place. Where they don't, probably better left free-form. I'll keep adding to this as more come up.

Separately, the pointer itself seems uncontroversial enough that I'll write it up as a small standalone draft so it isn't blocked on the vocabulary work. Format stays out of scope there.

[tupui]

I would suggest posting this to the dev discord if you want to get more eyes on it. X and tagging some SCF/SDF accounts is also a good idea.