Lelantos SDK

Appearance

@lelantos-org/sdk / index / WalletApi

Interface: WalletApi ​

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:37

The high-level wallet surface. Wallet in ./wallet.ts is the shipped implementation; depend on this interface to keep tests mockable.

Amounts are always in circuit units — tokenBaseUnits = amount * asset.scale. Use wallet.asset(id) plus parseAmount / formatAmount from ./assets.js to move between circuit units and what a user types.

Typical lifecycle:

ts
const wallet = await connect({ network: "anvil", privateKey, rpcUrl });
await wallet.sync();                              // notes + Merkle tree
const weth = requireTokenMeta(await wallet.asset(assetId(1n)));
await wallet.deposit({ asset: weth.id, amount: parseAmount("0.25", weth) });
await wallet.sync();
wallet.balance(weth.id);

Properties ​

address ​

ts
readonly address: ShieldedAddress;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:39

This wallet's shielded lelantos1… address (bech32m).

chain ​

ts
readonly chain: ChainAdapter;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:43

Cast to a concrete adapter type for adapter-specific accessors.

keys ​

ts
readonly keys: SpendingKey;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:40

noteSource ​

ts
readonly noteSource: NoteSource;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:44

noteStore ​

ts
readonly noteStore: NoteStore;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:41

prover ​

ts
readonly prover: Prover;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:46

scanner ​

ts
readonly scanner: Scanner;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:47

selector ​

ts
readonly selector: CoinSelector;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:48

submitter ​

ts
readonly submitter: Submitter;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:45

Methods ​

asset() ​

ts
asset(ref, opts?): Promise<AssetInfo>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:75

Registry entry for id plus ERC-20 symbol/decimals when the adapter exposes them. Cached per wallet; pass { refresh: true } to re-read.

Parameters ​

ParameterType
refAssetRef
opts?{ refresh?: boolean; }
opts.refresh?boolean

Returns ​

Promise<AssetInfo>

assets() ​

ts
assets(): Promise<AssetInfo[]>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:79

Every asset registered on this chain, lowest id first.

Returns ​

Promise<AssetInfo[]>

awaitCommitments() ​

ts
awaitCommitments(cms, opts?): Promise<AwaitCommitmentsResult>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:64

Poll until every commitment in cms is in the local store.

Resolves with a status rather than void, so "the indexer is behind" is distinguishable from "all present".

Parameters ​

ParameterType
cmsHex32[]
opts?AwaitCommitmentsOpts

Returns ​

Promise<AwaitCommitmentsResult>

balance() ​

ts
balance(asset): CircuitAmount;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:68

Unspent total for one asset, in circuit units.

Parameters ​

ParameterType
assetAssetIdLike

Returns ​

CircuitAmount

balances() ​

ts
balances(): Map<AssetId, CircuitAmount>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:70

Unspent totals keyed by asset id — one pass for a multi-asset view.

Returns ​

Map<AssetId, CircuitAmount>

cancelDeposit() ​

ts
cancelDeposit(id, inputs): Promise<{
  txHash: Hex32;
}>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:119

Reclaim an escrowed deposit that the relayer never flushed. Permissionless once chain.cancelDelay() blocks have passed. Supply the DepositEscrowed event payload — the contract re-derives the digest from it.

Parameters ​

ParameterType
idbigint
inputsCancelDepositInputs

Returns ​

Promise<{ txHash: Hex32; }>

compact() ​

ts
compact(): Promise<{
  removed: number;
}>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:128

Drop notes flagged spent: true from the underlying store. Returns the number of notes pruned. Balance is unaffected; this only shrinks the on-disk file. Live notes and reconcile state are preserved.

Returns ​

Promise<{ removed: number; }>

deposit() ​

ts
deposit(args): Promise<DepositResult>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:104

Shield ERC-20 (or native ETH via asEth) into the MASP.

Parameters ​

ParameterType
argsDepositOptions

Returns ​

Promise<DepositResult>

dispose() ​

ts
dispose(): Promise<void>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:139

