@zerc20/wallet-sdk 0.4.0 → 0.6.0

package/dist/wallet.d.ts

@@ -28,6 +28,9 @@ export interface OpenOptions {
     birthday?: bigint | Date;
     /** The app opening the wallet, when it takes a share of what reaches the deposit addresses it hands out. */
     referrer?: Referrer;
+    /** Takes the wallet from another tab or window that holds it open, whose `taken` aborts, rather than failing with
+     * `wallet-in-use`: for a user who opens it here, where the other may be a tab the browser keeps in the background. */
+    take?: boolean;
 }
 export interface WatchOptions extends Pick<OpenOptions, 'network' | 'persist' | 'birthday'> {
     /** The account's view key, from its wallet's `viewKey()`. */
@@ -78,7 +81,8 @@ export interface Activity {
      * paid none. */
     fee: bigint | null;
     /** The other side, where known: a payer's claimed address (unverified), where a payment or withdrawal went, or whom a
-     * returned deposit went back to. */
+     * returned deposit went back to. A payment's other side, `sent`'s or that of a `received` with no `burnAddress`, is a
+     * zERC20 account, which an app shows by its zERC20 ID (`accountId`); any other is a public address. */
     counterparty: Address | null;
     /** What the counterparty alone does not say: the receive code a payment went to (it has no counterparty), or the
      * deposit address a deposit came through (its counterparty, which forwarded what was sent to it). */
@@ -115,9 +119,21 @@ export interface CoinInfo {
     state: 'spendable' | Exclude<PendingReason, 'incoming'> | 'spending' | 'blocked';
     /** A note's payer (as claimed, unverified) or a deposit's sender, where known. */
     from: Address | null;
-    /** For a deposit in `screening`, when the ASP should decide it: an estimate, null until there is one. */
-    screenedBy: Date | null;
+    /** The deposit address of this wallet's that a deposit came through (its `from`), as `Activity.via` names it: its
+     * `rageExit` goes where `to` says. */
+    via: {
+        depositAddress: Address;
+    } | null;
+    /** While `screening` or `awaiting-root`, when it should be spendable: the later of its AML check's deadline and when a
+     * root should cover it, by how long commitments on its chain usually wait for one. An estimate: null until there is
+     * one, and in other states. */
+    readyBy: Date | null;
+    /** When it landed: its block's time, null until read. */
+    at: Date | null;
 }
+/** Of `coins`, the one whose turning spendable makes them `need`, the soonest first; null where they never do, or the
+ * one it takes has no estimate. */
+export declare function waitsOn(coins: CoinInfo[], need: bigint): CoinInfo | null;
 export interface DepositInfo {
     id: string;
     /** The burn address it was sent to. */
@@ -130,18 +146,39 @@ export interface DepositInfo {
     sender: Address | null;
     state: 'screening' | 'approved' | 'rejected' | 'spent';
 }
+export interface DepositAddressInfo {
+    address: Address;
+    token: Token;
+    /** What the relayer takes out of each payment through it. Null where its receipt in storage does not say what it was
+     * registered with: `flushDepositAddress` needs that, so only the relayer flushes such an address. */
+    fee: bigint | null;
+    /** When it was handed out, or watched again (`rewatchDepositAddress`), from which the deposit relayer watches it for
+     * 7 days: when storage took its receipt. */
+    at: Date;
+}
 /** A send's or withdrawal's recipient gets all of its amount, and the private balance pays `fee` on top. */
 export interface FeeQuote {
     /** To the relayer. */
     relayer: bigint;
     /** The protocol's cut of the public withdrawal: a withdrawal's, or the one that pays the relayer. */
     protocol: bigint;
+    /** `protocol` as a rate of that withdrawal, in basis points (35 is 0.35%): lower in tiers as the withdrawal grows. */
+    protocolBps: number;
     /** `relayer + protocol`: the `maxFee` this quote passes. */
     fee: bigint;
     /** Transactions needed: one JoinSplit for a send or a withdrawal, a consolidation's merges (each pays the relayer's
      * fee again). */
     steps: number;
 }
+/** The most a send or withdrawal can pay now, and what its fees keep back of what is spendable. */
+export interface MaxAmount {
+    /** What the recipient would get: 0 where the fees take everything. */
+    amount: bigint;
+    /** The fees: the payment's, and those of the merges it needs first. Where they take everything, what they would be. */
+    fee: bigint;
+    /** Merges first, when one JoinSplit cannot spend all of it: each pays the relayer again. */
+    merges: number;
+}
 export type OperationKind = OperationRecord['kind'];
 export type OperationStatus = OperationRecord['status'];
 export type CoinState = CoinInfo['state'];
@@ -167,18 +204,31 @@ export interface Operation {
     /** How far a send, withdrawal or consolidation round has come, for an app to show; null for a deposit, or between
      * rounds. It moves during a sync: read it while one runs. */
     readonly stage: Step['stage'] | MergeStep['stage'] | null;
-    /** Whom a deposit pays, when it goes into their burn address (`deposit({ to })`); null otherwise. */
+    /** Whom a deposit pays, when `deposit({ to })` named an address; null otherwise. One to a receive code shows its code
+     * as `via` in `activity()`. */
     readonly to: Address | null;
+    /** Whether `cancel()` can still end it: a send, withdrawal or consolidation that has paid nothing and has no request
+     * out to the relayer. It moves during a sync: read it while one runs. */
+    readonly cancellable: boolean;
     /** Syncs until the operation is done; throws if it fails. */
     wait(): Promise<void>;
+    /** Ends it while `cancellable`, and does nothing once it is cancelled: it paid nothing, its notes and deposits are free
+     * again, it leaves `operations()` and `activity()`, and `wait()` throws `cancelled`. Throws otherwise, and when the
+     * wallet cannot save it, which leaves it under way. */
+    cancel(): Promise<void>;
 }
 export declare class Wallet {
     #private;
+    /** A wallet over `ctx`, held by `lock`: by default held nowhere, as where there are no Web Locks. */
     private constructor();
-    /** Lets this wallet open again: in another tab, or here for another account. This object is done with: what is
+    /** Lets this wallet go, for another tab or another account here. This object is done with: what is
      * queued fails with `wallet-closed`, a burn address search stops, and the wallet is let go once the task under way
      * ends, so that two never write its state at once. */
     close(): Promise<void>;
+    /** Aborts once another tab or window takes this wallet (`take`), which closes it here: what is queued fails with
+     * `wallet-taken`, a burn address search stops, and the task under way saves nothing more, as the other tab reads the
+     * state and writes it now. */
+    get taken(): AbortSignal;
     get address(): Address;
     /** The account's view key, for `watch` to follow it with on another device: whoever holds it sees what this wallet
      * shows, except the private payments to receive codes, and can spend none of it. Checksummed text (bech32m,
@@ -216,6 +266,20 @@ export declare class Wallet {
     } | null>;
     /** Every deposit found, with the id `rageExit` takes. */
     deposits(): DepositInfo[];
+    /** The deposit addresses this wallet handed out (`depositAddress`), on any of its devices, newest first: for an app to
+     * show each while what is sent to it is on its way, which `activity()` shows once deposited. Each is dated, and its
+     * fee told, by its receipt in storage, alike on every device. */
+    depositAddresses(): DepositAddressInfo[];
+    /** What `address` is to this wallet on `chainId`: one of its own burn addresses (`deposit`), one it paid someone
+     * into (`payment`, `deposit({ to })` to an address), or neither (null), as is a receive code's that it paid. On chain
+     * either is a plain transfer to an address that names no one: this tells an app listing the account's public
+     * transfers which they were. Both are recorded before the transfer is sent. */
+    burnAddressOf(chainId: bigint, address: Address): {
+        kind: 'deposit';
+    } | {
+        kind: 'payment';
+        to: Address;
+    } | null;
     /** The payments to the burn addresses this wallet's points of sale handed out. Spent ones are, normally, in a
      * merged note. */
     payments(): DepositInfo[];
@@ -225,17 +289,32 @@ export declare class Wallet {
      * addresses. */
     posKey(): Promise<Hex>;
     /** Refunds deposit `id` to its sender without the ASP, the attester or a proved root: for a deposit the ASP
-     * rejected, or when those services stop. The account's wallet sends the transactions and pays their gas. */
-    rageExit(id: string): Promise<Hex[]>;
+     * rejected, or when those services stop. The account's wallet sends the transactions and pays their gas, or with
+     * `from` another wallet of the user's does, as `deposit({ from })` pays. One through a deposit address of this
+     * wallet's (`CoinInfo.via`) goes to `to`, by default `from`'s account, else this account; any other goes back to its
+     * sender, and one through a point of sale's deposit address to the refund address its payer named. */
+    rageExit(id: string, opts?: {
+        from?: WalletClient;
+        to?: Address;
+    }): Promise<Hex[]>;
+    /** Sends what deposit address `address` of this wallet's holds of `asset` (NATIVE for the chain's own currency) to
+     * `to`: another token sent to it, which it cannot wrap. What it can wrap is wrapped instead, as a payment to it is.
+     * It deploys on its first flush, and refunds nothing before. `from` and `to` as for `rageExit`. */
+    refundDepositAddress(address: Address, asset: Address, opts?: {
+        from?: WalletClient;
+        to?: Address;
+    }): Promise<Hex>;
     operations(): Operation[];
     /** Moves `amount` of the account's public tokens into the private balance: wraps the underlying asset into a fresh
      * burn address (approving it first if needed). The deposit is spendable once the ASP has screened it. More than the
      * account holds fails at once (`insufficient-funds`), before anything is asked of the wallet.
      *
-     * With `to`, an address that registered, it pays them instead, privately: into a fresh burn address of theirs,
-     * under the public key they registered, told to them in storage first as a note is (`planDeposit`). They
-     * receive it as a deposit of their own, screened like any; the burn address names no one. It shows in `activity()`
-     * as sent. Finding the address takes about 2^16 hashes (`burn-address`).
+     * With `to`, an account that registered, by its address or its zERC20 ID, it pays them instead, privately: into a
+     * fresh burn address of theirs, under the public key they registered, told to them in storage first as a note is
+     * (`planDeposit`). They receive it as a deposit of their own, screened like any; the burn address names no one. It
+     * shows in `activity()` as sent. Finding the address takes about 2^16 hashes (`burn-address`). Or `to` is a receive
+     * code (`receiveCode`), paid into its burn address, which its owner already watches: storage is told nothing, so
+     * only this device's `activity()` shows it as sent.
      *
      * With `wrapped`, it pays from the account's zERC20 itself, as a withdrawal pays out, rather than its underlying
      * asset: a plain transfer into the burn address, with no wrap and no approval.
@@ -248,7 +327,7 @@ export declare class Wallet {
     deposit(opts: {
         token: Token;
         amount: bigint;
-        to?: Address;
+        to?: string;
         wrapped?: boolean;
         from?: WalletClient;
         onStep?: (step: DepositStep) => void;
@@ -256,13 +335,31 @@ export declare class Wallet {
     /** An address that takes `token`'s underlying asset from anywhere (an exchange withdrawal, another wallet) and
      * deposits it privately, less `fee` (in the underlying's base units) to the deposit relayer each time: what arrives
      * must exceed it. A wallet opened with a `referrer` also pays it its `bps` of the rest. Watched for 7 days by the
-     * deposit relayer; refunds go back to this account. `onStep` hears what it waits on (`queued`, `burn-address`). */
+     * deposit relayer. It names no account: its refunds go where a key of its own signs for (`rageExit`'s `to`,
+     * `refundDepositAddress`). `depositAddresses()` lists it. `onStep` hears what it waits on (`queued`,
+     * `burn-address`). */
     depositAddress(token: Token, opts?: {
         onStep?: (step: DepositStep) => void;
     }): Promise<{
         address: Address;
         fee: bigint;
     }>;
+    /** Has the deposit relayer watch deposit address `address` of this wallet's for another 7 days, at the fee it was
+     * handed out with: what reached it after its 7 days is deposited then, and so is what reaches it within the next.
+     * `depositAddresses()` dates it from now, on every device. */
+    rewatchDepositAddress(address: Address): Promise<{
+        address: Address;
+        fee: bigint;
+    }>;
+    /** Deposits what deposit address `address` of this wallet's holds, as the deposit relayer would, for when it does
+     * not: down, or no longer watching the address. Its receipt says all the address was registered with, wherever its
+     * `fee` is known (`depositAddresses()`), so no relayer is asked. `from`, another wallet of the user's, sends the
+     * flush and pays its gas, and shows on chain as the depositor: never the account's own, which the address does not
+     * name. What it holds must exceed the fee (`insufficient-funds`). It shows in `activity()` as any deposit through
+     * the address. */
+    flushDepositAddress(address: Address, opts: {
+        from: WalletClient;
+    }): Promise<Hex>;
     /** A receive code for `token`, to hand to one payer: it pays any amount, as often as it likes, publicly by a transfer
      * of the token to the code's burn address (a deposit, like a point of sale's payment addresses), or privately by
      * `send`. It is one of this wallet's burn addresses, recorded in storage ahead of need, so handing it out writes
@@ -283,13 +380,17 @@ export declare class Wallet {
     maxAmount(opts: {
         kind: 'send' | 'withdraw';
         token: Token;
-    }): Promise<bigint>;
+    }): Promise<MaxAmount>;
     /** What the next merge of a consolidation of everything would spend, as `coins()` ids: up to 100, the largest first,
      * for `consolidate({ coins })`. Null when nothing spendable is worth merging. */
     nextMerge(token: Token): Promise<string[] | null>;
-    /** Pays `amount` privately: to an address that has registered (any wallet that ever opened), or to a receive code
-     * (`receiveCode`). An address that never registered fails with `recipient-not-registered`. One JoinSplit from
-     * what is spendable now, or it fails here: `needs-consolidation`, `funds-settling` or `insufficient-funds`.
+    /** Fetches what a send or withdrawal proves with, some 25 MB, once a page: an app calls it as a payment form opens,
+     * so that the payment's proof does not wait for the download. Outside the queue of calls: a sync goes on meanwhile. */
+    preloadProver(): Promise<void>;
+    /** Pays `amount` privately: to an account that has registered (any wallet that ever opened), by its address or its
+     * zERC20 ID (`accountId`), or to a receive code (`receiveCode`). An account that never registered fails with
+     * `recipient-not-registered`. One JoinSplit from what is spendable now, or it fails here: `needs-consolidation`,
+     * `funds-settling` or `insufficient-funds`.
      * `amount` is what the recipient gets, and `maxFee` caps what it pays on top, `fees({ kind: 'send' }).fee`: the
      * relayer names its fee, so a quote the user saw is the cap. */
     send(opts: {
@@ -324,7 +425,17 @@ export declare class Wallet {
         unwrap?: boolean;
     }): Promise<Operation>;
 }
-/** Holds `address`'s wallet until the returned function is called: two tabs on one wallet would each overwrite the
- * other's state and spend the same notes. A wallet that watches it (`view`) is held apart, as its state is its own.
- * Nothing where there are no Web Locks. */
-export declare function lockWallet(address: Address, kind?: 'wallet' | 'view'): Promise<() => void>;
+/** A wallet held open here (`lockWallet`): until `release`, or until another tab or window takes it, which aborts
+ * `taken`. */
+export interface Hold {
+    release: () => void;
+    taken: AbortSignal;
+    /** Runs `f`, a read or a write of the wallet's saved state, with no other tab in one, and only while this one holds the
+     * wallet: asked of the browser's lock manager, which knows of a take before this tab is told, so that a write lands
+     * either before the tab that took the wallet reads the state, or not at all. */
+    guard: <T>(f: () => Promise<T>) => Promise<T>;
+}
+/** Holds `address`'s wallet: two tabs on one wallet would each overwrite the other's state and spend the same notes. It
+ * fails with `wallet-in-use` while another tab or window holds it, unless it `take`s it from that one. A wallet that
+ * watches it (`view`) is held apart, as its state is its own. Neither where there are no Web Locks. */
+export declare function lockWallet(address: Address, kind?: 'wallet' | 'view', take?: boolean): Promise<Hold>;