feat(protocols): add SDA (Smart Deposit Address) protocol interface

[AlonzoRicardo]

Summary

Adds the generic SdaProtocol interface for Smart Deposit Address (SDA) providers — services that issue a deposit address, accept a stablecoin (or native token) from a supported source chain, convert it, and deliver a chosen asset (e.g. USDT) to a chosen destination chain and address. This is the foundation that providers (Rhino, Orchestra/Flashnet, Relay, Candide, …) implement as wdk-protocol-sda-* modules and that TW consumes for the "Other Assets" receive flow.

Part 1 of 3 (the interface — the bulk of the work), mirroring the earlier swidge work.

What's in it

src/protocols/sda-protocol.js — ISdaProtocol (the interface) + abstract SdaProtocol, re-exported from @tetherto/wdk-wallet/protocols.

• Required core (every provider implements): getSupportedRoutes, createDepositAddress.
• Optional, capability-gated: quoteDeposit, deriveDepositAddress, getDepositAddress, renewDepositAddress, getTransferStatus, getDepositAddressTransfers, getTransfersByRecipient, recoverDepositAddress, disableDepositAddress.
• Introspection: getCapabilities() returns a descriptor (custody model, client-derivability, activation lifecycle, quoting, reusability, route discovery, recovery, history-by-address/recipient, status, disable, refund) so consumers adapt to provider differences without trial-and-error.

Design notes

