@zerc20/storage-sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org/>

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @zerc20/storage-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Private note delivery for zERC20 on the Internet Computer. A payer leaves a note's opening, encrypted, in the storage
+canister, and the receiver finds it with its view key. The canister holds only ciphertext under unlinkable ids, so it
+cannot tell who paid whom. Every secret stays in this SDK.
+
+```sh
+npm install @zerc20/storage-sdk
+```
+
+Node 22.12 or later. Apps that hold a wallet use it through `@zerc20/wallet-sdk`.
+
+## License
+
+[Unlicense](LICENSE)

package/dist/candid.d.ts

@@ -0,0 +1,73 @@
+import type { ActorMethod } from '@icp-sdk/core/agent';
+import type { IDL } from '@icp-sdk/core/candid';
+export type KindName = 'Outgoing' | 'Lane';
+export type Kind = {
+    [K in KindName]: {
+        [P in K]: null;
+    };
+}[KindName];
+export type Action = {
+    OpenChannel: {
+        inbox: Uint8Array;
+        enc_announcement: Uint8Array;
+        outgoing_id: Uint8Array;
+        enc_outgoing: Uint8Array;
+    };
+} | {
+    Put: {
+        kind: Kind;
+        id: Uint8Array;
+        data: Uint8Array;
+    };
+};
+export interface AuditRequest {
+    target: Uint8Array;
+    notify_key: Uint8Array;
+    transport_public_key: Uint8Array;
+    expiry_ns: bigint;
+    signature: Uint8Array;
+}
+export interface Registration {
+    address: Uint8Array;
+    public_key: Uint8Array;
+    notify_key: Uint8Array;
+    escrow: Uint8Array;
+    expiry_ns: bigint;
+    signature: Uint8Array;
+}
+export interface Slot {
+    data: Uint8Array;
+    at_ns: bigint;
+}
+export interface AuditRecord {
+    auditor: Uint8Array;
+    target: Uint8Array;
+    notify_key: Uint8Array;
+    transport_public_key: Uint8Array;
+    expiry_ns: bigint;
+    signature: Uint8Array;
+    at_ns: bigint;
+}
+export type CanisterError = {
+    Occupied: Uint8Array;
+} | {
+    Rejected: string;
+};
+export type Result<T> = {
+    Ok: T;
+} | {
+    Err: CanisterError;
+};
+export interface Service {
+    escrow_public_key: ActorMethod<[], Result<Uint8Array>>;
+    register: ActorMethod<[Registration, bigint], Result<null>>;
+    registration: ActorMethod<[Uint8Array, [] | [Uint8Array]], [] | [Registration]>;
+    audit_escrow_key: ActorMethod<[AuditRequest], Result<Uint8Array>>;
+    get_audits: ActorMethod<[bigint, number], AuditRecord[]>;
+    submit: ActorMethod<[Action[], bigint], Result<null>>;
+    get_announcements: ActorMethod<[Uint8Array, number, number], Uint8Array[]>;
+    get_slots: ActorMethod<[Kind, Uint8Array[]], ([] | [Slot])[]>;
+    get_log: ActorMethod<[bigint, number], Uint8Array[]>;
+    log_length: ActorMethod<[], bigint>;
+}
+export declare const idlFactory: IDL.InterfaceFactory;

package/dist/candid.js

@@ -0,0 +1,51 @@
+// The zerc20_storage Candid interface (canister/zerc20_storage.did), by hand: generated bindings
+// target the older @dfinity/* packages.
+export const idlFactory = ({ IDL }) => {
+    const Blob = IDL.Vec(IDL.Nat8);
+    const Error = IDL.Variant({ Occupied: Blob, Rejected: IDL.Text });
+    const BlobResult = IDL.Variant({ Ok: Blob, Err: Error });
+    const UnitResult = IDL.Variant({ Ok: IDL.Null, Err: Error });
+    const Kind = IDL.Variant({ Outgoing: IDL.Null, Lane: IDL.Null });
+    const Action = IDL.Variant({
+        OpenChannel: IDL.Record({ inbox: Blob, enc_announcement: Blob, outgoing_id: Blob, enc_outgoing: Blob }),
+        Put: IDL.Record({ kind: Kind, id: Blob, data: Blob }),
+    });
+    const AuditRequest = IDL.Record({
+        target: Blob,
+        notify_key: Blob,
+        transport_public_key: Blob,
+        expiry_ns: IDL.Nat64,
+        signature: Blob,
+    });
+    const Registration = IDL.Record({
+        address: Blob,
+        public_key: Blob,
+        notify_key: Blob,
+        escrow: Blob,
+        expiry_ns: IDL.Nat64,
+        signature: Blob,
+    });
+    const Slot = IDL.Record({ data: Blob, at_ns: IDL.Nat64 });
+    const AuditRecord = IDL.Record({
+        auditor: Blob,
+        target: Blob,
+        notify_key: Blob,
+        transport_public_key: Blob,
+        expiry_ns: IDL.Nat64,
+        signature: Blob,
+        at_ns: IDL.Nat64,
+    });
+    return IDL.Service({
+        escrow_public_key: IDL.Func([], [BlobResult], []),
+        register: IDL.Func([Registration, IDL.Nat64], [UnitResult], []),
+        registration: IDL.Func([Blob, IDL.Opt(Blob)], [IDL.Opt(Registration)], ['query']),
+        audit_escrow_key: IDL.Func([AuditRequest], [BlobResult], []),
+        get_audits: IDL.Func([IDL.Nat64, IDL.Nat32], [IDL.Vec(AuditRecord)], ['query']),
+        submit: IDL.Func([IDL.Vec(Action), IDL.Nat64], [UnitResult], []),
+        get_announcements: IDL.Func([Blob, IDL.Nat32, IDL.Nat32], [IDL.Vec(Blob)], ['query']),
+        get_slots: IDL.Func([Kind, IDL.Vec(Blob)], [IDL.Vec(IDL.Opt(Slot))], ['query']),
+        get_log: IDL.Func([IDL.Nat64, IDL.Nat32], [IDL.Vec(Blob)], ['query']),
+        log_length: IDL.Func([], [IDL.Nat64], ['query']),
+    });
+};
+//# sourceMappingURL=candid.js.map

package/dist/candid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candid.js","sourceRoot":"","sources":["../src/candid.ts"],"names":[],"mappings":"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"}

package/dist/canister.d.ts

@@ -0,0 +1,33 @@
+import { type ActorSubclass, type Agent } from '@icp-sdk/core/agent';
+import { Principal } from '@icp-sdk/core/principal';
+import { DerivedPublicKey } from '@dfinity/vetkeys';
+import { type Action, type CanisterError, type Registration, type Result, type Service } from './candid.js';
+/** A definite answer from the canister: `Occupied` (the slot holds other data) or `Rejected`. */
+export declare class StorageError extends Error {
+    readonly error: CanisterError;
+    constructor(error: CanisterError);
+    get occupied(): boolean;
+}
+export declare function unwrap<T>(result: Result<T>): T;
+export declare class CanisterClient {
+    #private;
+    readonly canisterId: Principal;
+    /** Queries answered by a single replica: cheap, but only good for spotting news. */
+    readonly actor: ActorSubclass<Service>;
+    /** Every method as an update call, so the subnet agrees on the answer. */
+    readonly replicated: ActorSubclass<Service>;
+    /** A client over HTTP. A local replica (an `http://` host on this machine) has its root key fetched; the IC's is
+     * built in. A root key fetched from anywhere else would let whoever is on the path forge every certified answer. */
+    static connect(host: string, canisterId: Principal | string): Promise<CanisterClient>;
+    constructor(agent: Agent, canisterId: Principal | string);
+    /** The key owners IBE-encrypt their escrows with. Fixed for the canister's lifetime. */
+    escrowPublicKey(): Promise<DerivedPublicKey>;
+    /** `address`'s registration with `notifyKey`, by default its current one: a query, which one replica answers.
+     * Unverified: check it with `verifyRegistration`. Call `replicated.registration` where a stale answer matters. */
+    registration(address: Uint8Array, notifyKey?: Uint8Array): Promise<Registration | null>;
+    /** Solves the proof of work and registers. An identical registration that is already stored is a
+     * no-op, so a call whose outcome is unknown can be repeated. */
+    register(registration: Registration): Promise<void>;
+    /** Solves the proof of work and submits the batch. Throws `StorageError` on a definite failure. */
+    submit(actions: Action[]): Promise<void>;
+}

package/dist/canister.js

