[Enhancement] SEP-1 stellar.toml hosting: publish org, account, and asset metadata at /.well-known/stellar.toml

[zeemscript]

Summary

Host a SEP-1 stellar.toml at /.well-known/stellar.toml so the DeenBridge platform is discoverable and verifiable across the Stellar ecosystem — wallets, explorers, and directories can resolve the platform's organization metadata, declared accounts (the platform/payout wallet), and the assets it deals in. Today DeenBridge builds and submits real Stellar payments but publishes no ecosystem metadata at all, so there is no canonical, machine-readable statement of "who this service is" or "which USDC issuer it trusts."

Current state

• There is no /.well-known/* route anywhere. app.js mounts /, /health, and the /api/* routers only — a grep for well-known, stellar.toml, or toml across src/ and app.js returns nothing.
• Asset identity is hardcoded in code, not published anywhere: src/services/stellar/stellarService.js pins USDC_ISSUER per network (GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN on mainnet, a testnet issuer otherwise) and exports USDC, USDC_ISSUER, NETWORK, networkPassphrase. Nothing declares these to the outside world.
• The platform is heading toward flows that assume ecosystem trust and discoverability — SEP-10 "Sign in with Stellar" ([Enhancement] SEP-10 Web Authentication: challenge/verify endpoints and JWT issuance for "Sign in with Stellar" #25), SEP-24 anchors ([Enhancement] SEP-24 anchor integration: non-custodial fiat on/off-ramp for USDC via interactive deposit and withdrawal #46), and signed webhooks ([Enhancement] Signed webhook event system: HMAC-signed payment lifecycle callbacks with retries and dead-letter redelivery #45) — all of which conventionally reference a stellar.toml (WEB_AUTH_ENDPOINT, SIGNING_KEY, TRANSFER_SERVER_SED0024, CURRENCIES). There is no home for those keys today.
• Network is env-driven (STELLAR_NETWORK, default testnet), so the served TOML must switch issuer/passphrase/URLs the same way stellarService.js already does.

What to build

1. Static-but-templated TOML endpoint (src/routes/wellKnownRoutes.js, mounted before the /api rate limiter in app.js at app.get("/.well-known/stellar.toml", ...)): serve Content-Type: text/toml; charset=utf-8 with permissive CORS (Access-Control-Allow-Origin: *) as SEP-1 requires for cross-origin fetching.
2. Config-driven document builder (src/services/stellar/stellarTomlService.js): assemble the TOML from a typed config object so values stay in sync with stellarService.js. Include at minimum:
   • VERSION, NETWORK_PASSPHRASE (reuse networkPassphrase), ACCOUNTS = [ <platform/payout public key> ].
   • [DOCUMENTATION] — ORG_NAME = "DeenBridge", ORG_URL, ORG_DESCRIPTION, ORG_LOGO, official contacts / Telegram.
   • [[CURRENCIES]] — a block for the USDC the platform settles in (code = "USDC", issuer = <USDC_ISSUER for the active network>, is_asset_anchored, status, display metadata). Make it iterate a list so multi-asset support ([Enhancement] Verify signed Stellar transaction contents before granting item access #18) can add more.
   • Placeholder-but-wired keys for the in-flight SEPs: WEB_AUTH_ENDPOINT ([Enhancement] SEP-10 Web Authentication: challenge/verify endpoints and JWT issuance for "Sign in with Stellar" #25), SIGNING_KEY, and a commented [[CURRENCIES]]/transfer-server hook (Dev #24/[Enhancement] SEP-24 anchor integration: non-custodial fiat on/off-ramp for USDC via interactive deposit and withdrawal #46) that later issues can fill in without restructuring.
3. Env plumbing: add STELLAR_PLATFORM_PUBLIC_KEY, ORG_URL, ORG_LOGO, and SIGNING_KEY (or reuse existing) to src/config/validateEnv.js's optional list, and document them in .env.example/QUICK_START.md. The endpoint must still render (omitting unknown blocks) when optional values are missing, so CI's boot check stays green.
4. Validity: output must be parseable TOML and pass a SEP-1 linter (e.g. round-trip through a TOML parser in the test). Field names must match the SEP-1 spec exactly (case-sensitive).

Acceptance criteria

• GET /.well-known/stellar.toml returns 200 with Content-Type: text/toml and Access-Control-Allow-Origin: *, and is reachable without authentication or tripping the /api rate limiter.
• The served document parses as valid TOML and contains NETWORK_PASSPHRASE matching the active network, an ACCOUNTS entry for the platform wallet, [DOCUMENTATION] org metadata, and at least one [[CURRENCIES]] block whose issuer equals USDC_ISSUER for the active NETWORK.
• Switching STELLAR_NETWORK between testnet and mainnet changes the passphrase and USDC issuer in the output (no hardcoded duplication — values come from the same source as stellarService.js).
• Missing optional env vars degrade gracefully (block omitted, no 500); server still boots and /health passes.
• Jest + supertest test fetches the endpoint, asserts the content type/CORS header, parses the body as TOML, and checks the issuer/passphrase for a stubbed network.

Pointers

• app.js (route mounting order — must precede app.use("/api", apiLimiter)), src/services/stellar/stellarService.js (USDC_ISSUER, USDC, NETWORK, networkPassphrase exports to reuse), src/config/validateEnv.js (optional env list), QUICK_START.md/README (document the new vars).
• Align with, do not duplicate: [Enhancement] SEP-10 Web Authentication: challenge/verify endpoints and JWT issuance for "Sign in with Stellar" #25 (SEP-10 — will populate WEB_AUTH_ENDPOINT/SIGNING_KEY), [Enhancement] SEP-24 anchor integration: non-custodial fiat on/off-ramp for USDC via interactive deposit and withdrawal #46/Dev #24 (SEP-24 — transfer server keys), [Enhancement] Verify signed Stellar transaction contents before granting item access #18 (multi-asset — extends [[CURRENCIES]]).
• Gotchas: SEP-1 mandates the exact path /.well-known/stellar.toml, text/toml content type, and CORS *. .github/workflows/ci.yml boots the server and curls /health, and runs node --check on every file, so a syntactically broken route fails CI immediately. PRs target dev.

Difficulty

Medium — no signing or network calls, but it requires correct SEP-1 field semantics, network-aware templating that shares a single source of truth with the Stellar service, and forward-compatible structure so the SEP-10/SEP-24 issues can slot their keys in without a rewrite.

---

🏆 GrantFox OSS — Official Campaign | FWC26. Apply for this issue through the GrantFox campaign page. The maintainer assigns one contributor before work starts; unassigned PRs may not be reviewed. PRs target the dev branch. Quality bar: CI must stay green.

💬 Questions or need help? Reach the maintainers and other contributors on the DeenBridge Telegram: https://t.me/+nst9lXNj1wc4ZDE0

[vreabernardo]

I’d like to work on this for the FWC26 campaign. I’ll add the network-aware SEP-1 route, TOML parser coverage, and the requested env/docs updates. Please assign me if it’s available.

[Myart352]

Hello DeenBridge team,

I'd like to apply for this issue.

After reviewing the requirements, I understand that the goal is to implement a fully compliant SEP-1 stellar.toml endpoint that serves as the platform's canonical Stellar metadata while remaining synchronized with the existing Stellar configuration and future SEP implementations.

My implementation approach would be to introduce a dedicated stellarTomlService responsible for generating the document from a typed configuration rather than hardcoding values. This will allow the endpoint to reuse the existing exports from stellarService.js—including the active NETWORK_PASSPHRASE, USDC_ISSUER, and network configuration—ensuring there is a single source of truth when switching between testnet and mainnet. I'll expose the document through /.well-known/stellar.toml with the required text/toml content type and permissive CORS headers, mounted before the /api rate limiter as specified.

The implementation will include the required SEP-1 fields such as VERSION, ACCOUNTS, [DOCUMENTATION], and [[CURRENCIES]], while gracefully handling optional environment variables by omitting unavailable sections instead of failing application startup. I'll also structure the document so upcoming SEP-10 and SEP-24 work can plug in WEB_AUTH_ENDPOINT, SIGNING_KEY, and transfer server metadata without requiring a redesign.

Finally, I'll provide comprehensive Jest and Supertest coverage to validate the endpoint, response headers, TOML parsing, network-aware issuer selection, and graceful handling of missing optional configuration, ensuring the implementation is standards-compliant and CI remains green.

Thank you for considering my application.

[Ahbiz]

i have experience with the stack and i ve reviewed the code

[grantfox-oss]

🦊 GrantFox — @Ahbiz has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #58)
2. Your PR will be reviewed by the Deen-Bridge maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@Ahbiz's PR #75 was approved and merged by @zeemscript.

🏆 @Ahbiz: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (153 total points). Track your full progress on GrantFox.

👏 Great work, @Ahbiz! Keep contributing to Deen-Bridge.