Trustline Onboarder - third-party trustline onboarding for classic assets

[hugo-heer]

Receiving a classic Stellar asset requires the holder to create a trustline, and an AUTH_REQUIRED asset stays unusable until the issuer authorizes it. In a CEX withdrawal this lands as a context-free "create a trustline" prompt mid-withdrawal.

The invariant we build on rather than fight: creating a trustline always requires the owner's own signature. No third party can create one for a non-custodial user. So onboarding someone into an asset can't mean signing for them. It means the third party does everything else: pays the reserve via CAP-33 sponsorship, authorizes on the issuer's behalf through a permissionless on-chain contract, and orchestrates the transaction. The user is reduced to at most one in-flow signature, and for an existing unauthorized trustline, zero.

The draft defines:

A Trustline Authorizer contract installed as the asset's SAC admin (building on admin-sep, SDF discussion #1670), exposing a permissionless authorize_trustline gated by a denylist or allowlist policy.
A one-signature onboard(sac, holder) router over CAP-73 trust() that discovers the asset's capability on-chain via CAP-68, so clients don't branch on asset class.
A [TRUSTLINE_ONBOARDER] stellar.toml block, an integrator interface, and an audit event per state transition.
It serves open assets (USDC, EURC) and regulated AUTH_REQUIRED assets (EURCV) under one interface, assuming the regulated model for all assets was our biggest early mistake.

Status: an authorizer of this shape has been live on mainnet as EURCV's SAC admin. The asset-agnostic version, the router, an SDK, an issuer CLI and an HTTP relayer run on testnet, with transaction hashes recorded in the draft. Apache-2.0, funded by SCF #44.

Draft: https://github.com/theahaco/authline/tree/main/sep
Feedback welcome.

[leighmcculloch]

Reading sep_trustlineonboarder.md@6833212:

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

fn authorize_trustline(env: Env, account: Address) -> Result<(), Error>

I'm reading the SEP and trying in my mind to separate what the requirements are of an implementer who wants to make a new implementation or tools/wallets that plan to interop with implementations, are the points of interop just the two functions above (onboard, authorize_trustline) and their respective status and error types?

Are the other Authorizer functions and the admin-sep dependence just implementation details of the reference implementation or is every implementation dependent on those too?

[hugo-heer]

Hello !

• Yes you are right, the interop points are onboard and authorize_trustline with their respective status and error types. The router only calls authorize_trustline.

• Every Authorizer implementation is also bound to admin-sep and the full admin surface yes

[leighmcculloch]

interop points are onboard and authorize_trustline

👍🏻 Thanks for confirming.

bound to admin-sep

For contracts that interact with the authorizer and the asset to get onboarded, what functions of the admin-sep do they need to call?

[hugo-heer]

None. On the onboarding path a consumer only calls the SAC's built-in trust, authorized and admin plus the Authorizer's authorize_trustline. The admin-sep surface (admin/set_admin/upgrade and the lifecycle entry points) is only used by the issuer to govern the Authorizer

[leighmcculloch]

The admin-sep surface (admin/set_admin/upgrade and the lifecycle entry points) is only used by the issuer to govern the Authorizer

It sounds like the admin-sep surface is an implementation detail that probably doesn't need to be part of the SEP? i.e. This SEP can compose (or not) with Admin SEP, but they are otherwise decoupled (which is good), since they're adjacent and not dependent. Is that correct?

[aristidesstaffieri]

some thoughts on the UX of this -
right now, most wallets do a much worse job of communicating soroban invocations with deep auth trees than they do classic operations. So for the end user in most wallets today, going from singing a change_trust op to signing a soroban invocation is not going to make things more clear.

I think you could still keep the 2 steps of getting the trustline + getting authorized separate and achieve a better UX with a similar flow.

1. Wallet reads the toml, sees the authorizer and policy, calls is_eligible(user) to decide which path to take.
2. User signs a plain classic ChangeTrust. Wallet renders and can choose to sponsor it.
3. The exchange or wallet calls authorize_trustline(user) in a separate Soroban transaction, paying the fee. The user does not sign this.
4. Wallet polls is_authorized, shows done. Wallet can show authorization status in whichever way they choose.So you can keep the easier to digest classic op signature review while getting a lot of the benefits of the proposed solution.

I'm wondering if this is mostly already solve-able through application layer improvements. It seems like the common experience today is something like -

User needs to add trustline, which many wallets and exchanges dont sponsor today, causing reserve related friction(but they can).
Then user needs to wait for authorization, which many wallets and exchanges don't provide visibility into.

don't applications already have what they need to do this better by polling authorized status on the asset? Applications could go much further by providing this state, and providing context on what it is, then notifying users when they are authorized.

[hugo-heer]

Agreed. That flow is already in the SEP (Case B then Case A, and it's what our relayer does), but the selection rule currently sends funded holders to onboard() first. Given how wallets render Soroban auth today, your option sounds better. We'll make the classic path the default and specify the getters it relies on (is_eligible, is_authorized).

We'd keep onboard() as a fallback for self-custody holders with nobody to pay the second transaction, and in case some wallets render Soroban auth well.

On the app-layer question :
Reserve friction and visibility are application problems. What apps can't do today is end the wait. Authorizing an AUTH_REQUIRED trustline needs the issuer, and where an issuer has delegated to a contract the interface is bespoke. The SEP standardizes that delegation and its discovery, so any third party can complete authorization for any asset without an issuer signature.

[leighmcculloch]

Reading sep_trustlineonboarder.md@6833212:

The errors are defined as names without corresponding integer values:

Error	Condition
AccountBanned	denylist policy, account is banned
AccountNotAllowed	allowlist policy, account not allowed
NoTrustline	account has no trustline for the asset
ContractPaused	contract is paused
CannotAuthorizeAdminContract	account == authorizer contract address

Are the errors required for interop? Is the intent for contracts calling the contract to branch and change behaviour based on the error returned? Errors exist as numbers when encoded, so without specifying them implementations or integrations won't know what values to use.

[hugo-heer]

Good catch. The named errors are for wallets and integrators to show the right message, so they do need fixed values. We will assign u32 codes in the next revision !