@kaspacom/kcc20-tx-builder 0.2.5 → 0.4.0

package/examples/vendor/kaspa/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "kaspa-wasm",
+  "type": "module",
+  "collaborators": [
+    "Kaspa developers"
+  ],
+  "description": "KASPA WASM bindings",
+  "version": "1.1.1-toc.1",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kaspanet/rusty-kaspa"
+  },
+  "files": [
+    "kaspa_bg.wasm",
+    "kaspa.js",
+    "kaspa.d.ts"
+  ],
+  "main": "kaspa.js",
+  "types": "kaspa.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaspacom/kcc20-tx-builder",
-  "version": "0.2.5",
+  "version": "0.4.0",
   "description": "Runtime-independent KCC20 covenant transaction and PSKT construction primitives.",
   "license": "Apache-2.0",
   "author": "KaspaCom",
@@ -60,8 +60,22 @@
     "index.d.ts",
     "src",
     "artifacts",
+    "docs",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "RELEASING.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "examples/shared",
+    "examples/backend",
+    "examples/frontend/*.ts",
+    "examples/frontend/index.html",
+    "examples/vendor",
+    "examples/package.json",
+    "examples/package-lock.json",
+    "examples/tsconfig.json",
+    "examples/README.md",
+    "examples/test"
   ],
   "engines": {
     "node": ">=20"
@@ -72,8 +86,11 @@
   "scripts": {
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/write-cjs-package.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run typecheck && npm run build && node test/smoke.mjs && node test/cjs-smoke.cjs",
-    "prepack": "npm test"
+    "test": "npm run typecheck && npm run build && node test/smoke.mjs && node test/cjs-smoke.cjs && node test/snapshot-plan.mjs",
+    "prepack": "npm test",
+    "test:examples": "npm run verify:compatibility && node scripts/test-examples.mjs --browser",
+    "verify:compatibility": "node scripts/verify-compatibility.mjs",
+    "test:snapshot:transactions": "npm run build && node test/snapshot-transactions.mjs && node test/snapshot-claims.mjs"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

package/src/artifacts.ts

@@ -7,6 +7,8 @@ export const KCC20_CURRENT_NATIVE_ARTIFACT_KEY =
   "KCC20.placeholder.json" as const;
 
 export const KCC20_ARTIFACT_SCRIPT_SHA256 = Object.freeze({
+  "KCC20SnapshotBootstrap.placeholder.json": "85edea7401eb415c447e6a0d0a45e1667802a269dde9fbe33d5881c4a4de51e2",
+  "KCC20SnapshotController.placeholder.json": "8f90525afcc1c23240f1d18eed30b3b377a72a323e8b48925dfac53bd5aab0ae",
   [KCC20_CURRENT_NATIVE_ARTIFACT_KEY]:
     "4633b082f26adbf14600b767d6e2146e36ce67d63d8202c0281857922c05ac41",
   "KCC20FeeTicket.placeholder.json":
@@ -19,6 +21,39 @@ export const KCC20_ARTIFACT_SCRIPT_SHA256 = Object.freeze({
     "1b84d74aa01b6a50edbff5bf1f9e988a5a6a00ec645458dfd3912ac532b77c33",
 });
 
+/**
+ * Canonical raw artifact pins and structural metadata for signerless snapshot
+ * migrations. Consumers must use these values instead of maintaining their
+ * own copies; the raw SHA-256 pins cover the exact packaged JSON bytes.
+ */
+export const KCC20_SNAPSHOT_ARTIFACT_PINS = Object.freeze({
+  bootstrap: Object.freeze({
+    key: "KCC20SnapshotBootstrap.placeholder.json",
+    contractName: "KCC20SnapshotBootstrap",
+    artifactSha256:
+      "bc566a964b5feb1c2055d5130af25951142d695472287b888c5537e9a56ee3d2",
+    scriptLength: 33718,
+    stateStart: 1,
+    stateLength: 405,
+  }),
+  controller: Object.freeze({
+    key: "KCC20SnapshotController.placeholder.json",
+    contractName: "KCC20SnapshotController",
+    artifactSha256:
+      "f0d7b082e0680a90736948cd6658ccbc8600e097d9b4d5568013acdaafb39bf5",
+    scriptLength: 15297,
+    stateStart: 1,
+    stateLength: 432,
+  }),
+});
+
+/** Canonical KCC20 template committed by both snapshot contracts. */
+export const KCC20_SNAPSHOT_TOKEN_TEMPLATE_PIN = Object.freeze({
+  hash: "911f0638ccb7368bf36d117f1725073ae7ee487ce8b58ca3e8375051c2d40f6c",
+  prefixLength: 1,
+  suffixLength: 25439,
+});
+
 export type Kcc20ArtifactKey = keyof typeof KCC20_ARTIFACT_SCRIPT_SHA256;
 
 export function isKcc20ArtifactKey(value: string): value is Kcc20ArtifactKey {

package/src/engine.ts

@@ -62,6 +62,7 @@ import {
   ownerAuthorizationWitness,
 } from "./abi.js";
 import { KCC20_BUILDER_KEYS } from "./operations.js";
+import { createKcc20SnapshotPsktBuilder } from "./snapshot-operation.js";
 import { splitKcc20MintSupply } from "./protocol.js";
 import { buildKcc20DeployIntentOutputs } from "./deploy-receipt.js";
 import {
@@ -143,12 +144,9 @@ export function createKcc20PsktBuilderEngine(
       );
     }
   }
-  const kaspaWasm = new Proxy(options.wasm, {
-    get(target, property, receiver) {
-      if (property === "RpcClient") return InjectedRpcClient;
-      return Reflect.get(target, property, receiver);
-    },
-  });
+  // Bundlers can freeze module namespace exports. A Proxy cannot replace a
+  // non-configurable RpcClient property; copy the host exports before adapting it.
+  const kaspaWasm = { ...options.wasm, RpcClient: InjectedRpcClient };
 
   const INPUT_SCHEMA = "kcc20-in-process-pskt-builder-input/v1";
   const OUTPUT_SCHEMA = "kcc20-in-process-pskt-builder-output/v1";
@@ -156,7 +154,7 @@ export function createKcc20PsktBuilderEngine(
   const DEFAULT_PRIORITY_FEE = 10_000n;
   const DEFAULT_MATCHER_PRIORITY_FEE = 30_000_000n;
   const DEFAULT_WRAPPER_DEPLOY_PRIORITY_FEE = 10_000_000n;
-  const DEFAULT_WRPC_URL = "ws://65.108.107.30:17210";
+  const DEFAULT_WRPC_URL = "wss://tn10-node.kaspa.com/testnet-10";
   const MIN_FILL_GROSS_SOMPI = 50_000_000n;
   const MIN_RELAY_FEE_PER_MASS_SOMPI = 100n;
   const TOCCATA_COMPUTE_BUDGET_MASS_PER_UNIT = 100n;
@@ -221,7 +219,11 @@ export function createKcc20PsktBuilderEngine(
         .then((artifact) => {
           if (!artifact)
             throw new Error(`Missing supplied KCC20 artifact: ${path}`);
-          const normalized = normalizeSilverScriptArtifact(artifact);
+          const artifactValue =
+            artifact && typeof artifact === "object" && !Array.isArray(artifact)
+              ? (artifact.artifact ?? artifact)
+              : artifact;
+          const normalized = normalizeSilverScriptArtifact(artifactValue);
           assertKcc20ArtifactScriptHash(path, normalized);
           return normalized;
         })
@@ -487,6 +489,15 @@ export function createKcc20PsktBuilderEngine(
     return new kw.ScriptBuilder({ flags: { covenantsEnabled: true } });
   }
 
+  const buildSnapshotMigrationPskt = createKcc20SnapshotPsktBuilder({
+    wasm: options.wasm,
+    artifacts: options.artifacts,
+    artifactProvider: options.artifactProvider,
+    config: options.config,
+    sourceProvider: options.sourceProvider,
+    rpcClientFactory: options.rpcClientFactory,
+    transactionWithCalculatedFeeChange,
+  });
   const psktBuilderByKey = Object.freeze({
     "kcc20.deploy-token": buildKcc20DeployPskt,
     "kcc20.mint": buildKcc20MintPskt,
@@ -512,6 +523,10 @@ export function createKcc20PsktBuilderEngine(
     "kcc20orderbook.cancel-ask": buildWrappedCancelPskt,
     "kcc20orderbook.cancel-bid": buildWrappedCancelPskt,
     "kcc20orderbook.matcher-settle-crossed": buildWrappedCrossMatchPskt,
+    "kcc20-snapshot.deploy-bootstrap": buildSnapshotMigrationPskt,
+    "kcc20-snapshot.deploy-controller": buildSnapshotMigrationPskt,
+    "kcc20-snapshot.start": buildSnapshotMigrationPskt,
+    "kcc20-snapshot.claim": buildSnapshotMigrationPskt,
   });
   const missingBuilderKeys = KCC20_BUILDER_KEYS.filter(
     (builderKey) => !psktBuilderByKey[builderKey],
@@ -570,8 +585,7 @@ export function createKcc20PsktBuilderEngine(
       params.utilityTokenAmount,
       "utilityTokenAmount",
     );
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rootAddress = requireKaspaAddress(rootUtxo.address);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
@@ -792,8 +806,7 @@ export function createKcc20PsktBuilderEngine(
         "FeeTicket batch utility token amount must fit in an unsigned 64-bit integer",
       );
     }
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const tokenOutputSompi =
@@ -1148,8 +1161,7 @@ export function createKcc20PsktBuilderEngine(
       throw new Error("FeeTicket burn source outpoints must be unique");
     }
 
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const priorityFee = parseU64(
@@ -1376,8 +1388,7 @@ export function createKcc20PsktBuilderEngine(
       throw new Error("FeeTicket transfer source outpoints must be unique");
     }
 
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const priorityFee = parseU64(
@@ -2602,8 +2613,7 @@ export function createKcc20PsktBuilderEngine(
       "priceScale",
     );
     assertWrapperArtifactPriceScale(priceScale);
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const amountTkas = parseAmountTkas(
@@ -2915,8 +2925,7 @@ export function createKcc20PsktBuilderEngine(
       params.feeTicketId || ZERO_HASH,
       "fee ticket id",
     );
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const tokenOutputSompi = parseU64(
@@ -2925,8 +2934,7 @@ export function createKcc20PsktBuilderEngine(
       "tokenOutputSompi",
     );
     const priorityFee = parseU64(
-      env.KCC20_WRAP_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_WRAP_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const computeBudget = parsePositiveNumber(
@@ -3333,8 +3341,7 @@ export function createKcc20PsktBuilderEngine(
       "KCC20 recipient owner",
     );
     const tokenAmount = parsePositiveU64(params.tokenAmount, "tokenAmount");
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const tokenOutputSompi = parseU64(
@@ -3343,8 +3350,7 @@ export function createKcc20PsktBuilderEngine(
       "tokenOutputSompi",
     );
     const priorityFee = parseU64(
-      env.KCC20_UNWRAP_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_UNWRAP_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const computeBudget = parsePositiveNumber(
@@ -3824,8 +3830,7 @@ export function createKcc20PsktBuilderEngine(
     const expectedFeeTicketId = params.feeTicketId
       ? requireHex32(params.feeTicketId, "fee ticket id")
       : null;
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const tokenOutputSompi = parseU64(
@@ -3834,8 +3839,7 @@ export function createKcc20PsktBuilderEngine(
       "tokenOutputSompi",
     );
     const priorityFee = parseU64(
-      env.KCC20_ORDER_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_ORDER_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const computeBudget = parsePositiveNumber(
@@ -4182,8 +4186,7 @@ export function createKcc20PsktBuilderEngine(
       params.unitPriceSompi,
       "unitPriceSompi",
     );
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const tokenOutputSompi = parseU64(
@@ -4192,8 +4195,7 @@ export function createKcc20PsktBuilderEngine(
       "tokenOutputSompi",
     );
     const priorityFee = parseU64(
-      env.KCC20_FILL_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_FILL_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const computeBudget = parsePositiveNumber(
@@ -4605,8 +4607,7 @@ export function createKcc20PsktBuilderEngine(
       params.unitPriceSompi,
       "unitPriceSompi",
     );
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const tokenOutputSompi = parseU64(
@@ -4615,8 +4616,7 @@ export function createKcc20PsktBuilderEngine(
       "tokenOutputSompi",
     );
     const priorityFee = parseU64(
-      env.KCC20_FILL_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_FILL_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const computeBudget = parsePositiveNumber(
@@ -5197,8 +5197,7 @@ export function createKcc20PsktBuilderEngine(
       "wrapped market id",
     );
     const buyerOwner = requireHex32(request.owner?.kcc20Owner, "buyer owner");
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const tokenOutputSompi = parseU64(
@@ -5207,8 +5206,7 @@ export function createKcc20PsktBuilderEngine(
       "tokenOutputSompi",
     );
     const priorityFee = parseU64(
-      env.KCC20_FILL_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_FILL_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const wrappedArtifacts = await readWrappedArtifacts();
@@ -5746,8 +5744,7 @@ export function createKcc20PsktBuilderEngine(
       "wrapped market id",
     );
     const sellerOwner = requireHex32(request.owner?.kcc20Owner, "seller owner");
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const tokenOutputSompi = parseU64(
@@ -5756,8 +5753,7 @@ export function createKcc20PsktBuilderEngine(
       "tokenOutputSompi",
     );
     const priorityFee = parseU64(
-      env.KCC20_FILL_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_FILL_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const wrappedArtifacts = await readWrappedArtifacts();
@@ -6503,8 +6499,7 @@ export function createKcc20PsktBuilderEngine(
       "wrapped market id",
     );
     const sellerOwner = requireHex32(request.owner?.kcc20Owner, "seller owner");
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const configuredTokenOutputSompi = parseU64(
@@ -6513,8 +6508,7 @@ export function createKcc20PsktBuilderEngine(
       "tokenOutputSompi",
     );
     const priorityFee = parseU64(
-      env.KCC20_FILL_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_FILL_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const wrappedArtifacts = await readWrappedArtifacts();
@@ -7282,8 +7276,7 @@ export function createKcc20PsktBuilderEngine(
       "requested wrapped market id",
     );
     const owner = requireHex32(request.owner?.kcc20Owner, "token owner");
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const priorityFee = parseU64(
@@ -7582,8 +7575,7 @@ export function createKcc20PsktBuilderEngine(
       ? requireHex32(params.feeTicketId, "fee ticket id")
       : null;
     const maxFeeSompi = parseU64(params.maxFeeSompi || "0", "maxFeeSompi");
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const expectedOwner = request.owner?.kcc20Owner
       ? requireHex32(request.owner.kcc20Owner, "matcher owner")
@@ -7607,14 +7599,10 @@ export function createKcc20PsktBuilderEngine(
     );
     const transactionFeeReserve = priorityFee + networkFeeReserve;
     const computeBudget = parsePositiveNumber(
-      env.KCC20_MATCHER_COMPUTE_BUDGET ||
-        env.KCC20_FILL_COMPUTE_BUDGET ||
-        800,
+      env.KCC20_MATCHER_COMPUTE_BUDGET || env.KCC20_FILL_COMPUTE_BUDGET || 800,
       "computeBudget",
     );
-    const privateKeyHex = String(
-      env.KCC20_WRAPPER_OPERATOR_PRIVATE_KEY || "",
-    )
+    const privateKeyHex = String(env.KCC20_WRAPPER_OPERATOR_PRIVATE_KEY || "")
       .trim()
       .replace(/^0x/i, "");
     if (!privateKeyHex) {
@@ -8278,13 +8266,11 @@ export function createKcc20PsktBuilderEngine(
       params.targetOrderId,
       "target order id",
     );
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const priorityFee = parseU64(
-      env.KCC20_CANCEL_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_CANCEL_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const computeBudget = parsePositiveNumber(
@@ -8602,8 +8588,7 @@ export function createKcc20PsktBuilderEngine(
     const minterTxid = requireHex32(activeMinterUtxo.txidHex, "minter txid");
     const minterVout = parseVout(activeMinterUtxo.vout, "minter vout");
     const minterAddress = requireKaspaAddress(activeMinterUtxo.address);
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const tokenOutputSompi = assertKcc20TokenOutputSompi(
@@ -8615,8 +8600,7 @@ export function createKcc20PsktBuilderEngine(
       "mint",
     );
     const priorityFee = parseU64(
-      env.KCC20_MINT_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_MINT_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const computeBudget = parsePositiveNumber(
@@ -8988,8 +8972,7 @@ export function createKcc20PsktBuilderEngine(
     }
 
     const covenantId = requireHex32(params.covenantId, "canonical covenant id");
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const walletOwner = requireHex32(
       request.owner?.kcc20Owner,
@@ -9114,8 +9097,7 @@ export function createKcc20PsktBuilderEngine(
       "priorityFee",
     );
     const computeBudget = parsePositiveNumber(
-      env.KCC20_MINT_AVAILABILITY_COMPUTE_BUDGET ||
-        DEFAULT_COMPUTE_BUDGET,
+      env.KCC20_MINT_AVAILABILITY_COMPUTE_BUDGET || DEFAULT_COMPUTE_BUDGET,
       "computeBudget",
     );
     const rpc = new kaspaWasm.RpcClient({
@@ -9360,8 +9342,7 @@ export function createKcc20PsktBuilderEngine(
       "app canonical token id",
     );
     const owner = requireHex32(request.owner?.kcc20Owner, "token owner");
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const priorityFee = parseU64(
@@ -9627,13 +9608,11 @@ export function createKcc20PsktBuilderEngine(
     const params = request.params || {};
     const covenantId = requireHex32(params.covenantId, "canonical covenant id");
     const owner = requireHex32(request.owner?.kcc20Owner, "token owner");
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const priorityFee = parseU64(
-      env.KCC20_REVEAL_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_REVEAL_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const computeBudget = parsePositiveNumber(
@@ -9832,8 +9811,7 @@ export function createKcc20PsktBuilderEngine(
       "recipientOwnerScheme",
     );
     const transferAmount = parsePositiveU64(params.tokenAmount, "tokenAmount");
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const tokenOutputSompi = assertKcc20TokenOutputSompi(
@@ -9845,8 +9823,7 @@ export function createKcc20PsktBuilderEngine(
       "transfer",
     );
     const priorityFee = parseU64(
-      env.KCC20_TRANSFER_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_TRANSFER_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const computeBudget = parsePositiveNumber(
@@ -9924,7 +9901,18 @@ export function createKcc20PsktBuilderEngine(
           `active holder UTXO ${tokenTxid}:${tokenVout} not found`,
         );
       }
-      const spendCovenantId = covenantIdFromUtxoEntry(tokenEntry) ?? covenantId;
+      const rpcScript = tokenEntry.scriptPublicKey ??
+        tokenEntry.entry?.scriptPublicKey ?? tokenEntry.utxoEntry?.scriptPublicKey;
+      if (!rpcScript || kw.addressFromScriptPublicKey(rpcScript, network)?.toString() !== tokenAddress) {
+        throw new Error("active holder RPC script does not match rebuilt covenant state");
+      }
+      if (activeHolderUtxo.amountSompi != null &&
+          BigInt(activeHolderUtxo.amountSompi) !== utxoAmountSompi(tokenEntry)) {
+        throw new Error("active holder KAS amount does not match RPC");
+      }
+      const spendCovenantId = params.activeHolderNativeCovenantId
+        ? requireMatchingCovenantId(tokenEntry, covenantId, "active holder")
+        : covenantIdFromUtxoEntry(tokenEntry) ?? covenantId;
 
       let outputSompi = 0n;
       const recipientOutputIndex = 0;
@@ -10115,16 +10103,22 @@ export function createKcc20PsktBuilderEngine(
     );
     const decimals = parseU64(params.decimals ?? "0", "decimals");
     const priceScale = 10n ** decimals;
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
-    const amountTkas = parseAmountTkas(
-      env.KCC20_DEPLOY_OUTPUT_TKAS || DEFAULT_DEPLOY_TKAS,
-    );
+    const requestedOutputSompi =
+      params.outputSompi === undefined || params.outputSompi === null
+        ? undefined
+        : assertKcc20TokenOutputSompi(
+            parseU64(params.outputSompi, "outputSompi"),
+            "deploy",
+          );
+    const amountTkas =
+      requestedOutputSompi === undefined
+        ? parseAmountTkas(env.KCC20_DEPLOY_OUTPUT_TKAS || DEFAULT_DEPLOY_TKAS)
+        : undefined;
     const priorityFee = parseU64(
-      env.KCC20_DEPLOY_PRIORITY_FEE_SOMPI ||
-        DEFAULT_PRIORITY_FEE.toString(),
+      env.KCC20_DEPLOY_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
       "priorityFee",
     );
     const metadata = {
@@ -10249,7 +10243,9 @@ export function createKcc20PsktBuilderEngine(
       kw,
       covenantOutputs[0].script,
     );
-    const deploySompi = BigInt(Math.round(amountTkas * Number(SOMPI_PER_TKAS)));
+    const deploySompi =
+      requestedOutputSompi ??
+      BigInt(Math.round(amountTkas! * Number(SOMPI_PER_TKAS)));
     const premintOutputIndex = premintState ? covenantOutputs.length - 1 : null;
 
     const rpc = new RpcClient({
@@ -10264,6 +10260,8 @@ export function createKcc20PsktBuilderEngine(
       const fundingEntry = selectFundingEntry(
         utxos.entries,
         outputSompi + priorityFee + 10_000_000n,
+        [],
+        params.fundingOutpoint,
       );
       const fundingChangeOutputIndex = covenantOutputs.length;
       const change = utxoAmountSompi(fundingEntry) - outputSompi - priorityFee;
@@ -10455,8 +10453,7 @@ export function createKcc20PsktBuilderEngine(
       params.utilityTokenAmount,
       "utilityTokenAmount",
     );
-    const network =
-      request.network || env.KASPA_NETWORK || "testnet-10";
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
     const amountTkas = parseAmountTkas(
@@ -11699,10 +11696,7 @@ export function createKcc20PsktBuilderEngine(
   }
 
   async function retryUtxosByAddresses(rpc, addresses, isReady, initial) {
-    const attempts = parseRetryInteger(
-      env.KCC20_SOURCE_UTXO_RETRY_ATTEMPTS,
-      3,
-    );
+    const attempts = parseRetryInteger(env.KCC20_SOURCE_UTXO_RETRY_ATTEMPTS, 3);
     const delayMs = parseRetryInteger(
       env.KCC20_SOURCE_UTXO_RETRY_DELAY_MS,
       500,

package/src/index.ts

@@ -22,7 +22,15 @@ export * from "./runtime.js";
 export * as saleCommon from "./sale-common.js";
 export * from "./source-provider.js";
 export * from "./source-validation.js";
+export * from "./snapshot-operation.js";
+export * from "./snapshot-signerless.js";
+export * from "./snapshot-signerless-transactions.js";
 export * from "./wasm-provider.js";
 export * from "./wallet-operation.js";
 export * from "./wrapper-operation.js";
 export * from "./verify-operation.js";
+
+export * as snapshot from "./snapshot-signerless.js";
+export * as snapshotTransactions from "./snapshot-signerless-transactions.js";
+export * from "./snapshot-deployment.js";
+export * from "./snapshot-verification.js";

package/src/operations.ts

@@ -22,6 +22,10 @@ export const KCC20_BUILDER_KEYS = [
   "fee-ticket.create-from-utility-burn",
   "fee-ticket.burn",
   "fee-ticket.transfer",
+  "kcc20-snapshot.deploy-bootstrap",
+  "kcc20-snapshot.deploy-controller",
+  "kcc20-snapshot.start",
+  "kcc20-snapshot.claim",
 ] as const;
 
 export type Kcc20BuilderKey = (typeof KCC20_BUILDER_KEYS)[number];