Onboard router: one-method onboarding with on-chain capability discovery (CAP-68 + CAP-73)

[willemneal]

Replaces the asset-dependent two-path onboarding flow with a single Soroban "discovery router" method that learns an asset's trust-establishment capability on-chain, so the client never branches on per-asset config. Built TDD from the committed design spec + plan (in docs/superpowers/; the older two-path design is retained there, marked superseded).

The pivot

One method does it all:

onboard(env, sac: Address, holder: Address) -> Result<OnboardStatus, Error>

• holder.require_auth() — the holder signs once, over the whole auth tree.
• CAP-68 sac.executable() — refuse a sac that isn't a real Stellar Asset Contract (on-chain anti-copycat), then detect whether the SAC admin is a Wasm contract.
• CAP-73 trust() — idempotent; creates the trustline (no-op if it exists). Open asset (!AUTH_REQUIRED) → already authorized → Authorized.
• Otherwise call try_authorize_trustline(holder) on the discovered admin and classify: Ok + authorized → Authorized; Ok + still unauthorized → Err(NotAuthorized); a typed contract error → Err(AuthorizationRefused); any other recoverable error (no export / panic / non-contract admin) → Ok(TrustlineOnly).

OnboardStatus = { Authorized, TrustlineOnly }; Error = { NotSac=1, TrustFailed=2, AuthorizationRefused=3, NotAuthorized=4 }. The try-call classification is verified against soroban-env-host 26.1.3 (a 6-test spike pins the env semantics).

Why on-chain discovery: only a SAC's admin can set_authorized, so "the admin exports authorize_trustline" is the definition of one-step capability — the old authorizer config/toml field was a spoofable copy of sac.admin(). Discovering it on-chain removes the trust assumption.

Changes

