@dcasegr/amm-client 0.0.0-stage → 0.38.2

package/dist/pool/runar-ir-schema.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `runar-ir-schema`, minus its Ajv validators: what the vendored runar-sdk modules
+ * (src/vendor/runar, their `runar-ir-schema` import rewritten to this file) read. See
+ * README.md "runar-sdk, vendored".
+ *
+ * runar-ir-schema's own `index.ts` re-exports `validators.ts`, which reads its
+ * JSON schemas from disk at import time (`node:fs`, `fileURLToPath(import.meta.url)`)
+ * and imports `ajv`. Neither works in a browser bundle, and runar-sdk never
+ * calls the validators. Every other value export of that barrel (and the
+ * artifact, ANF and stack IR types runar-sdk uses) is re-exported
+ * here from the vendored copy of its sources (src/vendor/runar/runar-ir-schema).
+ */
+export * from "../vendor/runar/runar-ir-schema/src/state-layout.js";
+export * from "../vendor/runar/runar-ir-schema/src/abi-type-encoding.js";
+export * from "../vendor/runar/runar-ir-schema/src/canonical-json.js";
+export * from "../vendor/runar/runar-ir-schema/src/input-limits.js";
+export * from "../vendor/runar/runar-ir-schema/src/unknown-anf-kind-error.js";
+export { MERGED_LOCAL_TEMP_PREFIX } from "../vendor/runar/runar-ir-schema/src/anf-ir.js";
+export type * from "../vendor/runar/runar-ir-schema/src/artifact.js";
+export type * from "../vendor/runar/runar-ir-schema/src/anf-ir.js";
+export type * from "../vendor/runar/runar-ir-schema/src/stack-ir.js";

package/dist/pool/runar-ir-schema.js

@@ -0,0 +1,18 @@
+/**
+ * `runar-ir-schema`, minus its Ajv validators: what the vendored runar-sdk modules
+ * (src/vendor/runar, their `runar-ir-schema` import rewritten to this file) read. See
+ * README.md "runar-sdk, vendored".
+ *
+ * runar-ir-schema's own `index.ts` re-exports `validators.ts`, which reads its
+ * JSON schemas from disk at import time (`node:fs`, `fileURLToPath(import.meta.url)`)
+ * and imports `ajv`. Neither works in a browser bundle, and runar-sdk never
+ * calls the validators. Every other value export of that barrel (and the
+ * artifact, ANF and stack IR types runar-sdk uses) is re-exported
+ * here from the vendored copy of its sources (src/vendor/runar/runar-ir-schema).
+ */
+export * from "../vendor/runar/runar-ir-schema/src/state-layout.js";
+export * from "../vendor/runar/runar-ir-schema/src/abi-type-encoding.js";
+export * from "../vendor/runar/runar-ir-schema/src/canonical-json.js";
+export * from "../vendor/runar/runar-ir-schema/src/input-limits.js";
+export * from "../vendor/runar/runar-ir-schema/src/unknown-anf-kind-error.js";
+export { MERGED_LOCAL_TEMP_PREFIX } from "../vendor/runar/runar-ir-schema/src/anf-ir.js";

package/dist/pool/template.d.ts

