Skip to content

feat(harness): generate the SEP-1 stellar.toml - #452

Open
hpmaxi wants to merge 7 commits into
tranche-3from
feat/432-sep1-metadata
Open

hpmaxi wants to merge 7 commits into
tranche-3from
feat/432-sep1-metadata

Conversation

@hpmaxi

@hpmaxi hpmaxi commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Summary

Closes #432
Refs #450

Wallets and explorers read an issuer's stellar.toml (SEP-1) to show who issues a token and what backs it. The kit is a template, so it cannot publish one file for every operator. This adds a template and a harness command that fills it in from a deployment: the operator regenerates it after each attestation, so attestation_of_reserve always points at the latest proof.

Changes

  • scripts/harness/lib/stellar-toml.ts: a pure renderer. It turns the chain values and the operator's values into SEP-1 v2.7.0 TOML, and lists every field still open with the reason.
  • npm run sep1 -w scripts/harness: reads the share token's name, symbol and decimals, the network passphrase, the oracle's latest report and the SEP-40 feed from the deployment record, and writes scripts/harness/stellar.<network>.toml (git-ignored). It only reads.
  • Operator values come from a JSON file passed as SEP1_OPERATOR, so a regeneration never overwrites them. The file is checked before any network call; an unknown key, an empty value, an anchor_asset_type outside SEP-1's list or an ORG_URL without https:// is refused, naming the key.
  • docs/sep1/stellar.template.toml: the renderer's output with every field open. A test keeps the two in sync.
  • docs/sep1/stellar.testnet.toml: an example generated from the testnet deployment, operator fields still open.
  • README section "Asset metadata (SEP-1)": prerequisites, the operator file, how to publish (CORS, content type, size), and when to regenerate.

Deviations

  • The SEP-40 feed and the latest report's proof hash and acceptance time are TOML comments, not fields: SEP-1 has no field for a price feed or a proof hash.
  • status defaults to live on the public network and test elsewhere. The operator can set code, name and status in the operator file; a chain value past a SEP-1 limit stays open until they do.
  • An expired latest report still fills attestation_of_reserve, and the command prints a warning.
  • SEP-1 ties a domain to accounts through their home domain, and a SEP-41 contract has none. How a wallet reaches this file for a contract token is not settled here; Find how wallets reach the stellar.toml of a contract token #450 tracks it.

Acceptance criteria

  • A stellar.toml template in the repository, with every operator field marked
  • A harness command that fills it in from a deployment and lists the fields left for the operator
  • The generated file passes a SEP-1 check (valid TOML, contract set for the share token, attestation_of_reserve set to the latest proof_uri)
  • Tests for the generator: a full deployment, no attestation yet, no SEP-40 feed
  • The README explains how to publish it and links the testnet example

Test plan

Automated tests

  1. Harness unit tests: pass. They cover a full deployment, no attestation, no feed, the SEP-1 length limits at and past the edge, escaping, the operator file checks and overrides, the reads (NoRecord versus any other refusal), and the template staying in sync. The SEP-1 check serves each rendered file over local HTTP and parses it with the SDK's StellarToml.Resolver, the same code wallets use.
  2. Root npm run lint, format:check, typecheck: pass.
  3. On a fresh local network: sep1 right after deploy lists attestation_of_reserve as open; after test:happy-path it fills it with the latest report.

Manual verification

  1. HARNESS_NETWORK=testnet npm run sep1 -w scripts/harness (reads only) produced docs/sep1/stellar.testnet.toml.

Breaking changes

None.

Checklist

  • Self-reviewed my own diff
  • Tests added or updated
  • Docs updated (if applicable)
  • No unrelated changes bundled in

Screenshots

None.

- Every operator field left unset by SEP1_OPERATOR now goes into
  missing with the reason to set it there, instead of silently staying
  a placeholder.
- The operator can set code, name and status in the JSON file,
  overriding the chain value and the kit's test/live default; an
  over-limit chain value with no override names SEP1_OPERATOR as the fix.
- parseOperatorValues rejects arrays, empty strings, an unknown
  anchor_asset_type, an ORG_URL without https://, and an over-limit or
  unknown code/name/status.
- U+007F is escaped; a lone surrogate in any value throws, naming the
  field.
- An empty proof_uri leaves attestation_of_reserve open instead of
  publishing a blank link; the report's expiry is threaded through as
  expiresAt.
- The generated file gets a short header; the template keeps the
  longer one, since it is the renderer's output with no inputs at all.
- Dropped a comment restating the next function and one claiming SEP-1
  derives status from the network, which is the kit's own default.
SEP1_OPERATOR now resolves against INIT_CWD, the directory npm was
called from, the same way extend-target.ts resolves --config; before
this, the README's own example broke when run from the repo root.

The command now reads and checks the operator file before connecting
to the chain, so a bad path or malformed JSON is reported without a
wasted round trip, and names the file on a syntax error.

It also prints a warning when the oracle's latest report has expired,
instead of publishing an expired attestation with no sign of it.
- Name the deployment record and keys file the command needs, say it
  writes a whole file, and the operator keys list now covers the new
  code/name/status overrides with an updated JSON example.
- A domain already serving a stellar.toml must merge the share's
  currency entry in, instead of publishing the generated file as is.
- State plainly that SEP-1 links a domain to an account through its
  home_domain, and a SEP-41 contract has none, so this is unsettled.
- TESTING.md: drop a phrase no test covers, split the wallet-parse
  test into its own row, and add the sep1-reads and sep1-operator
  test rows.
- Regenerate the testnet example with the new short header; the
  template is unchanged, since the renderer's empty output did not
  change.
@vercel

vercel Bot commented Nov 13, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
strata-vault-kit-app Ready Ready Preview Nov 13, 2026 2:29pm UTC

Request Review

@hpmaxi
hpmaxi changed the base branch from feat/236-sep40-feed to tranche-3 November 13, 2026 14:43

This branch was successfully deployed

1 active deployment
Preview — d8daefd2 Deployed Nov 13, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant