[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.

[JakeUrban]

Something I didn't see mentioned in the above conversation was SEP-42. This SEP doesn't address the on-chain --> off-chain link, like this discussion is focused on, but the reason I bring it up is because it offers a better trust model than SEP-1.

SEP-1's [[CURRENCY]] list and stellar assets' home_domain field enable an application to verify that the asset's issuer (or in this case, the contract) associates itself with the returned home domain and vice-versa. This ensures the token metadata displayed by an application is correct, but it doesn't ensure the token or domain is safe to interact with.

SEP-42 allows applications to trust the maintainer of an asset list, which means the data included in the list is not just correct but also all tokens listed are safe. When Freighter looks up a token, it first checks if the token is included in a trusted asset list, and if it is, we use the metadata included in the list entry, instead of the metadata referenced in the stellar.toml file of the domain referenced on the issuer's home_domain field.

My point here is that we prefer to source metadata from trusted sources, and maybe the ecosystem generally should consider doing the same. The absence of a SEP for a home_domain() function naturally pushes applications towards this approach, at least for contract tokens.

[farbodghasemlu]

Fair on the trust model, and it belongs in the spec rather than a thread, so I'll put it there. Self-asserted, not a trust signal, defer to a trusted list where one covers the token.

Scope is where I'd still argue. Asset lists cover tokens someone decided were worth curating. They don't cover project docs, naming records, agent cards, and nobody is going to curate a list of every contract's documentation. That's how this thread started, with Tansu bending SEP-1 and Soroban Domains rolling its own kv db. The missing function didn't push those toward lists, it pushed them into one-off formats.

There's also the input side. A curator seeing a new contract token has to get its metadata from somewhere, and today that's mostly manual submission. A standard self-description makes it mechanical. Read what the contract claims, check the domain claims it back, then decide whether to list it. Trust call still sits with the curator.

Mostly I'm trying to figure out if this is dead on arrival for you. If Freighter would never touch a self-reported pointer even just to find tokens to curate, tell me and I'll drop the asset side and keep it to the contracts nothing else describes. If it's worth something to you, I'll shape the wording around what you'd actually use.