@@ -0,0 +1,295 @@
+import { LockingScript, PrivateKey, Transaction, UnlockingScript } from "@bsv/sdk";
+import { type PoolMethod, type PoolVersion } from "./artifact.js";
+/** The readonly constructor args (compiled into the code). */
+export interface PoolArgs {
+    /** The token's 32-byte BRC-162 id, hex, wire (internal) byte order. */
+    assetId: string;
+    lpFeeBps: bigint;
+    validatorFeeBps: bigint;
+    /** The relay's commission (constructor param 7), bps of amountIn in the input asset, paid to Swap's `commissionPkh`. */
+    commissionBps: bigint;
+}
+/** The mutable state after OP_RETURN. Keys are 33-byte compressed hex. */
+export interface PoolFields {
+    tokenReserve: bigint;
+    lpPubKey: string;
+    /** 33 zero bytes (hex) once rescinded (layout 2). */
+    validatorPubKey: string;
+    validatorIdentity: string;
+    /** Layout 2: the validator's nonce, 32 bytes hex. */
+    nonce?: string;
+    /** Layout 2: the validator's affirmation, DER hex ("" when the pool carries none). */
+    affirmation?: string;
+}
+/** A cleared ValidatorPubKey (Rescind, 0.13.0): 33 zero bytes. */
+export declare const RESCINDED_KEY: string;
+/** A decoded pool locking script. */
+export interface Pool {
+    /** The layout (artifact.ts): 2. */
+    version: PoolVersion;
+    args: PoolArgs;
+    state: PoolFields;
+    /** The Rúnar code (hex): what a call pushes as `_codePart`. */
+    code: string;
+    /** `code || OP_RETURN || state` (hex): the script runar-sdk sees. */
+    contractScript: string;
+}
+/** A pool output being spent. */
+export interface PoolUtxo {
+    txid: string;
+    vout: number;
+    satoshis: number;
+    script: string | LockingScript;
+    /** The pool's source transaction, when known (kept on the input for BEEF). */
+    sourceTransaction?: Transaction;
+}
+/** A non-pool input the builder adds after the pool (funding, token inputs). */
+export interface BuilderInput {
+    txid: string;
+    vout: number;
+    satoshis: number;
+    lockingScript: string | LockingScript;
+    sourceTransaction?: Transaction;
+    /**
+     * Signs this input once the transaction is final (e.g. `new P2PKH().unlock(key,
+     * "all", false, satoshis, lockingScript)`; a 1Color token on P2PKH unlocks the
+     * same way). Omitted: the input is left unsigned for a wallet to sign, and
+     * `estimatedUnlockLength` (default 107, a P2PKH) sizes the fee.
+     */
+    unlock?: {
+        sign(tx: Transaction, inputIndex: number): Promise<UnlockingScript>;
+        estimateLength(): Promise<number>;
+    };
+    estimatedUnlockLength?: number;
+}
+/** The miner fee: absolute sats, or a rate over the finished size. */
+export type FeeSpec = {
+    sats: number;
+} | {
+    satsPerKb: number;
+};
+interface CallCommon {
+    pool: PoolUtxo;
+    inputs: BuilderInput[];
+    /** Hash160 (hex) the change goes to. */
+    changePkh: string;
+    fee: FeeSpec;
+}
+export interface SwapParams extends CallCommon {
+    amountIn: bigint;
+    /** true: BSV in, tokens out. */
+    bsvIn: boolean;
+    /** Hash160 (hex) of the taker's payout. */
+    userPkh: string;
+    /** The validator key for the continuation. Default: derived from ValidatorIdentity and the pool outpoint (src/lib/keys.ts). */
+    nextValidatorPubKey?: string;
+    /**
+     * Hash160 (hex) the commission goes to (Swap's `commissionPkh`): the relay's
+     * `amm.swap.terms` address, or the taker's own. Always pushed; an output
+     * only when the commission (ceil(amountIn·CommissionBps/10000)) is nonzero.
+     */
+    commissionPkh: string;
+    /** What the caller priced the leg against; any mismatch is refused (see PoolBuildError). */
+    expect?: SwapExpectation;
+}
+/** `SwapParams` without the funding (inputs, change, fee): see `PoolTemplate.planSwap`. */
+export type SwapPlanParams = Omit<SwapParams, "inputs" | "changePkh" | "fee">;
+/** A pool call's required outputs and method arguments, before any funding is chosen. */
+export interface CallPlan {
+    pool: Pool;
+    poolUtxo: PoolUtxo;
+    method: PoolMethod;
+    /** The outputs the contract requires, in order; change (if any) follows them. */
+    outputs: {
+        satoshis: bigint;
+        script: string;
+    }[];
+    /** The method arguments, signature slots `EMPTY_SIG`. */
+    args: unknown[];
+    sigSlots: Partial<Record<SigSlot, number>>;
+    next: {
+        pool: Pool;
+        satoshis: number;
+        script: LockingScript;
+    };
+}
+export interface SwapExpectation {
+    bsvReserve?: bigint;
+    tokenReserve?: bigint;
+    lpFeeBps?: bigint;
+    validatorFeeBps?: bigint;
+    commissionBps?: bigint;
+    lpFee?: bigint;
+    validatorFee?: bigint;
+    commission?: bigint;
+    amountOut?: bigint;
+    minAmountOut?: bigint;
+}
+export interface CloseParams extends CallCommon {
+    /** The outputs, the LP's choice (the contract leaves them free). */
+    outputs: {
+        satoshis: bigint;
+        script: string;
+    }[];
+    /** The LP's key; when given, the LP slot is signed here. */
+    lpKey?: PoolSigner;
+}
+/** Signs a 32-byte sighash, returning a DER signature (without the sighash byte). */
+export type PoolSigner = PrivateKey | ((sighash: number[]) => Promise<number[]>);
+export type SigSlot = "validator" | "lp";
+/** A built pool call. */
+export interface PoolCall {
+    tx: Transaction;
+    method: PoolMethod;
+    /** The spent pool. */
+    pool: Pool;
+    /** The continuation (output 0), or null for a Close (it ends the pool). */
+    next: {
+        pool: Pool;
+        satoshis: number;
+        script: LockingScript;
+    } | null;
+    /** BIP-143 preimage (hex) the pool's signatures are over. */
+    preimage: string;
+    /** sha256d(preimage), hex: what the validator / LP sign. */
+    sighash: string;
+    /** Signature slots still OP_0 in input 0. */
+    unsigned: SigSlot[];
+    change: number;
+    fee: number;
+    /** Swap only: the trade, as the contract computes it. */
+    swap?: SwapAmounts;
+}
+/** A swap's trade, as the contract computes it (each fee in the input asset). */
+export interface SwapAmounts {
+    amountOut: bigint;
+    lpFee: bigint;
+    validatorFee: bigint;
+    commission: bigint;
+}
+export type PoolBuildErrorCode = "not_a_pool" | "stale_pool" | "fee_mismatch" | "quote_mismatch" | "slippage" | "token_mismatch" | "insufficient_funds" | "invalid";
+/** A refusal by the builder's own checks: nothing was signed. */
+export declare class PoolBuildError extends Error {
+    readonly code: PoolBuildErrorCode;
+    constructor(code: PoolBuildErrorCode, message: string);
+}
+export declare class PoolTemplate {
+    /**
+     * Decodes a pool locking script: a 1Color value prefix with a 32-byte id (no payload), then the Pool artifact
+     * (template bytes between the constructor slots), then the state. Also requires
+     * prefix id == assetId and prefix amount == TokenReserve (the admission check of
+     * Pool.runar.go's doc). Returns null for anything else.
+     */
+    static decode(script: string | LockingScript | number[]): Pool | null;
+    /** Whether the pool was rescinded by its validator (layout 2: ValidatorPubKey 33 zero bytes). */
+    static rescinded(pool: Pick<Pool, "state">): boolean;
+    /**
+     * A new pool's locking script (layout 2, 0.13.0): the 1Color prefix for TokenReserve (which
+     * the contract writes itself on every continuation, but nothing on chain writes for a deploy)
+     * in front of runar-sdk's locking script for the constructor args. `state` may leave the
+     * ValidatorPubKey, Nonce and Affirmation to come (33 zero bytes, absent, absent: the pool as
+     * `amm.pool.affirm` is asked about it); the deploy carries the validator's three.
+     */
+    static lockDeploy(args: PoolArgs, state: PoolFields): LockingScript;
+    /**
+     * The bytes the validator's affirmation signs (0.13.0, message v2, docs/AMM.md "The deploy
+     * and the affirmation"; src/pool.zig `affirmMessage`): "skein-amm affirm 2" ‖ AssetId (32,
+     * wire order) ‖ LpFeeBps ‖ ValidatorFeeBps ‖ CommissionBps (int64 LE) ‖ TokenReserve ‖ the
+     * pool output's satoshis (uint64 LE) ‖ LpPubKey ‖ ValidatorPubKey ‖ ValidatorIdentity (33
+     * each) ‖ Nonce (32). 221 bytes.
+     */
+    static affirmationMessage(pool: {
+        args: PoolArgs;
+        state: PoolFields;
+    }, satoshis: bigint): number[];
+    /**
+     * Whether the pool output (`script`, holding `satoshis`) attests itself (0.13.0, amm-lookup's
+     * deploy rule, src/pool.zig `affirmed`): layout 2, not rescinded, its ValidatorPubKey the
+     * ValidatorIdentity's child keyed by its Nonce (derived here), and its Affirmation that key's
+     * signature of `affirmationMessage`.
+     */
+    static affirmed(script: string | LockingScript | number[], satoshis: bigint): boolean;
+    /** The continuation script: `code` kept byte for byte, prefix and state rewritten. */
+    static lockContinuation(pool: Pool, state: PoolFields): LockingScript;
+    /**
+     * Swap (method 0). Outputs: 0 pool, 1 the taker's payout, then the LP fee,
+     * the validator fee and the commission (each only when nonzero, each in
+     * the input asset), then change. Token payouts and token fees are 1-sat
+     * 1Color outputs; BSV ones are P2PKH. The validator's slot is left empty.
+     */
+    static swap(p: SwapParams): Promise<PoolCall>;
+    /**
+     * The Swap call without its funding: the outputs the contract requires (in
+     * order: pool, payout, LP fee, validator fee, commission; no change) and
+     * the method arguments, with the validator's slot empty. For a builder that
+     * does not pick the funding itself (a BRC-100 wallet's `createAction` picks
+     * inputs and change): hand these outputs over, then fill input 0 with
+     * `callUnlock` over the transaction the wallet produced. Same checks and
+     * refusals as `swap` except the funding ones.
+     */
+    static planSwap(p: SwapPlanParams): CallPlan & {
+        swap: SwapAmounts;
+    };
+    /**
+     * The pool input's unlocking script for `plan` over a finished transaction
+     * `tx` whose input 0 spends `plan.poolUtxo` and whose outputs are
+     * `plan.outputs`, then (optionally) one P2PKH change output: `change` names
+     * it (`{pkh, satoshis}`), or `null` when there is none. Signature slots stay
+     * empty (`OP_0`), to be filled with `signPoolInput`. Throws when `tx` does
+     * not have that shape (the contract would refuse it).
+     */
+    static callUnlock(plan: CallPlan, tx: Transaction, change: {
+        pkh: string;
+        satoshis: number;
+    } | null): {
+        unlockingScript: UnlockingScript;
+        preimage: string;
+        sighash: string;
+    };
+    /**
+     * An upper bound on the length of `plan`'s pool unlocking script once every
+     * signature slot is filled: what a wallet's `createAction` is told as the
+     * pool input's `unlockingScriptLength` before the transaction exists (the
+     * fee is sized from it). The preimage's length depends only on the code, so
+     * it is exact; the change amount is bounded by 2^53.
+     */
+    static maxCallUnlockLength(plan: CallPlan): number;
+    /**
+     * Close (method 1; skein-amm 0.9.0, David Case 2026-10-09: a position is deployed or closed,
+     * never resized in place), the LP's, built here: the outputs are the LP's (`outputs`), then
+     * change. No continuation.
+     */
+    static close(p: CloseParams): Promise<PoolCall>;
+    /**
+     * The Close call without its funding (as `planSwap` for Swap), the LP's slot empty
+     * (`Close(lpSig)`, outputs free): `outputs` are the LP's choice, passed through (at least one).
+     */
+    static planClose(p: {
+        pool: PoolUtxo;
+        outputs: {
+            satoshis: bigint;
+            script: string;
+        }[];
+    }): CallPlan;
+    /**
+     * The BIP-143 preimage of `tx`'s pool input (input 0), computed from the
+     * transaction itself. Needs the pool output being spent: `source`, or input
+     * 0's `sourceTransaction`.
+     */
+    static preimage(tx: Transaction, source?: {
+        satoshis: number;
+        script: string | LockingScript;
+    }): string;
+    /**
+     * Fills signature slot `slot` of the pool input with `signer`'s signature
+     * over the preimage recomputed from `call.tx` (which must agree with the
+     * preimage pushed in the call). Every other push is kept byte for byte;
+     * no other input's signature is affected.
+     */
+    static signPoolInput(call: Pick<PoolCall, "tx" | "pool" | "method" | "unsigned"> & {
+        sourceSatoshis?: number;
+    }, slot: SigSlot, signer: PoolSigner): Promise<void>;
+}
+/** A P2PKH unlocker for a builder input (also a 1Color token held on P2PKH). */
+export declare function p2pkhUnlock(key: PrivateKey, satoshis: number, lockingScript: string | LockingScript): BuilderInput["unlock"];
+export {};