Candide Smart Deposit Addresses Overview

Candide's Forwarding Address module implements WDK's ISdaProtocol. It creates one deterministic EVM address for deposits from the configured source chains, including the destination chain, and forwards supported tokens to a recipient on that destination chain.

Use this module for an app deposit screen that discovers accepted tokens, displays an address and activation expiry, estimates delivery, and tracks forwards. The depositor sends an ordinary token transfer from their wallet or exchange. The module does not sign that deposit or require the depositor's private key.

Address and Activation Model

A forwarding address depends on the recipient, recovery withdrawer, destination chain, salt, and deployment inputs. The same inputs derive the same address; changing the recipient, recovery withdrawer, destination chain, or salt produces a different address. Requested source chains determine monitoring coverage, rather than a separate address per chain. Use different salts to give one recipient several addresses, such as one per user or order for attribution into a shared treasury.

Derivation and activation are separate operations:

• deriveDepositAddress() computes an address without enabling monitoring. It fetches deployment information unless the relayer is pinned in configuration.
• createDepositAddress() activates monitoring and returns a one-element array. The address descriptor includes its accepted source chains, tokens, and expiry in Unix seconds.
• renewDepositAddress() refreshes monitoring on every chain in the address's activation history, including expired chains.

Show expiry beside the address and renew it when opening the deposit screen. A derived address alone does not establish that deposits are monitored. The contract address remains reusable after monitoring expires, but forwarding waits for monitoring to resume.

Routes and Estimates

Discover routes per source chain using getSupportedRoutes({ sourceChain }). Candide controls the current EVM chain and token set. A route delivers each accepted input token as its corresponding destination token; outputAsset is not a token-selection filter in this implementation.

Only tokens returned for the route are forwarded. If a route advertises native ETH, Candide identifies it with the zero-address sentinel; other tokens use their ERC-20 contract address. The sender pays the source wallet's applicable gas fee separately from forwarding fees. Unsupported tokens and supported-token balances below the current minimum stay in the forwarding contract. Later deposits of the same token to the same address on the same source chain can bring a supported balance to the minimum and allow forwarding, subject to active monitoring and current route support. The recipient can withdraw any token immediately; the recovery withdrawer can do so after the recovery timelock.

When a source token is specified, a route may include limits.min in that token's base units. This is the smallest minimum reported by a bridge, and it changes with market conditions. Leave a margin and request a fresh, non-binding quoteDeposit() estimate before displaying deposit instructions. An earlier estimate does not reserve a bridge, fee, or output amount.

The quote's outputAsset identifies the destination token by contract address or native-token sentinel. The deposit descriptor's destinationAddress is the recipient. Keep these distinct in application state and confirmation screens.

Recovery and Provider Trust

The recipient can withdraw any token immediately by sending a transaction on the source chain. An optional recovery withdrawer can withdraw after a 48-hour timelock that the recipient can cancel. If the recipient cannot transact on the source chain, such as an exchange-controlled address or a smart account not deployed there, pair it with a recovery withdrawer that can. Decide who can recover stuck funds before creating the address; the recovery withdrawer is a derivation input.

The module's recoverDepositAddress() reactivates monitoring. It does not sign a transaction, withdraw funds, or confirm that a deposit has arrived. On-chain withdrawal is a separate operation through Candide's recovery frontend.

Requirements and Limits

• Node.js 20 or later and a shared @tetherto/wdk-wallet peer matching the declared ^1.0.0-beta.19 range. The package also exports a Bare entrypoint.
• A Forwarding Address API URL from the Candide dashboard. The URL carries a team API key for usage and billing and can be used client-side. It cannot activate addresses or move funds. Avoid exposing it in logs or public examples, and rotate it in the dashboard if it leaks.
• A server-held forwarding policy secret for creation, renewal, and reactivation. Route discovery, quotes, derivation, lookups, and history do not require that policy secret.
• An EVM recipient address. Binding a WDK account supplies its address as the default recipient; an unbound instance requires an explicit recipient.
• Explicit disabling is unsupported. Activations expire according to the provider's lifecycle.

Transfer history tracks forwards, rather than every raw deposit transaction. One forward can combine several deposits to the same address; sourceAddresses lists contributing senders and amounts when attribution is available. Candide's pending and unknown provider statuses map to WDK processing; an unrecognized status maps to WDK pending. See transfer fields and status mapping before using them for UI decisions.

Next Steps

---

Need Help?