@geeqdev/geeq-sdk 0.1.0 → 0.2.0

package/dist/src/chain/geeq-chain.js

@@ -0,0 +1,721 @@
+import { assertDuration, assertUint32 } from '../assert';
+import { resolveAccountId } from '../crypto/account-id';
+import { toBase64 } from '../encoding/base64';
+import { accountNotAttestable, accountNotFound, amountBelowMinimum, chainMismatch, insufficientFunds, invalidArgument, nftNotOwned, noChain, } from '../errors';
+import { decimalsOf, formatGeeq, toPennies } from '../amount';
+import { decodeWalletAddressSync } from '../address/wallet-address';
+import { createCoinTransferTxSync } from '../tx/transfer';
+import { createNftMintProxyTxSync, nftMintProxiesIn, nftMintProxyId } from '../tx/proxy';
+import { createNftMintTxSync } from '../tx/nft';
+import { discover } from '../net/discovery';
+import { readLedger, readNftRecords } from '../net/read-ledger';
+import { defaultTransport, raceAbort } from '../net/transport';
+import { initGeeq } from '../runtime/init';
+import { createAttestationTxSync } from '../tx/attestation';
+import { ATTEST_HASH_BYTES, attestHashOf } from '../tx/content';
+import { GeeqNode } from './geeq-node';
+import { NonceGuard } from './nonce-guard';
+import { GEEQ_NODE_PORT, originOf, selectNode, serviceOriginOf } from './select';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_LEDGER_MAX_AGE_MS = 5_000;
+const DEFAULT_RETRIES = 1;
+/** The process-wide default, installed by {@link GeeqChain.init}. */
+let defaultChain = null;
+/**
+ * Refuse a nonsense option before anything is read. Left to the network layer, a negative
+ * `retries` sends no request at all and a zero `timeoutMs` times every request out — both
+ * reported as an unreachable node, which is the one thing they are not.
+ */
+function assertChainOptions(options) {
+    assertDuration(options.timeoutMs, 'timeoutMs');
+    if (options.timeoutMs === 0) {
+        throw invalidArgument('timeoutMs must be more than 0, or every request times out at once.');
+    }
+    assertDuration(options.ledgerMaxAgeMs, 'ledgerMaxAgeMs');
+    const { retries, nodePort } = options;
+    if (retries !== undefined && (!Number.isInteger(retries) || retries < 0)) {
+        throw invalidArgument(`retries must be a whole number, 0 or more, received ${String(retries)}.`);
+    }
+    if (nodePort !== undefined && (!Number.isInteger(nodePort) || nodePort < 1 || nodePort > 65_535)) {
+        throw invalidArgument(`nodePort must be a port from 1 to 65535, received ${JSON.stringify(nodePort)}.`);
+    }
+    if (options.chainNumber !== undefined)
+        assertUint32(options.chainNumber, 'chainNumber');
+    if (options.nodeNumber !== undefined)
+        assertUint32(options.nodeNumber, 'nodeNumber');
+}
+/**
+ * Refuse a transaction its payer cannot cover. The node checks the balance against the
+ * amount plus the fee, so this does too — after building, because the fee is charged on
+ * the signed bytes.
+ */
+function assertAffordable(penniesPerGeeq, payer, balance, amount, fee, block) {
+    const cost = amount + (fee?.total ?? 0n);
+    if (balance >= cost)
+        return;
+    const geeq = (pennies) => formatGeeq(pennies, penniesPerGeeq);
+    const needed = fee === undefined
+        ? geeq(amount)
+        : amount === 0n
+            ? `a fee of ${geeq(fee.total)}`
+            : `${geeq(amount)} plus a fee of ${geeq(fee.total)}`;
+    throw insufficientFunds(`${payer} holds ${geeq(balance)} geeq at block ${block}, and this needs ${needed} geeq.`);
+}
+/**
+ * A chain, reached through one node.
+ *
+ * Holds the node directory, the metadata limits and a short-lived ledger cache, so an
+ * attestation needs only a keypair and something to attest. Everything a transaction is
+ * pinned to — chain number, target block, node number, nonce — is read from the ledger
+ * rather than asked of the caller, because none of it can be known offline and a wrong
+ * value is rejected by the chain.
+ *
+ * A chain is bound to the endpoint it was connected to. To use a different node, connect
+ * another one: a different node means a different address, certificate and CORS origin,
+ * which is not something to switch silently.
+ *
+ * In a reactive framework, mark an instance raw (Vue's `markRaw`) rather than letting it
+ * be proxied.
+ */
+export class GeeqChain {
+    /** @internal */
+    constructor(init) {
+        this.endpoint = init.endpoint;
+        this.candidates = Object.freeze([...init.candidates]);
+        this.chainName = init.chainName;
+        this.penniesPerGeeq = init.penniesPerGeeq;
+        // Non-enumerable and TS-private, never `#private` — see GeeqNode for why.
+        const hidden = (key, value, writable = false) => {
+            Object.defineProperty(this, key, { value, enumerable: false, writable });
+        };
+        hidden('request', init.request);
+        hidden('ledgerMaxAgeMs', init.ledgerMaxAgeMs);
+        hidden('declaredChainNumber', init.chainNumber);
+        hidden('nodeNumberOverride', init.nodeNumber);
+        hidden('nonces', new NonceGuard());
+        hidden('cached', null, true);
+        hidden('resolved', null, true);
+        hidden('inflight', null, true);
+    }
+    /**
+     * Choose a chain and a node, without reading anything from the chain itself.
+     *
+     * With `discovery`, the directory is asked which nodes exist and one of the active
+     * ones is taken. With `endpoint`, that node is used as given. Either way **no ledger
+     * is fetched here** — a ledger read is only valid for a few blocks, so it happens when
+     * a transaction is actually being built rather than when the app starts.
+     */
+    static async connect(options) {
+        const hasDiscovery = options.discovery !== undefined;
+        const hasEndpoint = options.endpoint !== undefined;
+        if (hasDiscovery === hasEndpoint) {
+            throw invalidArgument('Provide exactly one of discovery (a node directory to pick an active node ' +
+                'from) or endpoint (a node you already know).');
+        }
+        decimalsOf(options.penniesPerGeeq);
+        assertChainOptions(options);
+        const request = Object.freeze({
+            transport: options.transport ?? defaultTransport,
+            timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            retries: options.retries ?? DEFAULT_RETRIES,
+            headers: options.headers,
+        });
+        let endpoint;
+        let candidates = [];
+        let chainName = options.chainName;
+        let chainNumber = options.chainNumber;
+        if (hasDiscovery) {
+            const found = await discover({
+                origin: serviceOriginOf(options.discovery),
+                ...(options.chainName === undefined ? {} : { chainName: options.chainName }),
+                chainNumber: options.chainNumber,
+                ...(options.nodePort === undefined ? {} : { port: options.nodePort }),
+                request: {
+                    ...request,
+                    ...(options.signal === undefined ? {} : { signal: options.signal }),
+                },
+            });
+            candidates = found.nodes;
+            chainName = found.chain.name;
+            chainNumber = found.chain.chainNumber;
+            // Spread across the usable nodes rather than everyone hammering the first one.
+            // The directory's order is stable, so picking [0] would concentrate every client
+            // of every app on one machine.
+            endpoint = found.usable[Math.floor(Math.random() * found.usable.length)].url;
+        }
+        else {
+            endpoint = originOf(options.endpoint);
+        }
+        return new GeeqChain({
+            endpoint,
+            candidates,
+            chainName,
+            chainNumber,
+            nodeNumber: options.nodeNumber,
+            penniesPerGeeq: options.penniesPerGeeq,
+            request,
+            ledgerMaxAgeMs: options.ledgerMaxAgeMs ?? DEFAULT_LEDGER_MAX_AGE_MS,
+        });
+    }
+    /** {@link GeeqChain.connect}, and install the result as the process-wide default. */
+    static async init(options) {
+        const chain = await GeeqChain.connect(options);
+        defaultChain = chain;
+        return chain;
+    }
+    /** The default chain. Throws `not-initialized` when there is none. */
+    static current() {
+        if (defaultChain === null)
+            throw noChain('GeeqChain.current()');
+        return defaultChain;
+    }
+    /** Whether a default chain has been installed. */
+    static get initialized() {
+        return defaultChain !== null;
+    }
+    /** Clear the default. Call this from `afterEach` so tests do not leak into each other. */
+    static reset() {
+        defaultChain = null;
+    }
+    /** Resolve an amount to pennies, reading a `{ geeq }` figure at {@link penniesPerGeeq}. */
+    toPennies(amount) {
+        return toPennies(amount, this.penniesPerGeeq);
+    }
+    /** Show pennies as a Geeq figure at {@link penniesPerGeeq}, as the Geeq wallet does. */
+    formatGeeq(pennies) {
+        return formatGeeq(pennies, this.penniesPerGeeq);
+    }
+    /**
+     * This chain's number.
+     *
+     * Known immediately when a directory named the chain, or once a ledger has been read.
+     * `undefined` in between — with a bare endpoint and no declared number, only the node
+     * can say.
+     */
+    get chainNumber() {
+        return this.cached?.chainNumber ?? this.declaredChainNumber;
+    }
+    /**
+     * The node, once a ledger read has identified it in the net actor list.
+     *
+     * `undefined` until then: a node's number is the one thing the directory cannot say,
+     * so it is not known before the first read.
+     */
+    get node() {
+        return this.resolved ?? undefined;
+    }
+    /** The net actor directory from the last ledger read, if there has been one. */
+    get nodes() {
+        return this.cached?.nodes ?? [];
+    }
+    /** Those of them that accept transactions. */
+    get processingNodes() {
+        return this.cached?.processingNodes ?? [];
+    }
+    /** The ledger from the last read, if it is still cached. */
+    get ledger() {
+        return this.cached ?? undefined;
+    }
+    /**
+     * A URL for another node in this chain.
+     *
+     * Every node answers client traffic on {@link GEEQ_NODE_PORT}, so only the scheme is
+     * carried over from the endpoint in use. The port recorded against a node in the
+     * ledger is its own internal listener and is never what you connect to.
+     */
+    endpointFor(host) {
+        return `${new URL(this.endpoint).protocol}//${host}:${GEEQ_NODE_PORT}`;
+    }
+    /**
+     * The current ledger, from cache when it is fresh enough.
+     *
+     * Staleness is safe in exactly one direction. The node accepts a target block within
+     * `[N-8, N+1]` of its own head, and a cached ledger can only be *behind*, so the
+     * target it yields is never in the future — the only rejected direction. The default
+     * five seconds is set by the node list and metadata limits, which have no such
+     * tolerance, not by the block window.
+     */
+    async getLedger(options = {}) {
+        const maxAge = options.maxAgeMs ?? this.ledgerMaxAgeMs;
+        const cached = this.cached;
+        if (cached !== null && maxAge > 0 && Date.now() - cached.readAt < maxAge)
+            return cached;
+        return this.read(options.signal);
+    }
+    /** Discard the cached ledger and read again. */
+    async refresh(options = {}) {
+        this.cached = null;
+        return this.read(options.signal);
+    }
+    /**
+     * One read at a time.
+     *
+     * Same single-flight shape as `initGeeq`, including clearing the promise on failure so
+     * a later call can retry rather than being stuck with the first error. Without it, a
+     * page that builds several transactions at once pulls the whole ledger several times
+     * from an endpoint with no rate limiting of any kind.
+     *
+     * The read is shared, so it carries no caller's signal: one caller aborting must not
+     * fail the others waiting on it. Each caller stops waiting on its own signal instead,
+     * and the read runs on, bounded by `timeoutMs`, to fill the cache for whoever is next.
+     */
+    read(signal) {
+        if (signal?.aborted === true)
+            return Promise.reject(signal.reason);
+        if (this.inflight !== null)
+            return raceAbort(this.inflight, signal);
+        const pending = readLedger(this.endpoint, this.request)
+            .then((ledger) => {
+            const declared = this.declaredChainNumber;
+            if (declared !== undefined && ledger.chainNumber !== declared) {
+                throw chainMismatch(`This chain was opened as chain ${declared} but the node at ${this.endpoint} ` +
+                    `serves chain ${ledger.chainNumber}. A transaction signed for the wrong ` +
+                    'chain is rejected, so either drop chainNumber to accept the node\'s, or ' +
+                    `use a node on chain ${declared}.`);
+            }
+            // The node's own number lives only in the ledger, so this is the first moment it
+            // can be known — and the first moment the node can be checked for being able to
+            // take work at all.
+            const selected = selectNode(ledger, this.endpoint, {
+                ...(this.nodeNumberOverride === undefined ? {} : { nodeNumber: this.nodeNumberOverride }),
+            });
+            this.resolved = new GeeqNode({ ...this.request, ...selected, url: this.endpoint });
+            this.cached = ledger;
+            return ledger;
+        })
+            .finally(() => {
+            this.inflight = null;
+        });
+        this.inflight = pending;
+        return raceAbort(pending, signal);
+    }
+    /**
+     * Everything a transaction must be pinned to, read from this chain.
+     *
+     * Throws rather than guessing when the account cannot sign: absent from the ledger
+     * (the ordinary state of an unfunded keypair), or present as a record type the
+     * protocol will not accept.
+     */
+    async getChainState(request) {
+        const ledger = await this.getLedger({
+            ...(request.maxAgeMs === undefined ? {} : { maxAgeMs: request.maxAgeMs }),
+            ...(request.signal === undefined ? {} : { signal: request.signal }),
+        });
+        return this.stateIn(ledger, request.account);
+    }
+    /**
+     * What every transaction built from `ledger` is pinned to, bar the signer's nonce: the
+     * same for a signer's own transaction and for a proxy's.
+     */
+    pinnedTo(ledger) {
+        return {
+            chainNumber: ledger.chainNumber,
+            blockNumber: ledger.targetBlockNumber,
+            nodeNumber: this.resolved.nodeNumber,
+            metadataLimits: ledger.metadataLimits,
+            geeqNorm: ledger.geeqNorm,
+            ledgerBlockNumber: ledger.blockNumber,
+            readAt: ledger.readAt,
+            nodeUrl: this.endpoint,
+        };
+    }
+    /** {@link getChainState} against a ledger already in hand, so a build reads only one. */
+    stateIn(ledger, ref) {
+        const accountId = resolveAccountId(ref);
+        const account = ledger.findCoinAccount(accountId);
+        const shown = toBase64(accountId);
+        if (account === undefined) {
+            throw accountNotFound(`Account ${shown} is not in the ledger of chain ${ledger.chainNumber} at block ` +
+                `${ledger.blockNumber}. An account exists on a Geeq chain only once it has ` +
+                'received coins, so a freshly generated keypair will not be there. Fund it, ' +
+                'then try again.');
+        }
+        if (account.kind !== 'asset' || account.nonce === undefined) {
+            const described = account.kind === 'hl'
+                ? 'a hash-lock record, which carries no nonce at all'
+                : account.kind === 'micro'
+                    ? 'a micro-coin record'
+                    : 'a record whose subtype could not be read';
+            throw accountNotAttestable(`Account ${shown} is in the ledger at block ${ledger.blockNumber} as ${described}, ` +
+                'but an attestation must be signed by a coin-asset account. Sign with a ' +
+                'coin-asset key on this chain instead.');
+        }
+        return Object.freeze({
+            ...this.pinnedTo(ledger),
+            nonce: account.nonce,
+            balance: account.balance,
+            minimumTransfer: ledger.minimumTransfer,
+        });
+    }
+    /**
+     * The ledger a build is made from, and the state of `signer` in it.
+     *
+     * A cached ledger is up to a few seconds old, so "this account already built against
+     * this block" may only mean "we are looking at an old block". Look again once before
+     * letting the nonce guard refuse — otherwise a caller who waited out the block interval
+     * is told to wait for a block that has already passed. An explicit nonce is the caller
+     * taking responsibility, so it skips the check.
+     *
+     * Everything the build then needs — what the sender holds, which proxies exist — comes
+     * from this same ledger, so it all describes one block.
+     */
+    async readForBuild(signer, explicitNonce, signal) {
+        const options = signal === undefined ? {} : { signal };
+        const [cached] = await Promise.all([this.getLedger(options), initGeeq()]);
+        const ledger = await this.recheckIfClaimed(cached, explicitNonce === undefined ? toBase64(signer.accountId) : undefined, options);
+        const chainState = this.stateIn(ledger, signer);
+        return {
+            ledger,
+            chainState: explicitNonce === undefined ? chainState : { ...chainState, nonce: explicitNonce },
+        };
+    }
+    /** Read afresh if `guardKey` already built against `ledger`'s block. See {@link readForBuild}. */
+    async recheckIfClaimed(ledger, guardKey, options) {
+        if (guardKey === undefined || !this.nonces.wouldCollide(guardKey, ledger.blockNumber)) {
+            return ledger;
+        }
+        return this.refresh(options);
+    }
+    /**
+     * Build and sign an attestation, deriving everything the chain decides.
+     *
+     * This is where the ledger is read, because this is the first moment the values it
+     * carries are actually needed — and they go stale within a handful of blocks, so
+     * reading them any earlier would only mean reading them twice.
+     *
+     * The result is **not submitted**. Hand it to {@link GeeqSocket.track} first, so its
+     * verdict has somewhere to arrive, then POST `transaction` and `payload` to
+     * {@link AttestationTx.nodeUrl}; any other node rejects it, because the node number is
+     * checked with strict equality.
+     */
+    async createAttestation(input) {
+        if ((input.content === undefined) === (input.attestHash === undefined)) {
+            throw invalidArgument('Provide exactly one of content (hashed here with BLAKE3) or attestHash (a ' +
+                `${ATTEST_HASH_BYTES}-byte digest you produced yourself).`);
+        }
+        const attestHash = input.attestHash ?? (await attestHashOf(input.content));
+        const { chainState } = await this.readForBuild(input.keypair, input.nonce, input.signal);
+        const tx = createAttestationTxSync({
+            keypair: input.keypair,
+            attestHash,
+            ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+            chainState,
+        });
+        assertAffordable(this.penniesPerGeeq, 'This account', chainState.balance, 0n, tx.fee, chainState.ledgerBlockNumber);
+        this.claimNonce(input.keypair, input.nonce, chainState, tx);
+        return tx;
+    }
+    /**
+     * Record the nonce a finished build took, so a second build against the same block is
+     * refused rather than sent to share it.
+     *
+     * Claimed only once a transaction really exists, so a build that failed validation does
+     * not consume the account's one nonce for this block. An explicit nonce is the caller
+     * taking responsibility, so it bypasses the guard entirely.
+     */
+    claimNonce(signer, explicitNonce, chainState, tx) {
+        if (explicitNonce !== undefined)
+            return;
+        this.nonces.claim(toBase64(signer.accountId), chainState.ledgerBlockNumber, chainState.nonce, toBase64(tx.transactionHash));
+    }
+    /**
+     * Resolve a recipient, checking the chain it belongs to when one is stated.
+     *
+     * An address carries a chain number, and an address from another chain is almost
+     * always a paste from the wrong place. The account id inside it would still be
+     * technically usable here, which is exactly why this is worth refusing rather than
+     * quietly sending.
+     */
+    resolveRecipient(to, chainNumber) {
+        if (typeof to !== 'string')
+            return resolveAccountId(to);
+        const decoded = decodeWalletAddressSync(to);
+        if (decoded.chainNumber !== chainNumber) {
+            throw chainMismatch(`The recipient address is for chain ${decoded.chainNumber} but this is chain ` +
+                `${chainNumber}. An address encodes its chain, so this one was almost certainly ` +
+                'copied from somewhere else — check it before sending.');
+        }
+        return decoded.accountId;
+    }
+    /**
+     * Send coin to another account, and NFTs with it if you name them.
+     *
+     * Reads the ledger, so it also knows what the sender holds and what the chain's minimum
+     * transfer is. The amount is checked against the minimum, and the sender's NFTs against
+     * the ones named, before anything is signed; the balance against the amount plus the
+     * fee once the signed transaction gives the fee. NFTs always travel with coin: leave
+     * `amount` out and they go with the chain's minimum transfer.
+     *
+     * The result is **not submitted**. Hand it to {@link GeeqSocket.track} first, then POST
+     * `transaction` to {@link CoinTransferTx.nodeUrl} using `coinTransferSubmitBody`, which
+     * sends it as type `uvt` — a different shape from an attestation, and with no separate
+     * payload.
+     */
+    async createTransfer(input) {
+        const nfts = input.nfts ?? [];
+        if (input.amount === undefined && nfts.length === 0) {
+            throw invalidArgument('Say what to send: an amount, NFTs, or both.');
+        }
+        const asked = input.amount === undefined ? undefined : this.toPennies(input.amount);
+        const { ledger, chainState } = await this.readForBuild(input.from, input.nonce, input.signal);
+        const to = this.resolveRecipient(input.to, chainState.chainNumber);
+        const minimum = chainState.minimumTransfer;
+        const pennies = asked ?? minimum;
+        if (pennies === undefined) {
+            throw invalidArgument('This chain publishes no minimum transfer to send with the NFTs by default, so pass amount.');
+        }
+        if (minimum !== undefined && pennies < minimum) {
+            throw amountBelowMinimum(`This chain will not accept a transfer below ${this.formatGeeq(minimum)} geeq, and ` +
+                `${this.formatGeeq(pennies)} is smaller. The minimum comes from the chain's own ` +
+                'minTxAmt and geeqNorm parameters, read at block ' +
+                `${chainState.ledgerBlockNumber}.`);
+        }
+        // The transaction names each NFT by id and by its place in the sender's list, read
+        // from the same ledger as the nonce, so both describe one block.
+        const held = ledger.findCoinAccount(input.from)?.nfts ?? [];
+        const entries = nfts.map((id) => {
+            const position = held.findIndex((nft) => toBase64(nft.id) === toBase64(id));
+            if (position === -1) {
+                throw nftNotOwned(`This account does not hold NFT ${toBase64(id)} at block ${ledger.blockNumber}. ` +
+                    'findNfts lists the ones it does; one just sent away is gone once a block confirms it.');
+            }
+            if (held[position]?.counterparty === true) {
+                throw invalidArgument(`NFT ${toBase64(id)} is a counterparty NFT, which a plain transfer cannot move.`);
+            }
+            return { id, position };
+        });
+        // The chain gives an NFT only to a wallet account (or a multisig proxy). A proxy's
+        // address is the likely paste here.
+        if (entries.length > 0) {
+            const proxy = ledger.findProxyAccount(to);
+            const account = ledger.findCoinAccount(to);
+            if ((proxy !== undefined && proxy.kind !== 'multisig') || (account !== undefined && account.kind !== 'asset')) {
+                throw invalidArgument(`The recipient is a ${proxy?.kind ?? account?.kind} record, and the chain gives NFTs ` +
+                    'only to a wallet account. Send them to a wallet address instead.');
+            }
+        }
+        const tx = createCoinTransferTxSync({
+            keypair: input.from,
+            to,
+            amount: pennies,
+            nfts: entries,
+            chainState,
+        });
+        assertAffordable(this.penniesPerGeeq, 'This account', chainState.balance, pennies, tx.fee, chainState.ledgerBlockNumber);
+        this.claimNonce(input.from, input.nonce, chainState, tx);
+        return tx;
+    }
+    /**
+     * The NFTs an account holds on this chain, in the order its record lists them, each with
+     * the hash and labels it was minted with.
+     *
+     * Which NFTs it holds comes from the validation layer ledger; what each stands for, from
+     * the application layer ledger, which is read afresh every time. An account the chain
+     * does not know holds none. A new NFT shows once a block has confirmed it, so pass
+     * `maxAgeMs: 0` to look straight after one was minted or sent.
+     */
+    async findNfts(request) {
+        const signal = request.signal === undefined ? {} : { signal: request.signal };
+        const [ledger, records] = await Promise.all([
+            this.getLedger({
+                ...(request.maxAgeMs === undefined ? {} : { maxAgeMs: request.maxAgeMs }),
+                ...signal,
+            }),
+            readNftRecords(this.endpoint, { ...this.request, ...signal }),
+        ]);
+        const held = ledger.findCoinAccount(request.owner)?.nfts ?? [];
+        return Object.freeze(held.map((nft) => {
+            const record = records.get(toBase64(nft.id));
+            return Object.freeze({ ...nft, attestHash: record?.attestHash, metadata: record?.metadata ?? [] });
+        }));
+    }
+    /**
+     * The NFT mint proxies an admin has on this chain, each with its index, and the index
+     * its next proxy takes: one past the highest in use, or 1 for an admin with none.
+     *
+     * A proxy appears once a block has confirmed it, so pass `maxAgeMs: 0` to look
+     * straight after one was submitted.
+     */
+    async findNftMintProxies(request) {
+        const [ledger] = await Promise.all([
+            this.getLedger({
+                ...(request.maxAgeMs === undefined ? {} : { maxAgeMs: request.maxAgeMs }),
+                ...(request.signal === undefined ? {} : { signal: request.signal }),
+            }),
+            initGeeq(),
+        ]);
+        return nftMintProxiesIn(ledger, request.admin);
+    }
+    /**
+     * Create a proxy to mint NFTs through.
+     *
+     * A proxy is a record of its own: it holds coin, carries its own nonce, and names one
+     * admin — `admin` here — who signs every mint made through it. Its id is derived from
+     * the admin's key and an index, as the Geeq wallet derives it: by default the next
+     * index {@link findNftMintProxies} reports, so it is found again from the key alone.
+     *
+     * Checks the funding against the chain's minimum, and the admin's balance against the
+     * funding plus the fee. The result is **not submitted** — track it, then post it with
+     * `coinTransferSubmitBody`, exactly as a transfer. The proxy exists once a block
+     * confirms it.
+     */
+    async createNftMintProxy(input) {
+        const pennies = this.toPennies(input.amount);
+        const { ledger, chainState } = await this.readForBuild(input.admin, input.nonce, input.signal);
+        // The node holds proxy funding to the same minimum as any transfer.
+        const minimum = chainState.minimumTransfer;
+        if (minimum !== undefined && pennies < minimum) {
+            throw amountBelowMinimum(`A proxy must be funded with at least ${this.formatGeeq(minimum)} geeq, and ` +
+                `${this.formatGeeq(pennies)} is smaller. It is the same minimum as a transfer, from ` +
+                "the chain's minTxAmt and geeqNorm parameters, read at block " +
+                `${chainState.ledgerBlockNumber}.`);
+        }
+        const existing = nftMintProxiesIn(ledger, input.admin);
+        const index = input.index ?? existing.nextIndex;
+        if (existing.proxies.some((proxy) => proxy.index === index)) {
+            throw invalidArgument(`This admin already has a proxy at index ${index}. Leave index out to take the ` +
+                `next one, ${existing.nextIndex}.`);
+        }
+        const tx = createNftMintProxyTxSync({
+            keypair: input.admin,
+            index,
+            amount: pennies,
+            chainState,
+        });
+        assertAffordable(this.penniesPerGeeq, 'This account', chainState.balance, pennies, tx.fee, chainState.ledgerBlockNumber);
+        this.claimNonce(input.admin, input.nonce, chainState, tx);
+        return tx;
+    }
+    /**
+     * Mint an NFT through one of the admin's proxies.
+     *
+     * The proxy is the sender: it pays the fee and the coin sent with the NFT, and spends
+     * its own nonce, not the admin's. The admin signs. The NFT itself is the content's hash
+     * and labels, as an attestation is, and its id is derived from them — so the same
+     * content with the same labels through the same proxy cannot be minted twice.
+     *
+     * Reads the ledger to find the proxy and check what it holds. The result is **not
+     * submitted** — track it, then post it with `attestationSubmitBody`, exactly as an
+     * attestation: two fields, as `uat`.
+     */
+    async mintNft(input) {
+        if ((input.content === undefined) === (input.attestHash === undefined)) {
+            throw invalidArgument('Provide exactly one of content (hashed here with BLAKE3) or attestHash (a ' +
+                `${ATTEST_HASH_BYTES}-byte digest you produced yourself).`);
+        }
+        assertUint32(input.index, 'index');
+        const attestHash = input.attestHash ?? (await attestHashOf(input.content));
+        const signal = input.signal === undefined ? {} : { signal: input.signal };
+        const [cached] = await Promise.all([this.getLedger(signal), initGeeq()]);
+        const proxyKey = toBase64(nftMintProxyId(input.admin.publicKey, input.index));
+        // The proxy spends its own nonce, so the guard is keyed on the proxy, not the admin.
+        const ledger = await this.recheckIfClaimed(cached, input.nonce === undefined ? proxyKey : undefined, signal);
+        const proxy = ledger
+            .findProxyAccounts({ admin: input.admin })
+            .find((found) => toBase64(found.accountId) === proxyKey);
+        if (proxy === undefined) {
+            throw accountNotFound(`This admin has no NFT mint proxy at index ${input.index} in the ledger of chain ` +
+                `${ledger.chainNumber} at block ${ledger.blockNumber}. A new proxy appears once a ` +
+                'block has confirmed it; findNftMintProxies lists the ones there are.');
+        }
+        const minimum = ledger.minimumTransfer;
+        const pennies = input.amount === undefined ? minimum : this.toPennies(input.amount);
+        if (pennies === undefined) {
+            throw invalidArgument('This chain publishes no minimum transfer to send with the NFT by default, so pass amount.');
+        }
+        if (minimum !== undefined && pennies < minimum) {
+            throw amountBelowMinimum(`A mint must send at least ${this.formatGeeq(minimum)} geeq with the NFT, and ` +
+                `${this.formatGeeq(pennies)} is smaller. It is the same minimum as a transfer, from ` +
+                "the chain's minTxAmt and geeqNorm parameters, read at block " +
+                `${ledger.blockNumber}.`);
+        }
+        const tx = createNftMintTxSync({
+            keypair: input.admin,
+            proxyAccountId: proxy.accountId,
+            attestHash,
+            ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+            to: input.to === undefined
+                ? input.admin.accountId
+                : this.resolveRecipient(input.to, ledger.chainNumber),
+            amount: pennies,
+            chainState: { ...this.pinnedTo(ledger), nonce: input.nonce ?? proxy.nonce },
+        });
+        // The proxy pays, not the admin. Topping it up is a plain transfer to its address.
+        assertAffordable(this.penniesPerGeeq, `Proxy ${input.index}`, proxy.balance, pennies, tx.fee, ledger.blockNumber);
+        if (input.nonce === undefined) {
+            this.nonces.claim(proxyKey, ledger.blockNumber, proxy.nonce, toBase64(tx.transactionHash));
+        }
+        return tx;
+    }
+    /**
+     * Whether a built transaction is now too old to send: the chain is past its
+     * `validUntilBlock`, and a node would refuse it with an HTTP 400.
+     *
+     * Reads the ledger afresh, because a cached one can only be behind the chain and would
+     * say "not yet" when it already is. Call it before submitting a transaction that may
+     * have waited.
+     */
+    async isExpired(tx) {
+        const ledger = await this.getLedger({ maxAgeMs: 0 });
+        return ledger.blockNumber > tx.validUntilBlock;
+    }
+    /**
+     * Give back the nonce a built transaction took, because it will never be sent — the
+     * user changed something and is building again. The next build may then take the same
+     * nonce in the same block instead of being refused with `nonce-collision`.
+     *
+     * Only for a transaction that was not submitted: if it reaches the node as well as its
+     * rebuild, the two share a nonce and the node rejects both.
+     */
+    discard(tx) {
+        this.nonces.release(toBase64(tx.transactionHash));
+    }
+    /** Forget which accounts have built a transaction against the current block. */
+    forgetNonces() {
+        this.nonces.clear();
+    }
+    /** Drop cached state, and step down as the default if this chain holds that slot. */
+    dispose() {
+        this.cached = null;
+        this.resolved = null;
+        this.inflight = null;
+        this.nonces.clear();
+        if (defaultChain === this)
+            defaultChain = null;
+    }
+    toJSON() {
+        return {
+            chainNumber: this.chainNumber,
+            endpoint: this.endpoint,
+            node: this.node,
+            ledgerBlockNumber: this.cached?.blockNumber,
+            candidateCount: this.candidates.length,
+        };
+    }
+    toString() {
+        return `GeeqChain(chain ${this.chainNumber ?? 'unread'} via ${this.endpoint})`;
+    }
+}
+/**
+ * Connect to a chain and make it the default.
+ *
+ * Thin alias for {@link GeeqChain.init} — the name most applications reach for, and one
+ * line so there is no second implementation to keep in step.
+ *
+ * ```ts
+ * await initChain({ endpoint: 'https://1.2.3.4:2082' })
+ * const tx = await attest({ keypair, content: fileBytes })
+ * ```
+ */
+export function initChain(options) {
+    return GeeqChain.init(options);
+}
+/** Build an attestation on the default chain. See {@link GeeqChain.createAttestation}. */
+export function attest(input) {
+    return GeeqChain.current().createAttestation(input);
+}
+/** Send coin on the default chain. See {@link GeeqChain.createTransfer}. */
+export function transfer(input) {
+    return GeeqChain.current().createTransfer(input);
+}
+//# sourceMappingURL=geeq-chain.js.map