Lelantos SDK

Appearance

@lelantos-org/sdk / index / Wallet

Class: Wallet ​

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

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);

Implements ​

Properties ​

address ​

ts
readonly address: ShieldedAddress;

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

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

Implementation of ​

WalletApi.address

cfg ​

ts
readonly cfg: ResolvedWalletConfig;

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

Implementation of ​

ts
SpendContext.cfg

J ​

ts
readonly J: WasmJubjub;

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

Implementation of ​

ts
SpendContext.J

keys ​

ts
readonly keys: SpendingKey;

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

Implementation of ​

WalletApi.keys

P ​

ts
readonly P: Poseidon;

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

Implementation of ​

ts
SpendContext.P

Accessors ​

chain ​

Get Signature ​

ts
get chain(): ChainAdapter;

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

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

Returns ​

ChainAdapter

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

Implementation of ​

WalletApi.chain

noteSource ​

Get Signature ​

ts
get noteSource(): NoteSource;

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

Returns ​

NoteSource

Implementation of ​

WalletApi.noteSource

noteStore ​

Get Signature ​

ts
get noteStore(): NoteStore;

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

Returns ​

NoteStore

Implementation of ​

WalletApi.noteStore

nullifierStore ​

Get Signature ​

ts
get nullifierStore(): NullifierStore;

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

Returns ​

NullifierStore

Implementation of ​

ts
SyncContext.nullifierStore

prover ​

Get Signature ​

ts
get prover(): Prover;

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

Returns ​

Prover

Implementation of ​

WalletApi.prover

scanner ​

Get Signature ​

ts
get scanner(): Scanner;

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

Returns ​

Scanner

Implementation of ​

WalletApi.scanner

selector ​

Get Signature ​

ts
get selector(): CoinSelector;

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

Returns ​

CoinSelector

Implementation of ​

WalletApi.selector

submitter ​

Get Signature ​

ts
get submitter(): Submitter;

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

Returns ​

Submitter

Implementation of ​

WalletApi.submitter

treeStore ​

Get Signature ​

ts
get treeStore(): TreeStore;

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

Returns ​

TreeStore

Implementation of ​

ts
SpendContext.treeStore

Methods ​

asset() ​

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

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

Registry entry for id plus ERC-20 symbol/decimals when the adapter exposes them. Cached for the wallet's lifetime — asset entries are immutable apart from the disabled flag; { refresh: true } re-reads it.

Parameters ​

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

Returns ​

Promise<AssetInfo>

Implementation of ​

WalletApi.asset

assets() ​

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

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

Every asset this chain has registered, lowest id first.

Returns ​

Promise<AssetInfo[]>

Implementation of ​

WalletApi.assets

awaitCommitments() ​

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

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

Poll sync() until every commitment in cms is stored locally.

Reports whether they arrived — see AwaitCommitmentsResult. Does not throw on timeout by default: this runs after a successful broadcast, so a lagging indexer is not a failed transaction.

Parameters ​

ParameterType
cmsstring[]
opts?AwaitCommitmentsOpts

Returns ​

Promise<AwaitCommitmentsResult>

Implementation of ​

WalletApi.awaitCommitments

balance() ​

ts
balance(asset): CircuitAmount;

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

Unspent total for one asset, in circuit units.

Parameters ​

ParameterType
assetAssetIdLike

Returns ​

CircuitAmount

Implementation of ​

WalletApi.balance

balances() ​

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

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

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

Returns ​

Map<AssetId, CircuitAmount>

Implementation of ​

WalletApi.balances

cancelDeposit() ​

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

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

Cancel an escrowed deposit. Permissionless after cancelDelay blocks. Caller supplies the DepositEscrowed event payload for the on-chain digest check.

Parameters ​

ParameterType
idbigint
inputsCancelDepositInputs

Returns ​

Promise<{ txHash: Hex32; }>

Implementation of ​

WalletApi.cancelDeposit

compact() ​

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

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

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; }>

Implementation of ​

WalletApi.compact

create() ​

ts
static create(source, cfg): Promise<Wallet>;

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

Build from any key source. Wires defaults for omitted pluggables. Collects every config problem into WalletConfigError.missing.

Parameters ​

ParameterType
sourceKeySource
cfgWalletConfig

Returns ​

Promise<Wallet>

deposit() ​

ts
deposit(args): Promise<DepositResult>;

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

Shield ERC-20 into the MASP via Permit2 escrow. Funds sit in escrow until the relayer flushes a batch (or cancelDeposit after cancelDelay blocks). For native ETH set asEth: true.

Parameters ​

ParameterType
argsDepositOptions

Returns ​

Promise<DepositResult>

Implementation of ​

WalletApi.deposit

dispose() ​

ts
dispose(): Promise<void>;

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

Release everything this wallet holds: scanner workers and, if one was built, the prover's.

WorkerPoolScanner spawns 2–8 workers per wallet, each with its own wasm heap, and Scanner.dispose existed with no caller — so an app that rebuilds its wallet on an account or network switch leaked a whole pool every time.

Idempotent, and safe on a wallet that never synced or proved. The wallet must not be used afterwards.

Returns ​

Promise<void>

Implementation of ​

WalletApi.dispose

feeBps() ​

ts
feeBps(): Promise<bigint>;

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

SpendContext — config override, else the chain's fee.

Returns ​

Promise<bigint>

Implementation of ​

ts
SpendContext.feeBps

markPendingSpend() ​

ts
markPendingSpend(noteIds): Promise<void>;

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

Reserve notes against a spend whose outcome is unknown, so the selector stops offering them until reconciliation or expiry settles it.

Called automatically when a submit fails without an answer; see submitSpend and StoredNote.pendingSpendAt.

Parameters ​

ParameterType
noteIdsstring[]

Returns ​

Promise<void>

Implementation of ​

ts
SpendContext.markPendingSpend

markSpent() ​

ts
markSpent(noteIds): Promise<void>;

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

Called automatically by transfer / withdraw; exposed for alternative spend flows.

Parameters ​

ParameterType
noteIdsstring[]

Returns ​

Promise<void>

Implementation of ​

WalletApi.markSpent

notes() ​

ts
notes(filter?): WalletNote[];

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

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

Parameters ​

ParameterType
filter?NotesFilter

Returns ​

WalletNote[]

Implementation of ​

WalletApi.notes

quoteFee() ​

ts
quoteFee(args): Promise<FeeQuoteResult>;

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

What relaying kind costs and what it may be paid in, before building anything.

options[].affordable is checked against this wallet's own balances, so a UI can offer only the assets the holder can actually pay with.

Parameters ​

ParameterType
argsQuoteFeeArgs

Returns ​

Promise<FeeQuoteResult>

Implementation of ​

WalletApi.quoteFee

refresh() ​

ts
refresh(): Promise<void>;

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

Reload in-memory cache from NoteStore after external mutation.

Returns ​

Promise<void>

Implementation of ​

WalletApi.refresh

resolveAsset() ​

ts
resolveAsset(ref): Promise<AssetInfo>;

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

SpendContext — id, token address or symbol to a registry entry.

Parameters ​

ParameterType
refAssetRef

Returns ​

Promise<AssetInfo>

Implementation of ​

ts
SpendContext.resolveAsset

selectNotes() ​

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

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

Parameters ​

ParameterType
assetAssetId
targetCircuitAmount
opts?SelectOpts

Returns ​

SelectionResult

Implementation of ​

WalletApi.selectNotes

spendableMax() ​

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

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

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>

Implementation of ​

WalletApi.spendableMax

storedNotes() ​

ts
storedNotes(): readonly StoredNote[];

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

SpendContext — the raw stored-note list.

Returns ​

readonly StoredNote[]

Implementation of ​

ts
SpendContext.storedNotes

swap() ​

ts
swap(args): Promise<SwapResult>;

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

Atomic shielded swap. Leg-1 transact_2x2 unshields to SwapWrapper; leg-2 deposit request re-shields the B note. Bundled via submitter.submitSwap. args.amount is gross publicOut in circuit units of assetIn; MASP skims feeBps before transferring.

Parameters ​

ParameterType
argsSwapOptions

Returns ​

Promise<SwapResult>

Implementation of ​

WalletApi.swap

sync() ​

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

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

Pull encrypted notes, the Merkle tree, and the spent set in parallel, then reconcile which local notes are now spent. Convenience wrapper around syncNotes + syncTree + syncNullifiers.

Parameters ​

ParameterType
opts?SyncOpts

Returns ​

Promise<SyncResult>

Implementation of ​

WalletApi.sync

syncNotes() ​

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

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

Pull encrypted notes, trial-decrypt with ivk + dk, persist hits.

Pages the feed to exhaustion, resuming from the cursor on NotesFile.cursor, so a caught-up wallet fetches nothing. Idempotent: re-scanning a note already stored is dropped by cm. Does not sync the tree. limit is the page size, not a ceiling on notes fetched.

Parameters ​

ParameterType
opts?SyncOpts

Returns ​

Promise<SyncResult>

Implementation of ​

WalletApi.syncNotes

syncNullifiers() ​

ts
syncNullifiers(): Promise<void>;

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

Fetch new spent-nullifier chunks into the local set. Idempotent — resumes from its own cursor. reconcileSpentOnChain reads this set, so a stale mirror only ever under-reports spends; it never marks a live note spent.

Returns ​

Promise<void>

syncTree() ​

ts
syncTree(): Promise<void>;

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

Fetch new Merkle commitment chunks and rebuild the local tree. Idempotent — resumes from syncedCount cursor. Does not scan notes.

Returns ​

Promise<void>

Implementation of ​

WalletApi.syncTree

transfer() ​

ts
transfer(args): Promise<TransferResult>;

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

Shielded transfer: 1-2 notes → send-note + change-note → submit → mark spent. Throws InsufficientCoverError on no 1/2-note cover.

Parameters ​

ParameterType
argsTransferOptions

Returns ​

Promise<TransferResult>

Implementation of ​

WalletApi.transfer

withdraw() ​

ts
withdraw(args): Promise<WithdrawResult>;

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

Unshield ERC20 to args.to. Throws InsufficientCoverError on no cover.

Parameters ​

ParameterType
argsWithdrawOptions

Returns ​

Promise<WithdrawResult>

Implementation of ​

WalletApi.withdraw

withdrawEth() ​

ts
withdrawEth(args): Promise<WithdrawResult>;

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

Unshield to raw ETH via NativeAdapter.withdrawNative, which unwraps.

Parameters ​

ParameterType
argsWithdrawEthOptions

Returns ​

Promise<WithdrawResult>

Implementation of ​

WalletApi.withdrawEth