• New sda category, not swidge. Swidge executes an on-chain swap+bridge from the user's wallet (returns {hash, fee}); SDA issues a deposit address the user funds externally and the provider converts/delivers. Different lifecycle and return shape → its own category (closest sibling is fiat).
• Capability-gating over a fat interface. Optional methods default to throwing NotImplementedError; getCapabilities() advertises what's real.
• Custody + activation as first-class capabilities (from Candide's review). custodyModel distinguishes operator-held addresses from on-chain self-custodial ones; clientDerivableAddress flags deterministically-derivable addresses; activation (none / required / ttl) captures the address lifecycle. recovery is scoped to provider-side missed-deposit reprocessing only — keep-alive of an expired address is activation: 'ttl'.
• Provider-agnostic derivation. Rather than hard-code any provider's tuple, self-custodial derivation inputs are a generic, untyped derivation payload (passed through, echoed back on SdaDepositAddress), with deriveDepositAddress (pure client-side) separated from createDepositAddress (which also activates).

Validation

Pressure-tested against four structurally different providers spanning both custody models (local throwaway modules, not part of this PR). The Candide reference is validated live against Candide's alpha forwarding API (forwarding_getAddress / account_activateForwardingAddress / forwarding_getStatus). Every optional method is implemented by ≥1 provider and skipped by ≥1, and every capability takes multiple values:

	Rhino	Orchestra	Relay	Candide
custodyModel	trusted-operator	trusted-operator	trusted-operator	self-custodial
clientDerivableAddress	✗	✗	✗	✓
activation	ttl	none	none	ttl
createDepositAddress	1 family address	N per-chain	1 quote-bound	derive + activate
deriveDepositAddress	✗	✗	✗	✓
renewDepositAddress	✓	✗	✗	✓
quoteRequired (uses quote)	✗	✗	✓	✗
getTransferStatus	✗	✗	✓	✗
getDepositAddress	✓	✓	✗	✓
getDepositAddressTransfers	✓	✗	✓	✗
getTransfersByRecipient	✗	✗	✗	✓
recovery	none	reindex	reindex	none
disableDepositAddress	✗	✓	✗	✗

Each provider also passes a full registerProtocol → getSdaProtocol → method round-trip via the WDK.

Notes

• Source-only; generated .d.ts are produced by npm run build:types.
• Draft pending the P002 design-spec sign-off. Non-blocking refinements still open for the spec: limits denomination (USD vs token base-unit), history time-range filter, metadata/webhook fields.

Related PRs

This is one of a 3-PR set:

• wdk-wallet — SdaProtocol interface (this PR)
• wdk — getSdaProtocol support: feat: add SDA protocol support (getSdaProtocol) wdk#73
• create-wdk-module — sda module type + template: feat: add sda module type and template create-wdk-module#14

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1215952542364295

[Sednaoui]

great addition @AlonzoRicardo

I'm commenting from the angle of Candide's Forwarding Address. I think this is solid and overall very well written from a capabilities standpoint. A few things I think are missing or worth a fit.

Currently, capabilities don't say who holds the funds. Relay, Rhino, and Orchestra are all operator controlled. This means the deposit address is the provider's, and recovery means "ask their backend to reindex/reactivate." A self-custodial version is a different architecture: the address is an onchain smart contract with withdrawal rights fixed in code. In our case the recipient can withdraw immediately, and a custodial withdrawer (an optional recovery wallet) can do so only after a timelock. So funds are recoverable onchain without the provider, and no single operator can unilaterally move them. Since all three reference providers (Relay, Rhino, and Orchestra) sit on the operator side, nothing in the interface currently forces the distinction. I can propose to add something along these lines to cover the self-custodial, trust minimized design:

/** @typedef {'self-custodial' | 'trusted-operator'} SdaCustodyModel */

// SdaCapabilities:

* @property {SdaCustodyModel} custodyModel - Who controls deposited funds in flight.
* @property {boolean} clientDerivableAddress - Whether the address is deterministically derivable/verifiable client-side, before any provider call.

• On the word "recovery.": Here it means the provider re-processing a missed deposit (reindex/reactivate). For us those are two separate things: reactivating an expired TTL is just keep alive (what we call "reactivate"), whereas "recovery" specifically means the onchain withdrawal of stuck funds described above: recipient first, custodial withdrawer after the timelock. This recovery isn't a recoverDepositAddress call at all, it's the custody guarantee, which is the other reason the custodyModel flag is important. Keeping the two vocabularies distinct would avoid a consumer assuming recovery: 'none' means "funds can't be recovered."

• History is keyed by deposit address, not recipient: getDepositAddressTransfers keys on the deposit address, so a consumer with several addresses per user (multichain, or multiple salts) has to track each one and fan out a call per address. We expose status by recipient + destination chain instead: it aggregates every deposit, across all deposit addresses and source chains, routing to that user. A historyByRecipient capability + an optional getTransfersByRecipient(recipient, destinationChain, options) (or letting the history query accept a destination address) would cover it.

Two gaps in SdaCreateOptions for a deterministic provider like ours:

• The custodial withdrawer is an input to the CREATE2 address, so it can't live in static config, it changes the address. refundAddress is different (push-refund style). A generic optional withdrawer/recoveryParty that derivation can consume would cover it.
• No caller salt key: we need it to rederive a specific address (one-per-user vs one-per-tx)

Happy to send the custodyModel interface as a proposal if it's useful

If I missed any other tought or feedback @sherifahmed990 please feel free to further add it

[AlonzoRicardo]

Thanks @Sednaoui — I've pushed an update to this PR that folds in your feedback:

Added SdaCustodyModel = 'self-custodial' | 'trusted-operator', plus custodyModel and clientDerivableAddress on SdaCapabilities — essentially your proposal.

recovery is now documented strictly as provider-side reprocessing of a missed deposit (reindex/reactivate), explicitly not a statement about fund recoverability — that's custodyModel. So recovery: 'none' + custodyModel: 'self-custodial' reads correctly: "no provider reprocess call, funds recoverable on-chain." Your TTL keep-alive maps to reactivate; the on-chain stuck-fund withdrawal is the custody guarantee, not a recoverDepositAddress call.

History by recipient. Added optional getTransfersByRecipient(recipient, destinationChain, options) + a historyByRecipient capability, alongside the existing address-keyed one.

Create options. Added optional withdrawer and salt to SdaCreateOptions, documented as inputs to the (CREATE2) derivation — distinct from refundAddress, and salt for one-per-user vs one-per-tx.

Yes please, I'd love the custodyModel proposal. We're writing a short design spec for the interface before it merges, and the custody axis belongs in it as a first-class dimension. Two things that'd help:

• The exact derivation inputs you'd want the interface to carry — is recipient + withdrawer + salt enough, or is there a factory / init-code / timelock parameter a consumer should pass or read back?
• Whether you'd want getDepositAddress to support re-deriving/verifying an address client-side (vs a backend lookup) — a nice property unique to the derivable model.

cc @sherifahmed990

[sherifahmed990]

• the derivation inputs are recipient, custodialWithdrawer, destinationChainId and salt.
• other params like the factory, singelton address and initcode abi can be included as constants in the address calculation implementation.
• getDepositAddress verifying the result returned from the api is a good idea.

[Sednaoui]

To build on Sherif’s comment, I propose WDK interface to not hardcode Candide’s derivation tuple as the universal model. Other self-custodial, destination specific providers may encode different parameters in their deposit address, depending on their recovery model, execution model, supported inputs, or routing design.

To keep this generic, I can suggest writing the common capabilities, while leaving derivation inputs provider specific, like the following:

Capabilities

• custodyModel: 'self-custodial' | 'trusted-operator'
• clientDerivableAddress: boolean
• activation: 'none' | 'required' | 'ttl'

Methods

• createDepositAddress: returns an address that is ready to receive deposits according to the provider’s activation model. For activation: 'ttl', this may include activation/registration as part of the call.
• getDepositAddress: existing lookup
• optional pure deriveDepositAddress(inputs) -> address for clientDerivableAddress providers. This does not activate/register/monitor the address. Verification is derive + compare.
• optional renewDepositAddress: refreshes activation for providers where activation: 'ttl'.

Data

• derivation inputs should be a provider-specific payload that the generic layer passes through without typing.
• the created SdaDepositAddress should echo that payload back, so the address can be rederived, verified, or recovered later.

For Candide, the derivation payload is:

{
  recipient,
  custodialWithdrawer,
  destinationChainId,
  salt?
}

One nuance: for Candide, client derivation is mainly used as a verification, fallback, and recovery property. The normal flow is still to call forwarding_getAddress, optionally verify the returned address, then call account_activateforwardingaddress so the relayer monitors it. Deriving the address alone does not activate forwarding.

[AlonzoRicardo]

Thanks @Sednaoui — I've pushed an update to this PR that folds in your feedback:

Added SdaCustodyModel = 'self-custodial' | 'trusted-operator', plus custodyModel and clientDerivableAddress on SdaCapabilities — essentially your proposal.

recovery is now documented strictly as provider-side reprocessing of a missed deposit (reindex/reactivate), explicitly not a statement about fund recoverability — that's custodyModel. So recovery: 'none' + custodyModel: 'self-custodial' reads correctly: "no provider reprocess call, funds recoverable on-chain." Your TTL keep-alive maps to reactivate; the on-chain stuck-fund withdrawal is the custody guarantee, not a recoverDepositAddress call.

History by recipient. Added optional getTransfersByRecipient(recipient, destinationChain, options) + a historyByRecipient capability, alongside the existing address-keyed one.

Create options. Added optional withdrawer and salt to SdaCreateOptions, documented as inputs to the (CREATE2) derivation — distinct from refundAddress, and salt for one-per-user vs one-per-tx.

Yes please, I'd love the custodyModel proposal. We're writing a short design spec for the interface before it merges, and the custody axis belongs in it as a first-class dimension. Two things that'd help:

• The exact derivation inputs you'd want the interface to carry — is recipient + withdrawer + salt enough, or is there a factory / init-code / timelock parameter a consumer should pass or read back?
• Whether you'd want getDepositAddress to support re-deriving/verifying an address client-side (vs a backend lookup) — a nice property unique to the derivable model.

cc @sherifahmed990

[Davi0kProgramsThings]

LGTM.