@usesigil/kit 0.15.0 → 0.17.0

package/dist/build-unsigned.js

@@ -0,0 +1,152 @@
+/**
+ * S21 — `buildUnsigned()` composer.
+ *
+ * Public composer that wraps {@link buildOwnerTransaction} to give SDK
+ * consumers an offline-signing path. The only structural difference from
+ * `buildOwnerTransaction` is that `feePayer` is a plain {@link Address}, not
+ * a {@link TransactionSigner}; this composer wraps it in `createNoopSigner`
+ * internally so the caller never needs to construct a signer object.
+ *
+ * # Three use cases
+ *
+ *  1. **Squads multisig.** The caller submits the returned `unsignedTxBytes`
+ *     buffer to a Squads proposal; signers from the multisig sign
+ *     asynchronously, then the assembled signed tx is broadcast.
+ *
+ *  2. **CLI tools.** The caller pipes the `unsignedTxBytes` buffer to
+ *     `solana sign-tx` (or any cold-key signing tool) for offline signing.
+ *
+ *  3. **Cost preview.** The caller decodes `unsignedTxBytes` client-side via
+ *     {@link getCompiledTransactionMessageDecoder} to estimate CU + fee
+ *     before submission. Pass `simulate: true` to additionally fetch the
+ *     RPC's `unitsConsumed` estimate via `simulateTransaction`.
+ *
+ * # Why a separate function instead of `buildOwnerTransaction`?
+ *
+ * `buildOwnerTransaction` requires a {@link TransactionSigner} for the
+ * `owner` field. Callers without a wired-up signer (e.g. a CLI receiving
+ * just a pubkey via flag, or a Squads-flow UI that never holds the key) had
+ * to construct a `createNoopSigner(addr)` themselves AND know the function
+ * returns a `wireBase64` string they then have to base64-decode. This
+ * composer hands back a `Uint8Array` directly + a structured object with
+ * the original {@link Instruction}[] for inspection, in one call.
+ *
+ * The unsigned bytes have the standard Solana wire layout:
+ *   `[num_sigs:u8][signatures:64*num_sigs][messageBytes]`
+ * where every signature slot is zero-filled (caller hasn't signed yet).
+ */
+import { createNoopSigner, getCompiledTransactionMessageDecoder, } from "./kit-adapter.js";
+import { buildOwnerTransaction } from "./owner-transaction.js";
+// ─── buildUnsigned ──────────────────────────────────────────────────────────
+/**
+ * Build an unsigned versioned transaction for offline signing.
+ *
+ * @see {@link BuildUnsignedInput} for input fields.
+ * @see {@link BuildUnsignedResult} for the returned shape and the three use
+ *      cases this composer was added for (Squads, CLI, cost preview).
+ *
+ * @example Squads multisig
+ * ```ts
+ * const { unsignedTxBytes } = await buildUnsigned({
+ *   rpc, feePayer: squad.address, instructions: [transferIx],
+ * });
+ * await squads.createProposal({ transaction: unsignedTxBytes });
+ * ```
+ *
+ * @example CLI cold-key signing
+ * ```ts
+ * const { unsignedTxBytes } = await buildUnsigned({ rpc, feePayer, instructions });
+ * await fs.writeFile("tx.bin", unsignedTxBytes);
+ * // then: solana sign-tx tx.bin
+ * ```
+ *
+ * @example Cost preview with on-chain simulation
+ * ```ts
+ * const { estimatedComputeUnits, message } = await buildUnsigned({
+ *   rpc, feePayer, instructions, simulate: true,
+ * });
+ * console.log(`Estimated CU: ${estimatedComputeUnits}`);
+ * console.log(`Static accounts: ${message.staticAccounts.length}`);
+ * ```
+ */
+export async function buildUnsigned(input) {
+    const ownerSigner = createNoopSigner(input.feePayer);
+    const ownerTx = await buildOwnerTransaction({
+        rpc: input.rpc,
+        owner: ownerSigner,
+        instructions: input.instructions,
+        network: input.network ?? "devnet",
+        ...(input.computeUnitLimit !== undefined
+            ? { computeUnits: input.computeUnitLimit }
+            : {}),
+        ...(input.computeUnitPrice !== undefined
+            ? { priorityFeeMicroLamports: input.computeUnitPrice }
+            : {}),
+        ...(input.addressLookupTables !== undefined
+            ? { addressLookupTables: input.addressLookupTables }
+            : {}),
+        ...(input.blockhash !== undefined ? { blockhash: input.blockhash } : {}),
+    });
+    const unsignedTxBytes = base64ToUint8Array(ownerTx.wireBase64);
+    // Decode the compiled message portion for inspection.
+    // Wire layout: [num_sigs:u8][signatures:64*num_sigs][messageBytes].
+    // Versioned-tx with this composer always has exactly 1 required signer
+    // (the fee payer), so the message starts at offset 65 — but read
+    // num_sigs defensively in case future changes add co-signers.
+    const numSigs = unsignedTxBytes[0] ?? 0;
+    const messageBytes = unsignedTxBytes.slice(1 + 64 * numSigs);
+    const message = getCompiledTransactionMessageDecoder().decode(messageBytes);
+    let estimatedComputeUnits;
+    if (input.simulate) {
+        estimatedComputeUnits = await safeSimulateUnitsConsumed(input.rpc, ownerTx.wireBase64);
+    }
+    return {
+        unsignedTxBytes,
+        instructions: input.instructions,
+        ...(estimatedComputeUnits !== undefined ? { estimatedComputeUnits } : {}),
+        feePayer: input.feePayer,
+        recentBlockhash: ownerTx.blockhash.blockhash,
+        lastValidBlockHeight: ownerTx.blockhash.lastValidBlockHeight,
+        message,
+    };
+}
+// ─── Internal helpers ───────────────────────────────────────────────────────
+/**
+ * Decode base64 → Uint8Array via `atob` (built-in Node ≥ 16 + browser).
+ * Same pattern as `preview-create-vault.ts` — kept private here to avoid
+ * a cross-file dependency on a private helper.
+ */
+function base64ToUint8Array(b64) {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+/**
+ * Run `simulateTransaction` and return `unitsConsumed` as a number.
+ * Best-effort — any failure (RPC error, missing `unitsConsumed`, sim error)
+ * returns `undefined` so the caller still gets the unsigned bytes. The
+ * simulate flag is for cost preview, not for blocking the build.
+ */
+async function safeSimulateUnitsConsumed(rpc, wireBase64) {
+    try {
+        const result = await rpc
+            .simulateTransaction(wireBase64, {
+            encoding: "base64",
+            replaceRecentBlockhash: true,
+            sigVerify: false,
+            commitment: "confirmed",
+        })
+            .send();
+        const value = result.value;
+        if (!value || value.err || value.unitsConsumed == null)
+            return undefined;
+        return Number(value.unitsConsumed);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=build-unsigned.js.map

package/dist/build-unsigned.js.map

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

package/dist/caip2-network.d.ts

@@ -0,0 +1,171 @@
+/**
+ * CAIP-2 Solana chain identifiers + AL4 isMainnet derivation.
+ * Phase 9 Batch J (ISC-77..80, 147).
+ *
+ * Per the CAIP-2 spec (https://chainagnostic.org/CAIPs/caip-2), Solana
+ * networks are identified by a `solana:<genesis-hash-prefix>` string. The
+ * canonical IDs are registered at
+ * https://github.com/ChainAgnostic/namespaces/blob/main/solana/caip2.md.
+ *
+ * Sigil SDK V2 ships AL4 as a CAIP-2 chain id PLUS a derived `isMainnet`
+ * boolean. Per Council ISC-147, exposing the full CAIP-2 string (not just
+ * the boolean) preserves the future ability to bind testnet / localnet
+ * intents without changing the SealResult shape — collapsing 4 networks
+ * into 2 was flagged as a "footgun in waiting".
+ */
+/** CAIP-2 namespace for Solana. */
+export declare const CAIP2_NAMESPACE_SOLANA: "solana";
+/** Mainnet-beta CAIP-2 chain id. */
+export declare const CAIP2_SOLANA_MAINNET: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+/** Devnet CAIP-2 chain id. */
+export declare const CAIP2_SOLANA_DEVNET: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+/** Testnet CAIP-2 chain id (declared for completeness; not currently produced by `toCaip2`). */
+export declare const CAIP2_SOLANA_TESTNET: "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z";
+/**
+ * The set of CAIP-2 strings the SDK currently emits. The narrower string
+ * literal type prevents callers from constructing ad-hoc strings.
+ */
+export type SigilCaip2Chain = typeof CAIP2_SOLANA_MAINNET | typeof CAIP2_SOLANA_DEVNET;
+/**
+ * Convert the SDK's internal `"devnet" | "mainnet"` network discriminant
+ * to its canonical CAIP-2 chain id.
+ *
+ * @throws if `network` is not one of the two supported values. (Type
+ * narrowing prevents this at compile time; the runtime check catches
+ * misuse from JS callers or `any`-cast bypasses.)
+ */
+export declare function toCaip2(network: "devnet" | "mainnet"): SigilCaip2Chain;
+/**
+ * Derive the AL4 `isMainnet` boolean from a CAIP-2 chain id.
+ *
+ * `isMainnet === true` ONLY when the chain id matches the canonical
+ * mainnet-beta value. Devnet, testnet, localnet — anything else — all
+ * return false. This is intentional: `isMainnet` is a SECURITY signal
+ * (gate destructive defaults behind it); fuzzy matching would be a
+ * footgun.
+ */
+export declare function isMainnetCaip2(chain: string): boolean;
+/**
+ * Convenience: combine `toCaip2` + `isMainnetCaip2` from a `"devnet" | "mainnet"`
+ * input. Used by `seal()` to populate `SealResult.network` and
+ * `SealResult.isMainnet` in a single call.
+ */
+export declare function deriveNetworkIdentity(network: "devnet" | "mainnet"): {
+    network: SigilCaip2Chain;
+    isMainnet: boolean;
+};
+/**
+ * Convert a Sigil CAIP-2 string to a Wallet Standard chain identifier.
+ *
+ * Wallet Standard (https://github.com/wallet-standard/wallet-standard) uses
+ * `solana:<network-id>` per the SIWS / Solana Mobile spec, which is the
+ * exact same shape as Sigil's CAIP-2 strings (per the ChainAgnostic CAIP-2
+ * registry — https://chainagnostic.org/CAIPs/caip-2). The conversion is
+ * therefore identity at the value level — but the explicit helper
+ * documents the boundary so that future wallet-standard surface changes
+ * (e.g. an extra cluster discriminant, a versioning suffix) localize to
+ * this one function rather than spreading raw CAIP-2 casts across SIWS,
+ * connector adapters, and the seal() result shape.
+ *
+ * The return type is the wider template-literal `\`solana:${string}\`` to
+ * keep the helper assignable to Wallet Standard `IdentifierString` /
+ * `WalletWithSolanaFeatures` chain fields without consumers needing to
+ * narrow back through `SigilCaip2Chain`.
+ *
+ * @param caip2 — a CAIP-2 chain id produced by {@link toCaip2} or one of
+ *   the `CAIP2_SOLANA_*` constants. The argument MUST already be in the
+ *   `solana:<id>` form; this helper does not validate.
+ */
+export declare function toWalletStandardChain(caip2: SigilCaip2Chain): `solana:${string}`;
+/**
+ * Network discriminant the SDK accepts as a `"devnet" | "mainnet"`
+ * string. Re-exported here so consumers of `verifyNetworkIdentity` don't
+ * need a separate import.
+ */
+export type SigilNetwork = "devnet" | "mainnet";
+/**
+ * Canonical Solana genesis hashes, keyed by network. Values are the full
+ * 44-character base58 hashes returned by `rpc.getGenesisHash()`.
+ *
+ *   mainnet-beta: 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d
+ *   devnet:       EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG
+ *   testnet:      4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY
+ *
+ * Source: Solana Foundation Cluster RPC documentation
+ * (https://solana.com/docs/core/clusters). Hardcoded here so the
+ * verification path is offline-deterministic — a malicious RPC cannot
+ * substitute its own "canonical" hash.
+ */
+export declare const SOLANA_GENESIS_HASHES: {
+    readonly mainnet: "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d";
+    readonly devnet: "EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG";
+    readonly testnet: "4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY";
+};
+/** The set of networks `verifyNetworkIdentity` can report as `actualNetwork`. */
+export type SigilActualNetwork = keyof typeof SOLANA_GENESIS_HASHES | "unknown";
+/**
+ * Minimal RPC shape consumed by {@link verifyNetworkIdentity}. Matches
+ * the `@solana/kit` RPC contract so callers can pass the same `rpc`
+ * object they already use elsewhere in the SDK.
+ */
+export interface GenesisRpc {
+    getGenesisHash(): {
+        send(): Promise<string>;
+    };
+}
+/** Structured result returned by {@link verifyNetworkIdentity}. */
+export interface NetworkIdentityResult {
+    /** `true` iff the RPC's reported genesis matches the caller's `claimedNetwork`. */
+    verified: boolean;
+    /**
+     * The network the RPC actually serves, derived from `getGenesisHash()`.
+     * `"unknown"` indicates the RPC returned a hash that doesn't match any
+     * canonical cluster (likely a Surfpool/LiteSVM local validator).
+     */
+    actualNetwork: SigilActualNetwork;
+    /**
+     * Optional human-readable explanation. Populated when `verified === false`
+     * (mismatch) OR when `getGenesisHash()` errored / returned malformed data.
+     */
+    reason?: string;
+    /** The raw hash observed from the RPC (for diagnostic logging). */
+    observedGenesisHash?: string;
+    /** The hash the SDK expected for `claimedNetwork`. */
+    expectedGenesisHash: string;
+}
+/**
+ * Verify that an RPC actually serves the cluster a caller claims it does.
+ *
+ * **Opt-in, non-throwing diagnostic.** Unlike `assertGenesisHash` in
+ * seal.ts (which is called inside `createSigilClientAsync` and throws on
+ * mismatch), this helper returns a structured result so callers can
+ * branch on it without `try/catch`. Use it in preflight checks, in
+ * `mainnetConfirmed` confirmation flows that want to surface the
+ * mismatch to the operator, or anywhere raw-tx-building code paths
+ * bypass the client factory.
+ *
+ * **Does NOT change `seal()` default behaviour.** The existing seal
+ * factory still calls `assertGenesisHash` (which throws) — that's the
+ * load-bearing safety gate. `verifyNetworkIdentity` is purely additive.
+ *
+ * @example
+ * ```ts
+ * const result = await verifyNetworkIdentity({
+ *   rpc,
+ *   claimedNetwork: "mainnet",
+ * });
+ * if (!result.verified) {
+ *   console.error(
+ *     `Refusing to submit mainnet tx — RPC reports ${result.actualNetwork} ` +
+ *     `(genesis ${result.observedGenesisHash}); ` +
+ *     `expected mainnet (${result.expectedGenesisHash}).`,
+ *   );
+ *   throw new Error("Network mismatch");
+ * }
+ * ```
+ */
+export declare function verifyNetworkIdentity(input: {
+    rpc: GenesisRpc;
+    claimedNetwork: SigilNetwork;
+}): Promise<NetworkIdentityResult>;
+//# sourceMappingURL=caip2-network.d.ts.map

package/dist/caip2-network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caip2-network.d.ts","sourceRoot":"","sources":["../src/caip2-network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,mCAAmC;AACnC,eAAO,MAAM,sBAAsB,EAAG,QAAiB,CAAC;AAExD,oCAAoC;AACpC,eAAO,MAAM,oBAAoB,EAC/B,yCAAkD,CAAC;AAErD,8BAA8B;AAC9B,eAAO,MAAM,mBAAmB,EAC9B,yCAAkD,CAAC;AAErD,gGAAgG;AAChG,eAAO,MAAM,oBAAoB,EAC/B,yCAAkD,CAAC;AAErD;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB,OAAO,oBAAoB,GAC3B,OAAO,mBAAmB,CAAC;AAE/B;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,QAAQ,GAAG,SAAS,GAAG,eAAe,CAatE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,QAAQ,GAAG,SAAS,GAAG;IACpE,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB,CAGA;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,eAAe,GACrB,UAAU,MAAM,EAAE,CAEpB;AAmBD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB;;;;CAIxB,CAAC;AAEX,iFAAiF;AACjF,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,qBAAqB,GAAG,SAAS,CAAC;AAEhF;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,cAAc,IAAI;QAAE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;CAC/C;AAED,mEAAmE;AACnE,MAAM,WAAW,qBAAqB;IACpC,mFAAmF;IACnF,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,aAAa,EAAE,kBAAkB,CAAC;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE;IACjD,GAAG,EAAE,UAAU,CAAC;IAChB,cAAc,EAAE,YAAY,CAAC;CAC9B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAoEjC"}

package/dist/caip2-network.js

@@ -0,0 +1,202 @@
+/**
+ * CAIP-2 Solana chain identifiers + AL4 isMainnet derivation.
+ * Phase 9 Batch J (ISC-77..80, 147).
+ *
+ * Per the CAIP-2 spec (https://chainagnostic.org/CAIPs/caip-2), Solana
+ * networks are identified by a `solana:<genesis-hash-prefix>` string. The
+ * canonical IDs are registered at
+ * https://github.com/ChainAgnostic/namespaces/blob/main/solana/caip2.md.
+ *
+ * Sigil SDK V2 ships AL4 as a CAIP-2 chain id PLUS a derived `isMainnet`
+ * boolean. Per Council ISC-147, exposing the full CAIP-2 string (not just
+ * the boolean) preserves the future ability to bind testnet / localnet
+ * intents without changing the SealResult shape — collapsing 4 networks
+ * into 2 was flagged as a "footgun in waiting".
+ */
+import { SigilSdkDomainError } from "./errors/sdk.js";
+import { SIGIL_ERROR__SDK__INVALID_NETWORK } from "./errors/codes.js";
+/** CAIP-2 namespace for Solana. */
+export const CAIP2_NAMESPACE_SOLANA = "solana";
+/** Mainnet-beta CAIP-2 chain id. */
+export const CAIP2_SOLANA_MAINNET = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+/** Devnet CAIP-2 chain id. */
+export const CAIP2_SOLANA_DEVNET = "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+/** Testnet CAIP-2 chain id (declared for completeness; not currently produced by `toCaip2`). */
+export const CAIP2_SOLANA_TESTNET = "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z";
+/**
+ * Convert the SDK's internal `"devnet" | "mainnet"` network discriminant
+ * to its canonical CAIP-2 chain id.
+ *
+ * @throws if `network` is not one of the two supported values. (Type
+ * narrowing prevents this at compile time; the runtime check catches
+ * misuse from JS callers or `any`-cast bypasses.)
+ */
+export function toCaip2(network) {
+    if (network === "mainnet")
+        return CAIP2_SOLANA_MAINNET;
+    if (network === "devnet")
+        return CAIP2_SOLANA_DEVNET;
+    throw new SigilSdkDomainError(SIGIL_ERROR__SDK__INVALID_NETWORK, `toCaip2: network must be 'devnet' or 'mainnet', got ${String(network)}`, {
+        context: {
+            operation: "toCaip2",
+            received: String(network),
+        },
+    });
+}
+/**
+ * Derive the AL4 `isMainnet` boolean from a CAIP-2 chain id.
+ *
+ * `isMainnet === true` ONLY when the chain id matches the canonical
+ * mainnet-beta value. Devnet, testnet, localnet — anything else — all
+ * return false. This is intentional: `isMainnet` is a SECURITY signal
+ * (gate destructive defaults behind it); fuzzy matching would be a
+ * footgun.
+ */
+export function isMainnetCaip2(chain) {
+    return chain === CAIP2_SOLANA_MAINNET;
+}
+/**
+ * Convenience: combine `toCaip2` + `isMainnetCaip2` from a `"devnet" | "mainnet"`
+ * input. Used by `seal()` to populate `SealResult.network` and
+ * `SealResult.isMainnet` in a single call.
+ */
+export function deriveNetworkIdentity(network) {
+    const chain = toCaip2(network);
+    return { network: chain, isMainnet: isMainnetCaip2(chain) };
+}
+/**
+ * Convert a Sigil CAIP-2 string to a Wallet Standard chain identifier.
+ *
+ * Wallet Standard (https://github.com/wallet-standard/wallet-standard) uses
+ * `solana:<network-id>` per the SIWS / Solana Mobile spec, which is the
+ * exact same shape as Sigil's CAIP-2 strings (per the ChainAgnostic CAIP-2
+ * registry — https://chainagnostic.org/CAIPs/caip-2). The conversion is
+ * therefore identity at the value level — but the explicit helper
+ * documents the boundary so that future wallet-standard surface changes
+ * (e.g. an extra cluster discriminant, a versioning suffix) localize to
+ * this one function rather than spreading raw CAIP-2 casts across SIWS,
+ * connector adapters, and the seal() result shape.
+ *
+ * The return type is the wider template-literal `\`solana:${string}\`` to
+ * keep the helper assignable to Wallet Standard `IdentifierString` /
+ * `WalletWithSolanaFeatures` chain fields without consumers needing to
+ * narrow back through `SigilCaip2Chain`.
+ *
+ * @param caip2 — a CAIP-2 chain id produced by {@link toCaip2} or one of
+ *   the `CAIP2_SOLANA_*` constants. The argument MUST already be in the
+ *   `solana:<id>` form; this helper does not validate.
+ */
+export function toWalletStandardChain(caip2) {
+    return caip2;
+}
+/**
+ * Canonical Solana genesis hashes, keyed by network. Values are the full
+ * 44-character base58 hashes returned by `rpc.getGenesisHash()`.
+ *
+ *   mainnet-beta: 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d
+ *   devnet:       EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG
+ *   testnet:      4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY
+ *
+ * Source: Solana Foundation Cluster RPC documentation
+ * (https://solana.com/docs/core/clusters). Hardcoded here so the
+ * verification path is offline-deterministic — a malicious RPC cannot
+ * substitute its own "canonical" hash.
+ */
+export const SOLANA_GENESIS_HASHES = {
+    mainnet: "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d",
+    devnet: "EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG",
+    testnet: "4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY",
+};
+/**
+ * Verify that an RPC actually serves the cluster a caller claims it does.
+ *
+ * **Opt-in, non-throwing diagnostic.** Unlike `assertGenesisHash` in
+ * seal.ts (which is called inside `createSigilClientAsync` and throws on
+ * mismatch), this helper returns a structured result so callers can
+ * branch on it without `try/catch`. Use it in preflight checks, in
+ * `mainnetConfirmed` confirmation flows that want to surface the
+ * mismatch to the operator, or anywhere raw-tx-building code paths
+ * bypass the client factory.
+ *
+ * **Does NOT change `seal()` default behaviour.** The existing seal
+ * factory still calls `assertGenesisHash` (which throws) — that's the
+ * load-bearing safety gate. `verifyNetworkIdentity` is purely additive.
+ *
+ * @example
+ * ```ts
+ * const result = await verifyNetworkIdentity({
+ *   rpc,
+ *   claimedNetwork: "mainnet",
+ * });
+ * if (!result.verified) {
+ *   console.error(
+ *     `Refusing to submit mainnet tx — RPC reports ${result.actualNetwork} ` +
+ *     `(genesis ${result.observedGenesisHash}); ` +
+ *     `expected mainnet (${result.expectedGenesisHash}).`,
+ *   );
+ *   throw new Error("Network mismatch");
+ * }
+ * ```
+ */
+export async function verifyNetworkIdentity(input) {
+    const { rpc, claimedNetwork } = input;
+    if (claimedNetwork !== "devnet" && claimedNetwork !== "mainnet") {
+        // Defensive: JS callers or `any`-cast bypasses. Returned as
+        // unverified rather than throwing so the helper stays "diagnostic".
+        return {
+            verified: false,
+            actualNetwork: "unknown",
+            expectedGenesisHash: "",
+            reason: `claimedNetwork must be 'devnet' or 'mainnet', got ${String(claimedNetwork)}`,
+        };
+    }
+    const expectedGenesisHash = claimedNetwork === "mainnet"
+        ? SOLANA_GENESIS_HASHES.mainnet
+        : SOLANA_GENESIS_HASHES.devnet;
+    let observed;
+    try {
+        observed = await rpc.getGenesisHash().send();
+    }
+    catch (err) {
+        return {
+            verified: false,
+            actualNetwork: "unknown",
+            expectedGenesisHash,
+            reason: `getGenesisHash() failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (typeof observed !== "string" || observed.length < 32) {
+        return {
+            verified: false,
+            actualNetwork: "unknown",
+            expectedGenesisHash,
+            observedGenesisHash: observed == null ? undefined : String(observed),
+            reason: "getGenesisHash() returned a malformed response — expected a 44-char base58 string",
+        };
+    }
+    // Identify the actual cluster the RPC serves.
+    let actualNetwork = "unknown";
+    for (const [name, hash] of Object.entries(SOLANA_GENESIS_HASHES)) {
+        if (observed === hash) {
+            actualNetwork = name;
+            break;
+        }
+    }
+    if (observed === expectedGenesisHash) {
+        return {
+            verified: true,
+            actualNetwork,
+            expectedGenesisHash,
+            observedGenesisHash: observed,
+        };
+    }
+    return {
+        verified: false,
+        actualNetwork,
+        expectedGenesisHash,
+        observedGenesisHash: observed,
+        reason: `Cluster mismatch — RPC reports ${actualNetwork} (genesis ${observed}) ` +
+            `but caller claimed ${claimedNetwork} (expected ${expectedGenesisHash}).`,
+    };
+}
+//# sourceMappingURL=caip2-network.js.map

package/dist/caip2-network.js.map

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

package/dist/canonical-encode.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Canonical Borsh-style encoder primitives — shared utilities.
+ *
+ * APPEND-ONLY DISCIPLINE. The TA-19 policy preview digest
+ * (`policy/compute-policy-preview-digest.ts`) and the AL3 SealInput intent
+ * digest (`seal/intent-digest.ts`, Phase 9 Batch I) both depend on these
+ * primitives being byte-stable across SDK versions. Adding a new primitive
+ * is fine; CHANGING the byte layout of an existing one would break every
+ * downstream cross-impl Rust↔TS hash and silently invalidate every
+ * previously-signed policy preview digest.
+ *
+ * Mirrors the Rust-side conventions used by `solana_program::hash::hash`
+ * over Borsh-encoded structs:
+ *   - Little-endian for all multi-byte integers (u16/u32/u64).
+ *   - Vec<T> = u32 LE length prefix ++ flat element bytes (no per-element
+ *     framing).
+ *   - bool encoded as u8 (0 or 1; the canonical Borsh wire format).
+ *   - Pubkey = raw 32 bytes (base58 decoded).
+ *   - SHA-256 over the canonical-encoded byte string.
+ *
+ * Primitives are deliberately small, stateless, and side-effect-free so
+ * they can be unit-tested in isolation and reused without surprises.
+ */
+/**
+ * Decode a Solana base58 pubkey to its 32-byte raw form. Throws on any
+ * input that doesn't decode to exactly 32 bytes (catches malformed
+ * pubkeys before they corrupt the canonical encoding).
+ *
+ * @throws Error if `s` is empty, contains an invalid base58 character,
+ *   or decodes to a byte length other than 32.
+ */
+export declare function base58Decode32(s: string): Uint8Array;
+/** Write u8 (single byte). Returns new offset. */
+export declare function writeU8(view: DataView, offset: number, v: number): number;
+/** Write u16 little-endian. Returns new offset. */
+export declare function writeU16Le(view: DataView, offset: number, v: number): number;
+/** Write u32 little-endian. Returns new offset. */
+export declare function writeU32Le(view: DataView, offset: number, v: number): number;
+/** Write u64 little-endian. Returns new offset. */
+export declare function writeU64Le(view: DataView, offset: number, v: bigint): number;
+/** Write a bool as a single 0/1 byte. Returns new offset. */
+export declare function writeBool(view: DataView, offset: number, v: boolean): number;
+/**
+ * SHA-256 over the input bytes. Backed by `@noble/hashes/sha256` — pure
+ * JS, browser- and Bun-compatible, byte-identical to Node's `node:crypto`
+ * for the same input (TA-19 cross-impl fixture suite verifies this).
+ *
+ * Phase 9 Batch I switched the backend from `node:crypto` to noble so AL3
+ * intent-digest can ship the same primitive across Node, Bun, and the
+ * browser without runtime-conditional imports.
+ */
+export declare function sha256(input: Uint8Array): Uint8Array;
+/**
+ * Constant-time digest comparison (true if `a` and `b` are byte-equal).
+ * Uses XOR-accumulate with no early exit so timing leaks don't reveal
+ * which prefix matched. Used by cosign + policy-digest verification.
+ */
+export declare function digestsEqual(a: Uint8Array, b: Uint8Array): boolean;
+//# sourceMappingURL=canonical-encode.d.ts.map

package/dist/canonical-encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-encode.d.ts","sourceRoot":"","sources":["../src/canonical-encode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAqBH;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAsCpD;AAQD,kDAAkD;AAClD,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED,mDAAmD;AACnD,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG5E;AAED,mDAAmD;AACnD,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG5E;AAED,mDAAmD;AACnD,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG5E;AAED,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,GAAG,MAAM,CAG5E;AAID;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAOlE"}