Release scanner workers and any prover worker this wallet built.

A WorkerPoolScanner holds 2–8 workers, each with its own wasm heap, so an app that rebuilds its wallet on an account or network switch must call this or leak a pool per switch. Idempotent; the wallet must not be used afterwards.

Returns ​

Promise<void>

markSpent() ​

ts
markSpent(noteIds): Promise<void>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:122

Parameters ​

ParameterType
noteIdsstring[]

Returns ​

Promise<void>

notes() ​

ts
notes(filter?): WalletNote[];

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:66

Omit a field to stop filtering on it; notes() returns everything.

Parameters ​

ParameterType
filter?NotesFilter

Returns ​

WalletNote[]

quoteFee() ​

ts
quoteFee(args): Promise<FeeQuoteResult>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:84

What relaying kind costs and which assets can pay for it, checked against this wallet's balances. Empty when the relayer charges nothing.

Parameters ​

ParameterType
argsQuoteFeeArgs

Returns ​

Promise<FeeQuoteResult>

refresh() ​

ts
refresh(): Promise<void>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:57

Returns ​

Promise<void>

selectNotes() ​

ts
selectNotes(
   asset, 
   target, 
   opts?
): SelectionResult;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:102

Parameters ​

ParameterType
assetAssetId
targetCircuitAmount
opts?SelectOpts

Returns ​

SelectionResult

spendableMax() ​

ts
spendableMax(asset, opts?): Promise<SpendableMax>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:101

The largest amount of asset a single spend can cover, and what is holding the rest back.

Not the balance. The selector withholds notes that are reserved by an unconfirmed spend, still in their spend cooldown, or below the dust threshold, and a spend can consume only maxInputs of what remains — so a "max" built on the balance produces InsufficientCoverError against a figure the caller itself supplied. withheld breaks the difference down by cause so a UI can say which it is.

Takes the same SelectOpts a spend does, so the prediction and the spend cannot be computed under different rules. maxInputs defaults to the circuit's nIn; pass nIn - 1 when a cross-asset fee will need an input slot of its own, and fee for one paid in this same asset.

Parameters ​

ParameterType
assetAssetId
opts?SelectOpts

Returns ​

Promise<SpendableMax>

swap() ​

ts
swap(args): Promise<SwapResult>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:112

Atomic shielded swap; legs bundled via submitter.submitSwap.

Parameters ​

ParameterType
argsSwapOptions

Returns ​

Promise<SwapResult>

sync() ​

ts
sync(opts?): Promise<SyncResult>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:56

Pull notes and sync the tree in parallel. Convenience wrapper around syncNotes + syncTree.

Parameters ​

ParameterType
opts?SyncOpts

Returns ​

Promise<SyncResult>

syncNotes() ​

ts
syncNotes(opts?): Promise<SyncResult>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:50

Pull encrypted notes only. Sufficient for balance display; does not sync the Merkle tree.

Parameters ​

ParameterType
opts?SyncOpts

Returns ​

Promise<SyncResult>

syncTree() ​

ts
syncTree(): Promise<void>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:52

Fetch new Merkle commitment chunks and rebuild the local tree. Required before spending.

Returns ​

Promise<void>

transfer() ​

ts
transfer(args): Promise<TransferResult>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:106

Shielded transfer to another lelantos1… address.

Parameters ​

ParameterType
argsTransferOptions

Returns ​

Promise<TransferResult>

withdraw() ​

ts
withdraw(args): Promise<WithdrawResult>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:108

Unshield to an ERC-20 recipient.

Parameters ​

ParameterType
argsWithdrawOptions

Returns ​

Promise<WithdrawResult>

withdrawEth() ​

ts
withdrawEth(args): Promise<WithdrawResult>;

Defined in: @lelantos-org/sdk/dist/wallet/api.d.ts:110

Unshield to raw ETH via the WETH bridge.

Parameters ​

ParameterType
argsWithdrawEthOptions

Returns ​

Promise<WithdrawResult>