• Contract (contracts/trustline-onboard) — the 2-arg discovery router; 16 Rust tests (10 scenario + 6 env-classification), incl. typed-rejection revert, no-export/panicking admin → TrustlineOnly, post-condition NotAuthorized, impostor-SAC rejection, real G-account holder. # Security documents the holder-signed auth tree over the asset-chosen admin's sub-invocations.
• SDK (packages/authline-sdk, 0.3.0) — buildOnboardTx targets the router; buildTrustTx + the old 3-arg onboard deleted. Per-network ROUTERS singleton pinned + StrKey-validated; reconcileWithRegistry checks the advertised router against the pin even for uncurated codes (asset-independent). Shared decodeOnboardStatus decodes the router's return value; the React hook + ActivateButton now report TrustlineOnly truthfully instead of "Activated" on every tx success.
• Reads via Stellar RPC — Horizon dropped — getActivationStatus reads the trustline straight from the ledger (getLedgerEntries); assetAuthRequired deleted (capability is discovered on-chain); buildSponsoredOnboardTx uses rpc.getAccount. One endpoint, one allowHttp (localhost-only by default), and the prior "insecure horizon server" failure class is gone.
• dApp (src/) — single activate() path through the router; truthful success state decoded from OnboardStatus ("trustline created" vs "trustline authorized"); a missing/undecodable outcome falls back to the static capability so it never over-claims authorization; missing-router gates the CTA. Live asset defaults network-aware (mainnet → EURCV, every other network → the pinned testnet USDC) so a dev on testnet gets a working asset.
• SEP draft (sep/SEP-XXXX-…) — v0.3: verbatim contract code, the typed-error-MUST rule, the OnboardStatus/router model; records the v0.3 discovery-router testnet run.
• CI — the build job now runs npm run test:contracts (the router's correctness lives in those Rust tests); the workflow-dispatch e2e-testnet job runs the full tests/e2e suite (no longer orphaning the TLO discovery test) with a concurrency guard.
• Deploy — router pinned on testnet (CABVVUYHXS6UVN2VYYXKEUO2XEJIAGMTEYF2BOWGUUJVOO2IGPRWZAX4). Mainnet deploy is a tracked follow-up, gated on a fresh on-chain EURCV sac.admin() read.

Test Plan

• npm run lint · npm run typecheck · npm run build — green
• npx vitest run — 26 passed, 2 real-chain e2e skipped by default (RUN_TESTNET_E2E gate)
• npm run test:contracts — 17 Rust tests pass (16 router + 1 authorizer-stub; cargo test -p trustline-onboard -p authorizer-stub)
• npm run test:e2e:testnet — 2 passed on real testnet: USDC open → Authorized; TLO AUTH_REQUIRED → trustline created AND authorized via on-chain admin discovery ({ hasTrustline: true, isAuthorized: true }, read back over RPC)
• npm run test:e2e — Playwright browser e2e 1 passed on real testnet (directory → connect → activate → authorized USDC trustline)

Notes

• CI gates PRs on the offline suite (incl. contract tests); the real-testnet e2e are workflow_dispatch-only.
• Mainnet router deployment + EURCV one-step wiring are tracked follow-ups (not in this PR).

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://theahaco.github.io/stellar-assets/pr-preview/pr-16/
Built to branch gh-pages at 2026-06-10 17:02 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[Dgetsylver]

Reviewed the design — mechanism is verified-sound; a few concrete changes before code lands. I ran the open-asset path on real testnet against the repo's resolved SDK (14.5.0), and the core holds:

• prepareTransaction on SAC.trust(holder) decodes + submits in pure JS — no P26 "Bad union switch" (that only hits the set_authorized flag-write, not trustline creation). tx 523d7ad5…
• the resulting open trustline reports is_authorized=true → the status / "already authorized" / success screens work unchanged
• SAC.trust ABI is a single Address arg (§5.1's flagged open item — confirmed)

Must-fix

1. Registry entry is off vs the live issuer. Circle's testnet USDC issuer GBBD47IF… actually has auth_revocable=true (Horizon read), but §5.2 pins authRevocable:false — that suppresses the dApp's freeze warning (authline.tsx:583). Also homeDomain is centre.io, not circle.com. Suggest stamping verifiedAt only after the on-chain read.
2. assetIssuer has no registry fallback. config.ts does PUBLIC_ASSET_ISSUER ?? <hardcoded EURCV issuer> (unlike sac, which falls back to pinned?.sac). So a testnet env that sets only PUBLIC_ASSET_CODE=USDC yields {code:USDC, issuer:EURCV} → getActivationStatus queries the wrong issuer and never finds the trustline. §5.3's "config.ts needs no code change" doesn't hold — either also set PUBLIC_ASSET_ISSUER in the e2e env, or add a pinned?.issuer fallback (and state which).
3. .env.e2e won't be auto-loaded. Vite only loads .env.[mode] under --mode; the spec's vite preview runs production mode → PUBLIC_ASSET_CODE unset → defaults to EURCV. Use --mode testnet (.env.testnet), or load via dotenv in the Playwright webServer.

Test gating

4. The PR-gating unit test won't catch the only real risk. buildTrustTx.test.ts mocks prepareTransaction, so the blocking check never exercises the live decode; the layer that does (§6.4 testnet e2e) is opt-in/non-blocking, so a decode regression could merge green. Worth a thin blocking decode smoke (RPC prepareTransaction only — no fund/submit).
5. The permissioned EURCV path has no e2e, and it's the fragile one — its set_authorized flag-write is exactly what breaks the JS decoder. A standing (non-blocking) check against the deployed wrapper (PUBLIC_ONBOARD=CCQJ53C6…) would guard it.

Spec clarity

6. State the funding split. trust() has no sponsorship — it needs a funded holder (0.5 XLM reserve plus the Soroban resource/inclusion fees), so it can't onboard a brand-new zero-XLM user. The third-party "onboard during withdrawal" case still needs buildSponsoredOnboardTx (CAP-33). Worth noting it's retained, not superseded, so the sponsored path doesn't read as dead.
7. "Mainnet stays EURCV" rests on a repo var (PUBLIC_STELLAR_NETWORK_PASSPHRASE), not a committed .env — and config falls back to testnet if unset (config.ts:23). Worth verifying the var + a "never set PUBLIC_ASSET_CODE in repo vars" guard.

Nice-to-have

• Compile-time gate window.__AUTHLINE_E2E__ so it tree-shakes out of the prod bundle (non-custodial dApp — a wallet-override hook is worth keeping out of mainnet).
• Open-asset UI copy is permissioned-specific ("Auth req." pill, "then authorizes the line") — branch on ASSET.capability.

Mechanism, ABI, and decode are verified on-chain, so the path to merge is mostly the registry entry + env wiring + CI gating. Nice spec.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​playwright/​test@​1.60.0

View full report