@@ -0,0 +1,76 @@
+// A zerc20_storage canister, called anonymously.
+import { Actor, HttpAgent } from '@icp-sdk/core/agent';
+import { Principal } from '@icp-sdk/core/principal';
+import { DerivedPublicKey } from '@dfinity/vetkeys';
+import { idlFactory } from './candid.js';
+import { hex } from './crypto.js';
+import { REGISTER_POW_BITS, actionsDigest, registerDigest, requiredPowBits, solvePow } from './wire.js';
+/** A definite answer from the canister: `Occupied` (the slot holds other data) or `Rejected`. */
+export class StorageError extends Error {
+    error;
+    constructor(error) {
+        super('Occupied' in error ? `occupied: 0x${hex(error.Occupied)}` : `rejected: ${error.Rejected}`);
+        this.error = error;
+    }
+    get occupied() {
+        return 'Occupied' in this.error;
+    }
+}
+/** Each request gives up after this, so that one that hangs does not hold its caller forever. A call cut off may still
+ * have landed, as one whose connection drops may. */
+const TIMEOUT_MS = 30_000;
+const fetchWithTimeout = (input, init) => {
+    const timeout = AbortSignal.timeout(TIMEOUT_MS);
+    return fetch(input, { ...init, signal: init?.signal ? AbortSignal.any([init.signal, timeout]) : timeout });
+};
+export function unwrap(result) {
+    if ('Err' in result)
+        throw new StorageError(result.Err);
+    return result.Ok;
+}
+export class CanisterClient {
+    canisterId;
+    /** Queries answered by a single replica: cheap, but only good for spotting news. */
+    actor;
+    /** Every method as an update call, so the subnet agrees on the answer. */
+    replicated;
+    #escrowPublicKey;
+    /** A client over HTTP. A local replica (an `http://` host on this machine) has its root key fetched; the IC's is
+     * built in. A root key fetched from anywhere else would let whoever is on the path forge every certified answer. */
+    static async connect(host, canisterId) {
+        const url = new URL(host);
+        const local = url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+        const agent = await HttpAgent.create({ host, shouldFetchRootKey: local, fetch: fetchWithTimeout });
+        return new CanisterClient(agent, canisterId);
+    }
+    constructor(agent, canisterId) {
+        this.canisterId = Principal.from(canisterId);
+        const config = { agent, canisterId: this.canisterId };
+        this.actor = Actor.createActor(idlFactory, config);
+        this.replicated = Actor.createActor(idlFactory, { ...config, queryStrategy: 'update' });
+    }
+    /** The key owners IBE-encrypt their escrows with. Fixed for the canister's lifetime. */
+    escrowPublicKey() {
+        this.#escrowPublicKey ??= this.actor.escrow_public_key().then((r) => DerivedPublicKey.deserialize(unwrap(r)));
+        this.#escrowPublicKey.catch(() => (this.#escrowPublicKey = undefined));
+        return this.#escrowPublicKey;
+    }
+    /** `address`'s registration with `notifyKey`, by default its current one: a query, which one replica answers.
+     * Unverified: check it with `verifyRegistration`. Call `replicated.registration` where a stale answer matters. */
+    async registration(address, notifyKey) {
+        const r = await this.actor.registration(address, notifyKey ? [notifyKey] : []);
+        return r[0] ?? null;
+    }
+    /** Solves the proof of work and registers. An identical registration that is already stored is a
+     * no-op, so a call whose outcome is unknown can be repeated. */
+    async register(registration) {
+        const nonce = await solvePow(registerDigest(registration), REGISTER_POW_BITS);
+        unwrap(await this.actor.register(registration, nonce));
+    }
+    /** Solves the proof of work and submits the batch. Throws `StorageError` on a definite failure. */
+    async submit(actions) {
+        const nonce = await solvePow(actionsDigest(actions), requiredPowBits(actions));
+        unwrap(await this.actor.submit(actions, nonce));
+    }
+}
+//# sourceMappingURL=canister.js.map

package/dist/canister.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canister.js","sourceRoot":"","sources":["../src/canister.ts"],"names":[],"mappings":"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"}

package/dist/crypto.d.ts

