@getcofund/protocol 0.0.0-stage → 0.1.0

package/dist/btc/vault/build.js

@@ -0,0 +1,136 @@
+/** biome-ignore-all lint/suspicious/noBitwiseOperators: Taproot control-block bytes encode parity with bit masks. */
+import { hex } from "@scure/base";
+import * as btc from "@scure/btc-signer";
+import { Script } from "@scure/btc-signer";
+import { taprootTweakPubkey } from "@scure/btc-signer/utils.js";
+import { assertDistinctLeafKeys, sortUsers } from "./helpers.js";
+import { BTC_VAULT_MAX_PARTICIPANTS } from "./limits.js";
+import { buildKofNScript, kOfNOps } from "./script.js";
+function bytesEq(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+export function buildAdminRequiredThenKofN(adminXonly, allXonly, t) {
+    if (t < 2) {
+        throw new Error("AR leaf requires t >= 2");
+    }
+    if (adminXonly.length !== 32) {
+        throw new Error("admin x-only must be 32 bytes");
+    }
+    if (allXonly.length > BTC_VAULT_MAX_PARTICIPANTS) {
+        throw new Error(`too many keys: ${allXonly.length} exceeds the vault participant limit of ${BTC_VAULT_MAX_PARTICIPANTS}`);
+    }
+    // exclude admin from the body set to prevent double-counting
+    const others = allXonly.filter((pk) => !bytesEq(pk, adminXonly));
+    if (others.length < t - 1) {
+        throw new Error(`invalid AR body: need ${t - 1} of ${others.length} (admin excluded)`);
+    }
+    // Script ops: <admin> CHECKSIGVERIFY + (t-1)-of-(others)
+    const ops = [
+        adminXonly,
+        "CHECKSIGVERIFY",
+        ...kOfNOps(others, t - 1),
+    ];
+    return Script.encode(ops);
+}
+export function buildVault(contract, companyUsers, network, options) {
+    const users = sortUsers(companyUsers);
+    const admins = users.filter((u) => u.role === "admin");
+    const allXonly = users.map((u) => u.xonly);
+    // Default 2 keeps pre-threshold vaults (contractId without the field)
+    // re-deriving to the same address.
+    const threshold = options?.threshold ?? 2;
+    if (threshold < 2 || threshold > users.length) {
+        throw new Error(`Invalid threshold ${threshold}: must be between 2 and ${users.length}`);
+    }
+    const minThreshold = threshold;
+    const drafts = [];
+    const isNAR = contract.vaultType === "ALL" || contract.vaultType === "ADMINS_INCLUDED";
+    if (isNAR) {
+        // NAR: one leaf per threshold over ALL users
+        const script = buildKofNScript(allXonly, minThreshold);
+        drafts.push({ threshold: minThreshold, signers: users, script });
+    }
+    else {
+        // AR: for each threshold and each admin, require that admin + (t-1)-of-all
+        if (admins.length === 0) {
+            throw new Error("ADMINS_REQUIRED vault needs at least one admin");
+        }
+        // your rule: min threshold is always 2, so t-1 >= 1
+        for (const admin of admins) {
+            const bodySigners = users.filter((user) => user.id !== admin.id);
+            const script = buildAdminRequiredThenKofN(admin.xonly, allXonly, minThreshold);
+            // The witness consumes the pinned admin first and then the body ladder.
+            // Preserve that same order in metadata so signing never interprets a
+            // script-ordered stack through the unrelated global x-only sort order.
+            drafts.push({
+                threshold: minThreshold,
+                signers: [admin, ...bodySigners],
+                script,
+            });
+        }
+    }
+    // console.log(`Built ${drafts.length} leaf scripts`);
+    // for (const d of drafts) {
+    //   console.log(d.script);
+    // }
+    // Before the address exists: no leaf may hold one key in two slots. Legacy
+    // vaults store raw compressed pubkeys rather than xpubs, but the k-of-n
+    // ladder counts signatures identically, so a duplicate collapses it the same
+    // way.
+    if (!options?.reconstructingExistingVault) {
+        assertDistinctLeafKeys(drafts);
+    }
+    // 2) Convert to a Taproot script tree using btc.taprootListToTree
+    //    NOTE: leaf version 0xc0 for tapscript v0
+    const leavesList = drafts.map((d) => ({
+        script: d.script,
+        version: 0xc0,
+    }));
+    console.log(`Building tree with ${leavesList.length} leaves...`);
+    const tree = btc.taprootListToTree(leavesList);
+    // 3) Build P2TR: tweaked pubkey, merkle root, control blocks, scriptPubKey, address
+    const res = btc.p2tr(contract.internalKeyXonly, tree, network, true);
+    // 4) Join p2tr outputs back to our drafts.
+    //    btc.p2tr returns leaves[] with { hash, controlBlock, script?, version? } in the SAME order
+    //    as leavesList. We index by position to merge.
+    const byScript = new Map(drafts.map((d) => [hex.encode(d.script), d]));
+    const [_, parity] = taprootTweakPubkey(contract.internalKeyXonly, res.tapMerkleRoot);
+    const outLeaves = res.leaves.map((leaf) => {
+        const key = hex.encode(leaf.script);
+        const d = byScript.get(key); //k-of-n metadata
+        const tweakedParity = res.tweakedPubkey.length === 33
+            ? res.tweakedPubkey[0] & 1 // 0x02=>0, 0x03=>1
+            : 0;
+        const baseVer = (leaf.version ?? 0xc0) & 0xfe; // LSB=0 for tapscript v0
+        const cbVersion = baseVer | tweakedParity;
+        const cbStruct = {
+            version: cbVersion,
+            internalKey: res.tapInternalKey, // x-only internal key (32B)
+            merklePath: leaf.path, // siblings from p2tr()
+            parity,
+        };
+        return {
+            threshold: d.threshold,
+            script: d.script,
+            leafHash: leaf.hash,
+            signers: d.signers,
+            controlBlockStruct: cbStruct,
+        };
+    });
+    return {
+        merkleRoot: res.tapMerkleRoot,
+        tweakedPubkey: res.tweakedPubkey,
+        scriptPubKey: res.script,
+        address: res.address,
+        leaves: outLeaves,
+        internalPubKey: contract.internalKeyXonly,
+    };
+}

package/dist/btc/vault/canonical-order.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Compare by UTF-16 code unit — what the `<` and `>` operators do.
+ *
+ * Total, pure, and identical in every runtime and locale. For ASCII inputs
+ * (UUIDs, hex digests, Base58) this is byte order: digits, then `A`–`Z`, then
+ * `a`–`z`. Anywhere a sort decides bytes that get hashed, signed or turned into
+ * an address, the comparator is part of the protocol: `localeCompare()` resolves
+ * the ambient collation, and several locales reorder plain ASCII.
+ */
+export declare function compareCodepoint(a: string, b: string): number;

package/dist/btc/vault/canonical-order.js

@@ -0,0 +1,18 @@
+/**
+ * Compare by UTF-16 code unit — what the `<` and `>` operators do.
+ *
+ * Total, pure, and identical in every runtime and locale. For ASCII inputs
+ * (UUIDs, hex digests, Base58) this is byte order: digits, then `A`–`Z`, then
+ * `a`–`z`. Anywhere a sort decides bytes that get hashed, signed or turned into
+ * an address, the comparator is part of the protocol: `localeCompare()` resolves
+ * the ambient collation, and several locales reorder plain ASCII.
+ */
+export function compareCodepoint(a, b) {
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}

package/dist/btc/vault/from-contract-id.d.ts

@@ -0,0 +1,9 @@
+import type { BTC_NETWORK } from "@scure/btc-signer/utils.js";
+import type { BuiltVault } from "./types.ts";
+/** Label that pairs with a `BTC_NETWORK` — only mainnet derives differently. */
+export declare function networkLabelOf(btcNetwork: BTC_NETWORK): "mainnet" | "testnet";
+/**
+ * Reconstructs a Taproot structure from a serialized contract ID against an
+ * explicit network. Auto-detects account-based vs legacy format.
+ */
+export declare function buildTaprootForNetwork(contractId: string, btcNetwork: BTC_NETWORK): BuiltVault;

package/dist/btc/vault/from-contract-id.js

@@ -0,0 +1,74 @@
+import { hex } from "@scure/base";
+import { buildVault } from "./build.js";
+import { findDuplicateLeafKeys } from "./helpers.js";
+import { buildAccountBasedVault } from "./vault-policy.js";
+import { deserializeVaultContractData } from "./vaultContractUtil.js";
+// Reconstruction core, free of any process configuration: the app wraps it with
+// its network for the request paths (`taprootUtils.ts`), and the SDK and the
+// client-vault export pass their own.
+/** Label that pairs with a `BTC_NETWORK` — only mainnet derives differently. */
+export function networkLabelOf(btcNetwork) {
+    return btcNetwork.bech32 === "bc" ? "mainnet" : "testnet";
+}
+/**
+ * Reconstructs a Taproot structure from a serialized contract ID against an
+ * explicit network. Auto-detects account-based vs legacy format.
+ */
+export function buildTaprootForNetwork(contractId, btcNetwork) {
+    const contractData = deserializeVaultContractData(contractId);
+    // Vaults created before the threshold was configurable omit the field — 2.
+    const threshold = contractData.threshold ?? 2;
+    // This vault already exists on chain and its address is fixed, so the
+    // leaf-key uniqueness invariant is reported rather than enforced: throwing
+    // here would break every read path — including the ones needed to move the
+    // funds out of a vault that IS collapsed. See `warnOnCollapsedRoster`.
+    let built;
+    // Account-based vaults: rebuild from xpubs via vault-policy builder
+    if (contractData.accountBased && contractData.accountXpubs) {
+        const network = contractData.network ?? networkLabelOf(btcNetwork);
+        if (!contractData.nums) {
+            throw new Error("Account vault is missing its BIP341 NUMS recipe");
+        }
+        built = buildAccountBasedVault(contractData.accountXpubs, contractData.vaultType, network, {
+            nums: contractData.nums,
+            btcNetwork,
+            reconstructingExistingVault: true,
+            threshold,
+            // The vault's own ordering rule, resolved by the deserializer. Never
+            // the process default — that is how a Czech-locale browser used to
+            // render a different address than the server for one contractId.
+            participantOrdering: contractData.participantOrdering,
+        });
+    }
+    else {
+        // Legacy vaults: MuSig2 aggregate internal key
+        const internalKeyXonly = hex.decode(contractData.aggregateKey);
+        const contract = {
+            vaultType: contractData.vaultType,
+            internalKeyXonly,
+        };
+        built = buildVault(contract, contractData.companyUsers, btcNetwork, {
+            reconstructingExistingVault: true,
+            threshold,
+        });
+    }
+    warnOnCollapsedRoster(built);
+    return built;
+}
+/**
+ * Log a vault whose signers share a key.
+ *
+ * New vaults can no longer be built this way, but one created before the
+ * invariant landed would silently keep a threshold that a single key can meet.
+ * Surfacing it in the logs is how we'd find out: the vault is not fixable in
+ * place — the roster is baked into the funded script — so the funds have to be
+ * moved to a newly constructed address.
+ */
+function warnOnCollapsedRoster(built) {
+    // Logging must never be the reason an address fails to resolve: callers run
+    // this inside `.map()` over transaction rows and in PDF/email generation.
+    const duplicates = findDuplicateLeafKeys(built.leaves ?? []);
+    if (duplicates.length > 0) {
+        console.error(`SECURITY: BTC vault ${built.address} has signers sharing a key, so its threshold can be met by one signer. Move the funds to a newly created vault.`, duplicates);
+    }
+}

package/dist/btc/vault/helpers.d.ts

@@ -0,0 +1,73 @@
+import type { User, VaultType } from "./types.ts";
+/**
+ * Sort users by x-only asc, then id (deterministic).
+ *
+ * Both comparisons are by code point. The primary key is lowercase hex, which
+ * every collation orders identically, but the `id` tie-break used to be
+ * `localeCompare` — and ids are UUIDs, which a `da`/`nb` runtime reorders
+ * because it folds `aa` to `å`. The tie only fires when two users share an
+ * x-only key, which `assertDistinctLeafKeys` now rejects at creation, so this
+ * could only ever have bitten a legacy vault with a duplicated roster. Code
+ * point matches what an `en`-family runtime already produced for UUIDs, so no
+ * existing address moves.
+ */
+export declare function sortUsers(users: User[]): User[];
+export declare function subsets<T>(arr: T[]): Iterable<T[]>;
+export declare function isValidLeaf(vt: VaultType, t: number, S: User[]): boolean;
+/** A leaf (or leaf draft) reduced to what the uniqueness check needs. */
+type LeafKeys = {
+    signers: {
+        id: string;
+        xonly: Uint8Array;
+    }[];
+};
+export type DuplicateLeafKey = {
+    /** Hex x-only key that more than one signer slot resolved to. */
+    xonly: string;
+    /** Ids of every signer that resolved to it, in script order. */
+    signerIds: string[];
+};
+/**
+ * Find signer slots within a leaf that resolved to the SAME x-only key.
+ *
+ * Non-throwing counterpart to {@link assertDistinctLeafKeys}, for read paths
+ * that must keep working on an already-created vault.
+ */
+export declare function findDuplicateLeafKeys(leaves: LeafKeys[]): DuplicateLeafKey[];
+/**
+ * Every signer slot in a leaf must resolve to a DISTINCT x-only key.
+ *
+ * A tapscript threshold ladder counts signatures, not signers. BIP-342 does
+ * not require the keys or the signatures in a CHECKSIG/CHECKSIGADD chain to be
+ * distinct — every nonempty signature that verifies increments the counter —
+ * so when two company users share one account xpub they derive one leaf key,
+ * occupy two slots, and the holder of that key reaches threshold=2 alone. A
+ * hard 2-of-N collapses to 1-of-N and Bitcoin cannot tell the two users apart.
+ *
+ * Checked against the signer roster rather than the script's pushed keys,
+ * which is strictly stronger: an ADMINS_REQUIRED leaf filters keys equal to
+ * its admin out of the body, so a duplicate there is silently *dropped* from
+ * the cosigner set instead of double-counted — the script then encodes a
+ * narrower policy than the roster claims. Both outcomes are data errors.
+ *
+ * Runs before the address is derived. An address built from a duplicated
+ * roster cannot be un-built: per-user rows can be corrected afterwards, but
+ * the funded script stays collapsed and the funds have to be moved to a newly
+ * constructed vault.
+ */
+export declare function assertDistinctLeafKeys(leaves: LeafKeys[]): void;
+/**
+ * Thrown by {@link assertDistinctLeafKeys}. Carries an actionable message
+ * because it is a data problem an admin can fix, not an internal fault — the
+ * BTC deployer re-throws it verbatim instead of collapsing it into its generic
+ * "failed deploying" error.
+ */
+export declare class DuplicateSignerKeyError extends Error {
+    readonly duplicates: DuplicateLeafKey[];
+    constructor(duplicates: DuplicateLeafKey[]);
+}
+export interface KeyAggResult {
+    aggPubXonly: Uint8Array;
+}
+export declare function aggregateKeys(hexKeys: (string | Uint8Array)[]): KeyAggResult;
+export {};

package/dist/btc/vault/helpers.js

@@ -0,0 +1,129 @@
+import { hex } from "@scure/base";
+import * as musig2 from "@scure/btc-signer/musig2.js";
+import { compareCodepoint } from "./canonical-order.js";
+/**
+ * Sort users by x-only asc, then id (deterministic).
+ *
+ * Both comparisons are by code point. The primary key is lowercase hex, which
+ * every collation orders identically, but the `id` tie-break used to be
+ * `localeCompare` — and ids are UUIDs, which a `da`/`nb` runtime reorders
+ * because it folds `aa` to `å`. The tie only fires when two users share an
+ * x-only key, which `assertDistinctLeafKeys` now rejects at creation, so this
+ * could only ever have bitten a legacy vault with a duplicated roster. Code
+ * point matches what an `en`-family runtime already produced for UUIDs, so no
+ * existing address moves.
+ */
+export function sortUsers(users) {
+    return [...users].sort((a, b) => {
+        const byKey = compareCodepoint(hex.encode(a.xonly), hex.encode(b.xonly));
+        return byKey === 0 ? compareCodepoint(a.id, b.id) : byKey;
+    });
+}
+// All non-empty subsets
+export function* subsets(arr) {
+    const n = arr.length;
+    for (let mask = 1; mask < 1 << n; mask++) {
+        const sub = [];
+        for (let i = 0; i < n; i++) {
+            if (mask & (1 << i)) {
+                sub.push(arr[i]);
+            }
+        }
+        yield sub;
+    }
+}
+// ADMINS_REQUIRED validity: include (t,S) iff members(S) <= t-1
+export function isValidLeaf(vt, t, S) {
+    if (vt === "ALL" || vt === "ADMINS_INCLUDED") {
+        return true;
+    }
+    const members = S.filter((u) => u.role === "member").length;
+    return members <= t - 1;
+}
+/**
+ * Find signer slots within a leaf that resolved to the SAME x-only key.
+ *
+ * Non-throwing counterpart to {@link assertDistinctLeafKeys}, for read paths
+ * that must keep working on an already-created vault.
+ */
+export function findDuplicateLeafKeys(leaves) {
+    const duplicates = [];
+    for (const leaf of leaves) {
+        const idsByKey = new Map();
+        for (const signer of leaf.signers) {
+            const key = hex.encode(signer.xonly);
+            const ids = idsByKey.get(key) ?? [];
+            ids.push(signer.id);
+            idsByKey.set(key, ids);
+        }
+        for (const [xonly, signerIds] of idsByKey) {
+            if (signerIds.length > 1) {
+                duplicates.push({ xonly, signerIds });
+            }
+        }
+    }
+    return duplicates;
+}
+/**
+ * Every signer slot in a leaf must resolve to a DISTINCT x-only key.
+ *
+ * A tapscript threshold ladder counts signatures, not signers. BIP-342 does
+ * not require the keys or the signatures in a CHECKSIG/CHECKSIGADD chain to be
+ * distinct — every nonempty signature that verifies increments the counter —
+ * so when two company users share one account xpub they derive one leaf key,
+ * occupy two slots, and the holder of that key reaches threshold=2 alone. A
+ * hard 2-of-N collapses to 1-of-N and Bitcoin cannot tell the two users apart.
+ *
+ * Checked against the signer roster rather than the script's pushed keys,
+ * which is strictly stronger: an ADMINS_REQUIRED leaf filters keys equal to
+ * its admin out of the body, so a duplicate there is silently *dropped* from
+ * the cosigner set instead of double-counted — the script then encodes a
+ * narrower policy than the roster claims. Both outcomes are data errors.
+ *
+ * Runs before the address is derived. An address built from a duplicated
+ * roster cannot be un-built: per-user rows can be corrected afterwards, but
+ * the funded script stays collapsed and the funds have to be moved to a newly
+ * constructed vault.
+ */
+export function assertDistinctLeafKeys(leaves) {
+    const duplicates = findDuplicateLeafKeys(leaves);
+    if (duplicates.length > 0) {
+        throw new DuplicateSignerKeyError(duplicates);
+    }
+}
+/**
+ * Thrown by {@link assertDistinctLeafKeys}. Carries an actionable message
+ * because it is a data problem an admin can fix, not an internal fault — the
+ * BTC deployer re-throws it verbatim instead of collapsing it into its generic
+ * "failed deploying" error.
+ */
+export class DuplicateSignerKeyError extends Error {
+    duplicates;
+    constructor(duplicates) {
+        const detail = duplicates
+            .map((d) => `${d.signerIds.join(" + ")} → ${d.xonly}`)
+            .join("; ");
+        super("Cannot create this Bitcoin vault: two or more signers share the same " +
+            "key, and a single signature from it would meet the vault's threshold " +
+            "on its own. Give each signer their own extended public key " +
+            `(${detail})`);
+        this.name = "DuplicateSignerKeyError";
+        this.duplicates = duplicates;
+    }
+}
+export function aggregateKeys(hexKeys) {
+    if (hexKeys.length < 2) {
+        throw new Error("Need at least 2 pubkeys for MuSig");
+    }
+    const pubKeys = hexKeys.map((k, i) => {
+        const bytes = typeof k === "string" ? hex.decode(k) : k;
+        if (bytes.length !== 33 || (bytes[0] !== 0x02 && bytes[0] !== 0x03)) {
+            throw new Error(`Pubkey #${i} must be compressed (33 bytes starting with 0x02/0x03)`);
+        }
+        return bytes;
+    });
+    const sortedKeys = musig2.sortKeys(pubKeys);
+    const ctx = musig2.keyAggregate(sortedKeys);
+    const aggPubXonly = musig2.keyAggExport(ctx);
+    return { aggPubXonly };
+}

package/dist/btc/vault/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A Bitcoin vault's taproot tree, built from its definition: the members'
+ * account xpubs, the template, the threshold, the participant ordering and the
+ * NUMS recipe. The app builds and reconstructs vaults with this code
+ * (`apps/cofund/src/lib/bitcoin_scriptpath/creation` re-exports it), and the
+ * SDK rebuilds a vault to check its address before signing for it.
+ */
+export * from "./bip341-nums.ts";
+export * from "./build.ts";
+export * from "./canonical-order.ts";
+export * from "./from-contract-id.ts";
+export * from "./helpers.ts";
+export * from "./limits.ts";
+export * from "./participant-order.ts";
+export * from "./script.ts";
+export * from "./spend.ts";
+export * from "./tx-size.ts";
+export * from "./types.ts";
+export * from "./vault-policy.ts";
+export * from "./vaultContractUtil.ts";
+export * from "./xpub.ts";

package/dist/btc/vault/index.js

@@ -0,0 +1,21 @@
+/**
+ * A Bitcoin vault's taproot tree, built from its definition: the members'
+ * account xpubs, the template, the threshold, the participant ordering and the
+ * NUMS recipe. The app builds and reconstructs vaults with this code
+ * (`apps/cofund/src/lib/bitcoin_scriptpath/creation` re-exports it), and the
+ * SDK rebuilds a vault to check its address before signing for it.
+ */
+export * from "./bip341-nums.js";
+export * from "./build.js";
+export * from "./canonical-order.js";
+export * from "./from-contract-id.js";
+export * from "./helpers.js";
+export * from "./limits.js";
+export * from "./participant-order.js";
+export * from "./script.js";
+export * from "./spend.js";
+export * from "./tx-size.js";
+export * from "./types.js";
+export * from "./vault-policy.js";
+export * from "./vaultContractUtil.js";
+export * from "./xpub.js";

package/dist/btc/vault/limits.d.ts

@@ -0,0 +1,9 @@
+/** Ledger Bitcoin app wallet-policy limit for supported hardware signers. */
+export declare const LEDGER_MAX_POLICY_KEYS = 15;
+/**
+ * One Ledger wallet-policy key is the NUMS-backed Taproot internal key, leaving
+ * fourteen slots for participant account xpubs. Cofund applies this as a
+ * universal product limit so every vault it creates remains Ledger-compatible
+ * at the key-count layer, regardless of the currently selected signer types.
+ */
+export declare const BTC_VAULT_MAX_PARTICIPANTS: number;

package/dist/btc/vault/limits.js

@@ -0,0 +1,9 @@
+/** Ledger Bitcoin app wallet-policy limit for supported hardware signers. */
+export const LEDGER_MAX_POLICY_KEYS = 15;
+/**
+ * One Ledger wallet-policy key is the NUMS-backed Taproot internal key, leaving
+ * fourteen slots for participant account xpubs. Cofund applies this as a
+ * universal product limit so every vault it creates remains Ledger-compatible
+ * at the key-count layer, regardless of the currently selected signer types.
+ */
+export const BTC_VAULT_MAX_PARTICIPANTS = LEDGER_MAX_POLICY_KEYS - 1;

package/dist/btc/vault/participant-order.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Canonical participant ordering for account-based BTC vaults.
+ *
+ * A vault's taproot address is not stored anywhere — `Vault.contractId` holds
+ * only the roster (xpubs + roles), and every read path re-derives the address
+ * from it. Participant order decides the order of pushed keys inside the
+ * `CHECKSIGADD` tapscript, and for ADMINS_REQUIRED it also decides which admin
+ * owns which derivation branch (`2 * leafIdx`). So the comparator used to order
+ * the roster is part of the address: change it and a live vault silently
+ * repoints at an address nobody funded.
+ *
+ * That makes `String.prototype.localeCompare` unusable here, which is what this
+ * module replaces. With no explicit locale it resolves the runtime's default
+ * collation — the browser's UI language on the client, `LANG`/`LC_ALL` (or ICU's
+ * `en-US` fallback) on the server. Base58 is mixed-case alphanumeric, and
+ * several CLDR tailorings reorder plain ASCII:
+ *
+ *   - `cs` treats `ch` as one letter sorting after `h`, so `ch…` > `d…`
+ *   - `da` / `nb` fold `aa` to `å`, which sorts after `z`
+ *   - `et` reorders `z` before `t`…`w`; `lt` reorders `y`; `hu` has digraphs
+ *
+ * Measured against a corpus of realistic `tpub…` strings, `lt` disagrees with
+ * `en` on ~3.5% of pairs and `et` on ~1.5%. A vault created by the server and
+ * displayed to a Czech-locale browser therefore rendered two different valid
+ * bech32m addresses for one `contractId`.
+ *
+ * Both orderings below are pure, total and frozen. Neither consults ICU, so
+ * they return the same result in every runtime, browser locale and ICU version.
+ */
+/**
+ * Ordering rule a vault's address was derived under.
+ *
+ * Persisted in the `contractId` so a vault always re-derives under the rule it
+ * was created with. An absent field means {@link ORDERING_ICU_EN_V1} — every
+ * vault created before this field existed was ordered by `localeCompare`.
+ */
+export declare const ORDERING_ICU_EN_V1 = "icu-en-v1";
+/** Ordering rule for vaults created from now on. */
+export declare const ORDERING_XPUB_CODEPOINT_V2 = "role-then-xpub-codepoint-v2";
+export type ParticipantOrdering = typeof ORDERING_ICU_EN_V1 | typeof ORDERING_XPUB_CODEPOINT_V2;
+/** The rule new vaults are created under. */
+export declare const CURRENT_PARTICIPANT_ORDERING: ParticipantOrdering;
+/**
+ * Read the ordering rule off a deserialized contract.
+ *
+ * Fails OPEN to v1 rather than throwing: an unrecognised value can only come
+ * from a contract written by a newer revision, and v1 is what every vault
+ * predating the field used. Callers that must not guess should compare the
+ * derived address against a known-good one instead.
+ */
+export declare function participantOrderingOf(value: string | undefined): ParticipantOrdering;
+/**
+ * The ordering that `localeCompare()` produced for Base58 strings on an
+ * `en`-family runtime — the rule every pre-v2 vault address was built under.
+ *
+ * Exists ONLY so those vaults keep re-deriving the address their UTXOs are
+ * locked to. Do not use it for anything new; new vaults use
+ * {@link compareCodepoint} via {@link ORDERING_XPUB_CODEPOINT_V2}.
+ *
+ * Verified equal to `Intl.Collator` for `en-US`, `en-GB`, `de-DE`, `fr-FR`,
+ * `ja-JP`, `zh-CN`, `ar-EG`, `he-IL`, `ru-RU`, `el-GR` and `hi-IN` across
+ * exhaustive two-character Base58 pairs and randomised full-length `tpub`
+ * corpora — see `participant-order.test.ts`. Those locales all inherit root
+ * collation for ASCII; the tailorings that diverge (`cs`, `da`, `nb`, `et`,
+ * `lt`, `hu`) are the bug this replaces, not behaviour to reproduce.
+ */
+export declare function compareBase58IcuEnV1(a: string, b: string): number;
+/** The xpub comparator for a given ordering rule. */
+export declare function xpubComparatorFor(ordering: ParticipantOrdering): (a: string, b: string) => number;