Candide Smart Deposit Addresses API Reference

This reference documents @candidelabs/wdk-protocol-sda-candide@1.0.0-beta.1.

CandideForwardingProtocol is the default export of @candidelabs/wdk-protocol-sda-candide and extends WDK's SdaProtocol. It supports unbound, read-only-account, and full-account construction. API operations do not sign wallet transactions.

For the TypeScript constructor limitation with WDK generic registration, see installation guidance. Direct construction is shown below.

Constructor

You can import the class through the package entrypoint:

import CandideForwardingProtocol from '@candidelabs/wdk-protocol-sda-candide'

The constructor accepts the following account variants:

new CandideForwardingProtocol(account: undefined, config: CandideForwardingProtocolConfig)
new CandideForwardingProtocol(account: IWalletAccountReadOnly, config: CandideForwardingProtocolConfig)
new CandideForwardingProtocol(account: IWalletAccount, config: CandideForwardingProtocolConfig)

config.apiUrl is required. An account's EVM address supplies the default recipient for creation and derivation. Without an account, those methods require destinationAddress. See configuration fields for exact types, defaults, and credential requirements.

Methods

Route and Address Operations

getSupportedRoutes

Lists one route per source and destination chain pair. The declared options are SdaRoutesOptions & { sourceChain: Blockchain }. Although the generated signature makes the options parameter optional, this provider rejects a call without sourceChain.

Blockchain is string or number. Numeric IDs, numeric strings, and recognized chain aliases are accepted. Alias recognition is not evidence of live support; discover routes at runtime.

Each result contains sourceChains, destinationChain, inputTokens, and reusable: true. outputAsset is unset because each input is delivered as its own destination equivalent. Tokens also carry Candide's destinationTokenAddress and feeBps at runtime.

With sourceToken, limits.min is the smallest reported bridge minimum as a bigint in input-token base units. The reported minimum is inclusive. It is omitted if no minimum is reported. limits.max is not supplied by this method. Re-estimate before displaying instructions, since minimums change. Routes use the per-source cache configured by routesCacheTtlMs.

quoteDeposit

Accepts CandideDepositOptions, which extends SdaDepositOptions with optional depositAddress.

The result includes standard quote fields and bridge, outputAssetSymbol, and sponsored. outputAsset identifies the destination token by contract address or native-token sentinel; outputAmount is a bigint in that token's base units.

Candide uses 0x0000000000000000000000000000000000000000 for native ETH when advertised by a route. Use native base units for that token and distinguish the sender's gas costs from forwarding fees. A normal native send and an ERC-20 token transfer have different wallet transaction requirements; this module performs neither send.

The two fee entries are the Candide relayer fee (type: 'protocol') and bridge fee (type: 'network'). Both use input-token base units. included: true means the fee is already reflected in the output estimate; sponsored fees have included: false. Enable sponsorship on the forwarding policy in the Candide dashboard. Sponsored forwards deliver the full deposit and bill forwarding fees to the policy.

The module uses an explicit provider sponsored flag when available. Otherwise it infers sponsorship by comparing full input and output amounts with known decimals; missing decimals are assumed equal. Treat it as estimate metadata, not proof of a policy commitment. The result does not reserve the amount, bridge, fees, or settlement time.

createDepositAddress

Accepts CandideCreateDepositAddressOptions and returns a one-element CandideDepositAddress[] after activating monitoring.

The address's id equals its lowercase address. Its descriptor includes sourceChains, supportedInputTokens, destinationChain, recipient destinationAddress, reusable: true, optional Unix-second expiry, recoveryWithdrawer, and salt. outputAsset and limits are not supplied in the descriptor.

Persist the salt with the user or order and reuse it for the same logical address, including activation retries. Changing the salt derives a different address.

With default verification, local derivation happens before activation and the returned address is compared afterward. ADDRESS_MISMATCH can therefore reject after the API has activated its address. Fetching supported tokens can also fail after activation. Reconcile state before retrying, and do not fund an address whose verification failed.

deriveDepositAddress

Accepts the same options as creation and returns the lowercase CREATE2 address. It does not activate monitoring, deploy a contract, or send a transaction.

Deployment inputs are resolved through the API and cached unless deployParams.allowedRelayer is supplied; with that field, derivation is offline. The source-chain list is validated, but does not create a different address for each source chain. A derived address alone is not ready for monitored deposits.

getDepositAddress

Accepts a valid EVM address as id. Retrieves stored derivation inputs and activation history, then reconstructs the descriptor.

sourceChains includes every recorded chain, active or expired. expiry is the earliest per-chain expiresAt or expiredAt value and can be absent. A past expiry means at least one chain needs renewal. No activation history results in NoSuchElementError.