@@ -0,0 +1,27 @@
+import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils.js';
+export { bytesToHex as hex, hexToBytes as unhex, randomBytes };
+export declare const utf8: (text: string) => Uint8Array;
+export declare function concat(...parts: Uint8Array[]): Uint8Array;
+export declare function u32be(n: number): Uint8Array;
+export declare function u64be(n: bigint): Uint8Array;
+export declare const readU32: (bytes: Uint8Array, at: number) => number;
+export declare const readU64: (bytes: Uint8Array, at: number) => bigint;
+export declare function equal(a: Uint8Array, b: Uint8Array): boolean;
+/** Lexicographic (= big-endian numeric, for equal lengths) comparison. */
+export declare function compare(a: Uint8Array, b: Uint8Array): number;
+/** `u32_be(len) ‖ part` for every part, so fields can never run into each other. */
+export declare function lengthPrefixed(parts: Uint8Array[]): Uint8Array;
+/** Unix time in ns from the local clock. */
+export declare const nowNs: () => bigint;
+/** HKDF-SHA256 of `key`, domain-separated by `label` and the length-prefixed `parts`. */
+export declare function kdf(key: Uint8Array, label: string, parts?: Uint8Array[]): Uint8Array;
+/** SHA-256 of `tag` and `parts`, each length-prefixed: what anyone can compute, where `kdf` needs a key. */
+export declare function taggedHash(tag: string, parts: Uint8Array[]): Uint8Array;
+/** `nonce(12) ‖ ChaCha20-Poly1305`. The nonce is random so that a retry after a failed but
+ * already-visible call never reuses a (key, nonce) pair. */
+export declare function seal(key: Uint8Array, aad: Uint8Array, msg: Uint8Array): Uint8Array;
+export declare function open(key: Uint8Array, aad: Uint8Array, blob: Uint8Array): Uint8Array | null;
+/** ECIES to an X25519 public key: `ephemeral_pk(32) ‖ seal(..)`. `null` for a low-order key, whose
+ * shared secret anyone could compute. */
+export declare function sealTo(publicKey: Uint8Array, label: string, aad: Uint8Array, msg: Uint8Array): Uint8Array | null;
+export declare function openFrom(secret: Uint8Array, label: string, aad: Uint8Array, blob: Uint8Array): Uint8Array | null;

package/dist/crypto.js