renewDepositAddress

Accepts the address's id, reloads its stored recipient, recovery withdrawer, destination chain, salt, and source-chain history, and activates those chains again. It requires policySecret and returns the refreshed descriptor.

When verification is enabled and stored data includes the relayer, the module derives and compares the stored address before renewal. It always rejects if activation returns a different address, regardless of verifyAddresses. The method does not migrate a recipient or recovery wallet to a new value from constructor configuration.

getTransfers

Accepts the forwarding address and optional SdaTransfersOptions. Resolves the address's recipient and destination chain, then filters the recipient's paginated forwards by proxyAddress. Returns newest-first forwards. One forward can combine several deposits to the same address. It does not list every raw funding transaction.

Use a finite limit for application history views. Without it, the module walks every provider cursor page until exhausted. Unknown addresses throw NoSuchElementError.

getTransfersByRecipient

Accepts destinationChain: Blockchain, recipient: string, and the same optional history filters. Lists every forward delivered to that recipient on that destination chain, across forwarding addresses. Pagination and status mapping match getTransfers().

The recipient must be a valid EVM address. sourceChain is not applied as a filter.

getTransfer

Accepts the non-empty, opaque CandideTransfer.id returned in history. Fetches a single forward and maps its current state. It is not a transaction-hash lookup. A missing forward throws NoSuchElementError.

recoverDepositAddress

Accepts SdaRecoveryOptions: { id: string } or { address: string }. Both identify the same forwarding address. The shared sourceChain field is not needed by Candide.

Calls renewal and returns { status: 'reindexed', address, id, message }. It requires prior activation history and policySecret. It does not withdraw funds or send an on-chain transaction. reindexed confirms reactivation, rather than completed delivery.

For withdrawal, use the separate recovery frontend and review recipient and recovery rights.

disableDepositAddress

Always rejects with UnsupportedOperationError. Candide provides no explicit disable operation through this module; activations expire on their own.

getDeployParams

Returns CandideDeployParams: factory, singleton, proxyCreationCode, allowedRelayer, and optional version.

By default, the resolver compares the API's factory, beacon, and bytecode with PINNED_DEPLOY_PARAMS, then uses its relayer. Overridden fields are not compared. Supplying allowedRelayer skips the deployment API call. See deployment verification before overriding these values.

Transfer Fields and Status

CandideTransfer extends the minimal WDK { id, status } transfer with provider fields. Fields omitted by the API remain absent at runtime.

The sourceAddresses array contains { address: string, amount: string } entries for contributing senders and their amounts. One forward can aggregate multiple deposits. null means attribution was unavailable. Treat provider extension fields as optional in application rendering even when a declared type expects a value.

These are mappings, rather than a guaranteed sequence of transitions. History's provider unknown is not a successful delivery or a terminal failure.

Exported Types and Helpers

Type-only imports are separate from the JavaScript class and error imports:

import type {
  CandideCreateDepositAddressOptions,
  CandideDepositAddress,
  CandideDepositOptions,
  CandideDepositQuote,
  CandideDeployParams,
  CandideForwardingProtocolConfig,
  CandideSdaToken,
  CandideTransfer,
} from '@candidelabs/wdk-protocol-sda-candide'

The entrypoint also re-exports WDK SDA types and the provider payload types CandideRoute, CandideRouteToken, and CandideForward. They describe provider data, rather than methods on the protocol. Internal RPC clients, resolvers, normalization utilities, and mappers are not exported through the package entrypoint.

computeProxyAddress

Returns a lowercase EVM address synchronously. Required parameters are recipient, recoveryWithdrawer, destinationChainId: number, allowedRelayer, factory, singleton, and proxyCreationCode; salt is optional and defaults to ZERO_SALT. All other fields are strings. Invalid inputs throw ValueError.

This helper performs no API call, deployment, monitoring activation, or contract-code inspection. Prefer the protocol's derivation method when you need its deployment resolution and configuration behavior.

Errors

Shared errors are imported from the WDK protocols entrypoint:

import { InvalidTokenError, NoSuchElementError, ProviderError, SdaError, UnsupportedOperationError, ValueError } from '@tetherto/wdk-wallet/protocols'
import { CandideForwardingError, CandideForwardingErrorReason } from '@candidelabs/wdk-protocol-sda-candide'

Provider JSON-RPC codes and messages are preserved in cause. Do not log raw causes, credentials, or full dashboard URLs. Contact Candide through integration support, report package bugs through GitHub issues, and report security concerns privately as described in SECURITY.md.

Next Steps

Need Help?