@@ -0,0 +1,99 @@
+// Primitives: HKDF-SHA256, ChaCha20-Poly1305 with random nonces, X25519 ECIES, and byte helpers.
+import { chacha20poly1305 } from '@noble/ciphers/chacha.js';
+import { x25519 } from '@noble/curves/ed25519.js';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils.js';
+export { bytesToHex as hex, hexToBytes as unhex, randomBytes };
+export const utf8 = (text) => new TextEncoder().encode(text);
+export function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const part of parts) {
+        out.set(part, at);
+        at += part.length;
+    }
+    return out;
+}
+export function u32be(n) {
+    const out = new Uint8Array(4);
+    new DataView(out.buffer).setUint32(0, n, false);
+    return out;
+}
+export function u64be(n) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, n, false);
+    return out;
+}
+export const readU32 = (bytes, at) => new DataView(bytes.buffer, bytes.byteOffset).getUint32(at, false);
+export const readU64 = (bytes, at) => new DataView(bytes.buffer, bytes.byteOffset).getBigUint64(at, false);
+export function equal(a, b) {
+    return a.length === b.length && a.every((byte, i) => byte === b[i]);
+}
+/** Lexicographic (= big-endian numeric, for equal lengths) comparison. */
+export function compare(a, b) {
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    }
+    return a.length - b.length;
+}
+/** `u32_be(len) ‖ part` for every part, so fields can never run into each other. */
+export function lengthPrefixed(parts) {
+    return concat(...parts.flatMap((part) => [u32be(part.length), part]));
+}
+/** Unix time in ns from the local clock. */
+export const nowNs = () => BigInt(Date.now()) * 1000000n;
+const KDF_SALT = utf8('zerc20/storage/kdf/v1');
+/** HKDF-SHA256 of `key`, domain-separated by `label` and the length-prefixed `parts`. */
+export function kdf(key, label, parts = []) {
+    return hkdf(sha256, key, KDF_SALT, lengthPrefixed([utf8(label), ...parts]), 32);
+}
+/** SHA-256 of `tag` and `parts`, each length-prefixed: what anyone can compute, where `kdf` needs a key. */
+export function taggedHash(tag, parts) {
+    return sha256(lengthPrefixed([utf8(tag), ...parts]));
+}
+/** `nonce(12) ‖ ChaCha20-Poly1305`. The nonce is random so that a retry after a failed but
+ * already-visible call never reuses a (key, nonce) pair. */
+export function seal(key, aad, msg) {
+    const nonce = randomBytes(12);
+    return concat(nonce, chacha20poly1305(key, nonce, aad).encrypt(msg));
+}
+export function open(key, aad, blob) {
+    if (blob.length < 12)
+        return null;
+    try {
+        return chacha20poly1305(key, blob.subarray(0, 12), aad).decrypt(blob.subarray(12));
+    }
+    catch {
+        return null;
+    }
+}
+/** ECIES to an X25519 public key: `ephemeral_pk(32) ‖ seal(..)`. `null` for a low-order key, whose
+ * shared secret anyone could compute. */
+export function sealTo(publicKey, label, aad, msg) {
+    const ephemeral = x25519.utils.randomSecretKey();
+    const ephemeralPk = x25519.getPublicKey(ephemeral);
+    let shared;
+    try {
+        shared = x25519.getSharedSecret(ephemeral, publicKey);
+    }
+    catch {
+        return null;
+    }
+    return concat(ephemeralPk, seal(kdf(shared, label, [ephemeralPk, publicKey]), aad, msg));
+}
+export function openFrom(secret, label, aad, blob) {
+    if (blob.length < 32)
+        return null;
+    const ephemeralPk = blob.subarray(0, 32);
+    try {
+        const shared = x25519.getSharedSecret(secret, ephemeralPk);
+        const key = kdf(shared, label, [ephemeralPk, x25519.getPublicKey(secret)]);
+        return open(key, aad, blob.subarray(32));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"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"}

package/dist/formats.d.ts

@@ -0,0 +1,202 @@
+/** A sealed slot's plaintext: the blob less the nonce and the tag. */
+export declare const SLOT_PLAIN: number;
+/** An inbox announcement's plaintext: also less the ephemeral key. */
+export declare const ANNOUNCE_PLAIN: number;
+/** The most salts a burn block holds. */
+export declare const BURN_BLOCK = 6;
+/** The BN254 scalar field modulus `Fr`, big-endian. */
+export declare const FR_BE: Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>;
+/** Record types, the first byte of every plaintext. */
+export declare const NOTE = 1;
+export declare const CODE_NOTE = 2;
+export declare const SELF_NOTE = 3;
+export declare const DEPOSIT = 4;
+export declare const BURN_BLOCK_RECORD = 5;
+export declare const RETURNED = 6;
+export declare const DEPOSIT_ADDRESS = 7;
+export declare const POS_LANE = 8;
+export declare const SENT_TO_ADDRESS = 16;
+export declare const SENT_TO_CODE = 17;
+export declare const CHANNEL = 32;
+export declare const RECEIVE_CODE = 64;
+/** The inbox announcements of channels to `address` go to, under its registration's notify key: another
+ * registration, another inbox, so payers then open fresh channels. */
+export declare const addressInbox: (address: Uint8Array, notifyKey: Uint8Array) => Uint8Array;
+/** The payer's seed for its channel to `inbox`, recomputable from the payer's view key alone. */
+export declare const channelSeed: (seed: Uint8Array, payer: Uint8Array, inbox: Uint8Array) => Uint8Array;
+/** A channel's lane key. Binding the inbox and the claimed payer means a seed learned from one channel opens
+ * nothing when replayed into another inbox or under another name. */
+export declare const channelKey: (channelSeed: Uint8Array, inbox: Uint8Array, payer: Uint8Array) => Uint8Array;
+/** The lane key of receive code `index` (burn index `index` of `tokenId` on `chainId`). Every payer of the code
+ * writes its notes to this one lane, and the owner finds them through the log: no inbox, no announcement. */
+export declare const codeKey: (seed: Uint8Array, chainId: bigint, tokenId: number, index: number) => Uint8Array;
+/** The owner's own lane key: notes to self (merge outputs and change) and burn blocks, which only the owner's
+ * devices write and read. */
+export declare const ownKey: (seed: Uint8Array) => Uint8Array;
+/** The lane key of the owner's point of sale `n`, handed to that point of sale alone: it records there the burn
+ * addresses it makes for the owner, ahead of handing them out. */
+export declare const posKey: (seed: Uint8Array, n: number) => Uint8Array;
+/** The slot of record `slotIndex` on `chainId` in the lane of `laneKey`. */
+export declare const slotId: (laneKey: Uint8Array, chainId: bigint, slotIndex: number) => Uint8Array;
+export declare const sealKey: (laneKey: Uint8Array) => Uint8Array;
+export declare const outgoingId: (seed: Uint8Array, index: number) => Uint8Array;
+export declare const outgoingKey: (seed: Uint8Array) => Uint8Array;
+/** What an on-chain note commits to besides its owner's `public_key`:
+ * `note_hash = Poseidon(chain_id, public_key, value, token_id, note_salt)`. */
+export interface NoteOpening {
+    chainId: bigint;
+    tokenId: number;
+    /** Big-endian, below 2^248 (its first byte is 0). */
+    value: Uint8Array;
+    /** Big-endian canonical `Fr` element, fresh for every note. */
+    noteSalt: Uint8Array;
+}
+/** What a payment, withdrawal or merge was, kept on its note to self (its change, even of zero value, or a merge's
+ * output), so that every device of the owner shows it: that note on chain says it landed. */
+export interface Receipt {
+    kind: 'sent' | 'sent-to-code' | 'withdrawn' | 'unwrapped' | 'merged';
+    /** Big-endian, below 2^248, as a note's value: what was paid or withdrawn, or what a merge's note holds. */
+    amount: Uint8Array;
+    /** The same: what the relayer was paid for it. */
+    fee: Uint8Array;
+    /** Whom it paid: an address, a receive code's burn address, or for a merge 20 zero bytes. */
+    counterparty: Uint8Array;
+}
+/** What the owner did that leaves no note to self, kept in the own lane so that every device of the owner shows it:
+ * a deposit into its burn address returned to its sender (a rage exit), or a deposit address it registered for one. */
+export type OwnReceipt = {
+    chainId: bigint;
+    tokenId: number;
+    burnAddress: Uint8Array;
+} & ({
+    kind: 'returned';
+    /** The deposit's `commitment_index`. */
+    index: number;
+    recipient: Uint8Array;
+    /** Big-endian, below 2^248. */
+    amount: Uint8Array;
+    txHash: Uint8Array;
+} | {
+    kind: 'deposit-address';
+    depositAddress: Uint8Array;
+});
+/** Where a record sat in its lane, and when the canister first stored it (kept in the clear). */
+interface Stamped {
+    /** Position in the lane's sequence for its chain (0, 1, 2, …), which locates its slot. Not the on-chain
+     * `commitment_index`; slots that do not open leave gaps. */
+    slotIndex: number;
+    atNs: bigint;
+}
+export interface Note extends Stamped {
+    kind: 'note';
+    opening: NoteOpening;
+    /** In a receive code's lane, the payer it claims to be (unverified). */
+    payer?: Uint8Array;
+    /** In the own lane, what it is the change or the output of; missing for a kind this version does not know. */
+    receipt?: Receipt;
+}
+/** Not a note on chain: a deposit of `value` into the receiver's burn address of `burnSalt`, under the `public_key`
+ * the payer looked up (zERC20-v2's `burn_address`), paid by a plain transfer. */
+export interface Deposit extends Stamped {
+    kind: 'deposit';
+    chainId: bigint;
+    tokenId: number;
+    /** Big-endian, below 2^248, as a note's. */
+    value: Uint8Array;
+    burnSalt: Uint8Array;
+    /** The burn address, which the receiver derives itself: for the payer's other devices, to find the transfer. */
+    burnAddress: Uint8Array;
+}
+/** Burn addresses `first, first + 1, ..` of `tokenId` on `chainId`, by their salts, which their owner may have handed
+ * out. Whoever hands one out records its block first, so every device of the owner finds the payments to it. In the
+ * own lane they are zERC20-v2's `keys::burn` indices; in a point of sale's lane, its `keys::pos_burn` counters. Salts,
+ * because deriving an address takes about 2^16 hashes, and checking one from its salt takes one. */
+export interface BurnBlock {
+    chainId: bigint;
+    tokenId: number;
+    first: number;
+    /** 32 bytes each, 1 to `BURN_BLOCK` of them. */
+    salts: Uint8Array[];
+}
+/** In the own lane: the owner made point of sale `n`, whose lane (`posKey`) its devices then read. */
+export interface PosLane {
+    n: number;
+}
+export type LaneRecord = Note | Deposit | (BurnBlock & Stamped & {
+    kind: 'burn-block';
+}) | (OwnReceipt & Stamped) | (PosLane & Stamped & {
+    kind: 'pos-lane';
+});
+/** Which lane a record was read from: the records each holds, and who writes it. */
+export type LaneKind = 'channel' | 'code' | 'own' | 'pos';
+/** A note's plaintext, `token_id(4) ‖ value(31) ‖ note_salt(32)`, or `null` if a field is out of the circuit's range
+ * (an out-of-range field can hash like a different value). With `payer` it is a note to a receive code, naming its
+ * payer; with `receipt`, a note to self, saying what it is the change or the output of. */
+export declare function notePlaintext(opening: NoteOpening, extra?: {
+    payer: Uint8Array;
+} | {
+    receipt: Receipt;
+} | null): Uint8Array | null;
+/** A deposit's announcement, `token_id(4) ‖ value(31) ‖ burn_salt(32) ‖ burn_address(20)`, or `null` if the value or
+ * the salt is out of range. */
+export declare function depositPlaintext(tokenId: number, value: Uint8Array, burnSalt: Uint8Array, burnAddress: Uint8Array): Uint8Array | null;
+/** `token_id(4) ‖ burn_address(20) ‖` then a return's `index(8) ‖ recipient(20) ‖ amount(31) ‖ tx_hash(32)`, or a
+ * deposit address's `deposit_address(20)`. */
+export declare function ownReceiptPlaintext(r: OwnReceipt): Uint8Array;
+/** `token_id(4) ‖ first(4) ‖ count(1) ‖ salt(32) × count`. */
+export declare function burnBlockPlaintext(b: BurnBlock): Uint8Array;
+/** `n(4)`. */
+export declare function posLanePlaintext(n: number): Uint8Array;
+/** The record a slot of a `lane` lane on `chainId` held, or `null` if it is malformed or not one such a lane holds. */
+export declare function readLaneRecord(lane: LaneKind, chainId: bigint, slotIndex: number, atNs: bigint, plain: Uint8Array): LaneRecord | null;
+/** Where to pay: handed from receiver to payer over a trusted channel. It does not name the receiver, but whoever
+ * swaps it in transit redirects the funds. Pay any amount, by a transfer to `burnAddress` (a deposit), or by a note
+ * owned by `publicKey` written to the lane of `key`. */
+export interface ReceiveCode {
+    chainId: bigint;
+    tokenId: number;
+    /** zERC20-v2's `keys::burn` address of the code's index. */
+    burnAddress: Uint8Array;
+    /** The zERC20 public key the paying note commits to: the code's own (`keys::code_secret`), not the address's, so
+     * codes cannot be linked to each other or to the address. */
+    publicKey: Uint8Array;
+    key: Uint8Array;
+}
+/** A receive code as text: bech32m of `RECEIVE_CODE ‖ chain_id(8) ‖ token_id(4) ‖ burn_address(20) ‖ public_key(32) ‖
+ * key(32)`, so a mistyped one fails its checksum instead of paying someone else. */
+export declare function encodeCode(c: ReceiveCode): string;
+/** The receive code `text` holds, or `null` for anything else. */
+export declare function decodeCode(text: string): ReceiveCode | null;
+/** Where a payer paid, as its outgoing record keeps it: an address under one of its registrations (its notify key),
+ * or a receive code. */
+export type Target = {
+    address: Uint8Array;
+    notifyKey: Uint8Array;
+} | ReceiveCode;
+/** `address(20) ‖ notify_key(32)`, or the code's body. */
+export declare function targetPlaintext(t: Target): Uint8Array;
+export declare function readTarget(plain: Uint8Array): Target | null;
+/** A channel's announcement, `payer(20) ‖ channel_seed(32)`: who claims to open it, and the seed its lane key derives
+ * from. */
+export declare function channelPlaintext(payer: Uint8Array, seed: Uint8Array): Uint8Array;
+export declare function readChannel(plain: Uint8Array): {
+    payer: Uint8Array;
+    seed: Uint8Array;
+} | null;
+/** How records reach a receiver: through a channel to its address, a receive code's lane, or the lane of one of its
+ * points of sale. The code's owner knows it by its token and burn index; a payer by the code itself. */
+export type Via = {
+    type: 'address';
+} | {
+    type: 'code';
+    chainId: bigint;
+    tokenId: number;
+    index: number;
+} | {
+    type: 'code';
+    code: ReceiveCode;
+} | {
+    type: 'pos';
+    n: number;
+};
+export {};