@kaspacom/kcc20-tx-builder 0.4.0 → 0.6.0

package/src/snapshot-signerless-transactions.ts

@@ -61,10 +61,7 @@ export function buildSnapshotKcc20DeploymentPayload({
   if (normalizedProtocolFeeBps > 10_000n) {
     throw new Error("snapshot token protocol fee bps exceeds 10000");
   }
-  const normalizedMigrationId = hex32(
-    migrationId,
-    "snapshot migration id",
-  );
+  const normalizedMigrationId = hex32(migrationId, "snapshot migration id");
   const normalizedManifestCommitment = hex32(
     manifestCommitment,
     "snapshot manifest commitment",
@@ -132,11 +129,7 @@ export function buildSnapshotKcc20DeploymentPayload({
     claimArg("displayScale", "u64", normalizedDisplayScale.toString()),
     claimArg("mintPriceSompi", "u64", "0"),
     claimArg("treasury", "byte[32]", normalizedTreasury),
-    claimArg(
-      "protocolFeeRecipient",
-      "byte[32]",
-      normalizedFeeRecipient,
-    ),
+    claimArg("protocolFeeRecipient", "byte[32]", normalizedFeeRecipient),
     claimArg("protocolFeeBps", "u64", normalizedProtocolFeeBps.toString()),
     claimArg("ticker", "string", normalizedTicker),
     claimArg("name", "string", normalizedName),
@@ -274,7 +267,7 @@ export function buildSnapshotStartUnsignedTransaction(
     fundingInput,
     changeAddress,
     feeSompi,
-    payload = "",
+    payload = new Uint8Array() as Uint8Array<ArrayBufferLike>,
   },
 ) {
   requirePlan(plan, "snapshot-start-plan");
@@ -780,9 +773,7 @@ function fixedText32(value, label) {
 }
 
 function bytesHex(value) {
-  return [...value]
-    .map((byte) => byte.toString(16).padStart(2, "0"))
-    .join("");
+  return [...value].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 
 function transactionOf(kw, inputs, outputs, lockTime, payload) {
@@ -968,10 +959,10 @@ function setP2shSignatureScript(
   revealScript,
   prefix,
 ) {
-  transaction.inputs[inputIndex].signatureScript =
-    kw.ScriptBuilder.fromScript(
-      revealScript,
-    ).encodePayToScriptHashSignatureScript(prefix);
+  transaction.inputs[inputIndex].signatureScript = kw.ScriptBuilder.fromScript(
+    revealScript,
+    { flags: { covenantsEnabled: true } },
+  ).encodePayToScriptHashSignatureScript(prefix);
 }
 
 function unsignedEnvelope(kw, transaction, intent, signInputs) {

package/src/snapshot-signerless.ts

@@ -363,7 +363,9 @@ export function buildSnapshotStartSignatureScripts(
   const reserves = plan.reserves.map(normalizeKcc20State);
   const kcc20Template = templateParts(kcc20Artifact);
   const controllerTemplate = templateParts(controllerArtifact);
-  const bootstrapBuilder = new kw.ScriptBuilder();
+  const bootstrapBuilder = new kw.ScriptBuilder({
+    flags: { covenantsEnabled: true },
+  });
   for (const field of encodeControllerStateRecordArrays(controllers))
     bootstrapBuilder.addData(field);
   for (const field of encodeKcc20StateRecordArrays(reserves))
@@ -374,7 +376,7 @@ export function buildSnapshotStartSignatureScripts(
   bootstrapBuilder.addData(controllerTemplate.suffix);
   bootstrapBuilder.addData(dispatchTagFor(bootstrapArtifact, "start"));
   const controllerSignatureScripts = controllers.map((state, index) => {
-    const builder = new kw.ScriptBuilder();
+    const builder = new kw.ScriptBuilder({ flags: { covenantsEnabled: true } });
     addControllerState(builder, state);
     builder.addI64(BigInt(bootstrapInputIndex));
     builder.addI64(BigInt(index));
@@ -591,7 +593,7 @@ export function buildClaimSignatureScripts(
   requireControllerArtifact(controllerArtifact);
   requireKcc20Artifact(kcc20Artifact);
   requireOwnerWitness(claim.ownerScheme, claim.ownerWitness);
-  const builder = new kw.ScriptBuilder();
+  const builder = new kw.ScriptBuilder({ flags: { covenantsEnabled: true } });
   builder.addI64(BigInt(claim.globalIndex));
   builder.addI64(BigInt(claim.shardLeafIndex));
   addByte(builder, claim.ownerScheme);

package/src/snapshot-verification.ts

@@ -1,20 +1,23 @@
 import { prepareSnapshotDeployment, type SnapshotArtifacts, type SnapshotDeploymentDefinition } from './snapshot-deployment.js';
-import { bytesToHex } from './encoding.js';
 import * as tx from './snapshot-signerless-transactions.js';
 
-export function snapshotStartPayload(definition: SnapshotDeploymentDefinition, prepared: ReturnType<typeof prepareSnapshotDeployment>): string {
+export function snapshotStartPayload(definition: SnapshotDeploymentDefinition, prepared: ReturnType<typeof prepareSnapshotDeployment>): Uint8Array {
   const plan = prepared.plan;
   if (prepared.stage !== 'snapshot-start') throw new Error('snapshot start plan required');
-  const opening = {
-    ...prepared.extension, ticker: definition.ticker, name: definition.ticker,
-    premintSupply: definition.totalSupply, premintRecipient: plan.reserves[0].owner, premintOwnerScheme: 4,
-    holderExtensionCommitment: prepared.holderExtensionCommitment, snapshotMigrationId: definition.migrationId,
-    snapshotManifestCommitment: definition.manifestCommitment,
-    snapshotReserves: plan.reserves.map((reserve: any, shardIndex: number) => ({ ...reserve, shardIndex })),
-  };
-  return bytesToHex(new TextEncoder().encode(JSON.stringify({ tn10: { v: 1, tmpl: 'KCC20',
-    args: Object.entries(opening).map(([name, value]) => ({ name, type: 'value', value })),
-  } })));
+  return tx.buildSnapshotKcc20DeploymentPayload({
+    creator: definition.creator,
+    ticker: definition.ticker,
+    name: definition.ticker,
+    displayScale: definition.displayScale,
+    totalSupply: definition.totalSupply,
+    holderExtensionCommitment: prepared.holderExtensionCommitment,
+    migrationId: definition.migrationId,
+    manifestCommitment: definition.manifestCommitment,
+    reserves: plan.reserves,
+    treasury: definition.creator,
+    protocolFeeRecipient: definition.creator,
+    protocolFeeBps: 0,
+  });
 }
 
 /** Reconstruct the whole transaction from approved definition and pinned artifacts. */
@@ -59,7 +62,8 @@ export function verifySnapshotDeploymentTransaction(kw: any, args: {
       throw new Error('snapshot bootstrap input differs from approved genesis');
     }
     expected = tx.buildSnapshotStartUnsignedTransaction(kw, {
-      ...common, payload: snapshotStartPayload(args.definition, prepared),
+      ...common,
+      payload: snapshotStartPayload(args.definition, prepared),
       bootstrapInput,
       controllerInputs: plan.controllers.map((controller: any, index: number) => {
         const actual = input(index + 1, tx.buildSnapshotControllerScriptForState(args.artifacts.controllerArtifact, controller.stateBefore));

package/src/token-authorization.ts

@@ -0,0 +1,135 @@
+import { blake3 } from "@noble/hashes/blake3";
+import { requireTokenCapability, type TokenProfile } from "./token-profiles.js";
+
+export interface TokenSigningCapabilities {
+  schnorr: boolean;
+  ecdsa: boolean;
+}
+export type TokenWitnessArgument =
+  | { type: "data"; hex: string }
+  | { type: "signature"; prefixHex: string };
+export interface TokenAuthorityInput {
+  index: number;
+  scriptPublicKeyHex: string;
+  covenantId?: string;
+}
+const hex = (v: Uint8Array) =>
+  Array.from(v, (b) => b.toString(16).padStart(2, "0")).join("");
+const bytes = (v: string, size: number, label: string) => {
+  if (!new RegExp(`^[0-9a-f]{${size * 2}}$`, "i").test(v))
+    throw new Error(`invalid ${label}`);
+  return Uint8Array.from(v.match(/../g)!, (b) => parseInt(b, 16));
+};
+export function tokenPublicKeyHash(publicKey: Uint8Array): Uint8Array {
+  if (![32, 33].includes(publicKey.length))
+    throw new Error("invalid token public key length");
+  return blake3(publicKey);
+}
+/** Authority inputs must come from the authenticated transaction UTXOs, never an uploaded artifact. */
+export function planTokenOwnerWitness(input: {
+  profile: TokenProfile;
+  owner: string;
+  ownerScheme: number;
+  publicKey?: string;
+  capabilities: TokenSigningCapabilities;
+  authorityInputIndex?: number;
+  authorityInputs?: readonly TokenAuthorityInput[];
+  role: "leader" | "delegator";
+}): {
+  argument: TokenWitnessArgument;
+  signatureAlgorithm?: "schnorr" | "ecdsa";
+  authorityInputIndex?: number;
+} {
+  const { profile, ownerScheme } = input;
+  requireTokenCapability(profile, "transfer");
+  bytes(input.owner, 32, "token owner");
+  if (!profile.ownerSchemes.includes(ownerScheme))
+    throw new Error("token profile does not support this owner scheme");
+  const prefix = input.role === "leader" ? "00" : "";
+  if (ownerScheme <= 2) {
+    const algorithm = ownerScheme === 2 ? "ecdsa" : "schnorr";
+    if (!input.capabilities[algorithm])
+      throw new Error(`wallet does not support ${algorithm} token signatures`);
+    const key = bytes(
+      input.publicKey ?? "",
+      ownerScheme === 2 ? 33 : 32,
+      "wallet public key",
+    );
+    if (ownerScheme === 2 && key[0] !== 2 && key[0] !== 3)
+      throw new Error("ECDSA key must be compressed");
+    const expected =
+      ownerScheme === 0 ? hex(key) : hex(tokenPublicKeyHash(key));
+    if (expected !== input.owner.toLowerCase())
+      throw new Error("wallet public key does not own the token output");
+    return {
+      argument: {
+        type: "signature",
+        prefixHex: prefix + (ownerScheme === 0 ? "" : hex(key)),
+      },
+      signatureAlgorithm: algorithm,
+    };
+  }
+  const index = input.authorityInputIndex;
+  if (!Number.isSafeInteger(index) || index! < 0 || index! > 255)
+    throw new Error("explicit authority input index is required");
+  const matches = (input.authorityInputs ?? []).filter(
+    (a) => a.index === index,
+  );
+  if (matches.length !== 1)
+    throw new Error("authority input is missing or ambiguous");
+  const authority = matches[0];
+  if (
+    ownerScheme === 3 &&
+    authority.scriptPublicKeyHex.toLowerCase() !==
+      `aa20${input.owner.toLowerCase()}87`
+  )
+    throw new Error("authority input does not match token P2SH owner");
+  if (
+    ownerScheme === 4 &&
+    authority.covenantId?.toLowerCase() !== input.owner.toLowerCase()
+  )
+    throw new Error("authority input does not match token covenant owner");
+  return {
+    argument: {
+      type: "data",
+      hex:
+        prefix +
+        (ownerScheme === 3 ? index!.toString(16).padStart(2, "0") : ""),
+    },
+    authorityInputIndex: index,
+  };
+}
+/** Borrowing is an explicit mode. This function never converts an ordinary send into a borrow. */
+export function buildTokenBorrowWitness(input: {
+  profile: TokenProfile;
+  borrowScheme: number;
+  currentGuard: string;
+  signature?: string;
+  nextGuard?: string;
+  oneTimePublicKey?: string;
+}): Uint8Array {
+  requireTokenCapability(input.profile, "borrow");
+  const current = bytes(input.currentGuard, 32, "borrow guard");
+  if (input.borrowScheme === 1) {
+    if (
+      input.signature !== undefined ||
+      input.nextGuard !== undefined ||
+      input.oneTimePublicKey !== undefined
+    )
+      throw new Error("threshold borrowing requires an empty authorization");
+    return Uint8Array.of(1);
+  }
+  const sig = bytes(input.signature ?? "", 65, "borrow signature");
+  if (input.borrowScheme === 2) {
+    if (input.nextGuard !== undefined || input.oneTimePublicKey !== undefined)
+      throw new Error("Schnorr borrowing does not rotate its guard");
+    return Uint8Array.from([1, ...sig]);
+  }
+  if (input.borrowScheme !== 3)
+    throw new Error("unsupported or disabled borrow scheme");
+  const guard = bytes(input.nextGuard ?? "", 32, "next borrow guard");
+  const key = bytes(input.oneTimePublicKey ?? "", 32, "one-time public key");
+  if (hex(blake3(Uint8Array.from([...guard, ...key]))) !== hex(current))
+    throw new Error("hash-chain link does not match current guard");
+  return Uint8Array.from([1, ...guard, ...key, ...sig]);
+}

package/src/token-profiles.generated.ts

@@ -0,0 +1,112 @@
+// Generated by scripts/sync-reviewed-artifacts.mjs. Do not edit.
+import type { TokenProfileRegistry } from "./token-profiles.js";
+export const BUNDLED_TOKEN_PROFILE_DIGEST = "dd4880c1b89564d250fefb09949c07235e23d7fcbca0ff3f061396b515455b01";
+export const BUNDLED_TOKEN_PROFILES: TokenProfileRegistry = {
+  "schema": "kcc20-token-profiles/v2",
+  "standardRevision": "3fbec524abfbc20e87652eb938db218f8c17db17",
+  "profiles": [
+    {
+      "id": "kaspacom-kcc20-last-call-v1",
+      "artifactKey": "KCC20.placeholder.json",
+      "artifactSha256": "a45d06e8351421dac1ef73f3595c6f34068e4fa1e13d3f8fa1c88be518c6e56f",
+      "artifactCanonicalSha256": "2c299e2d354fd3d0e61b0987778d18bd0e5f17ccfdee614eb98a48fcf5779a8b",
+      "scriptSha256": "dd9cb334cd9e9220b15644782f271ef3ecdba34fd0762010e3d6bc18176837ae",
+      "scriptLength": 25377,
+      "templateHash": "5d6cacdf57c734536fcb8a9c833f0318671226727ec77c503a98fc5be59f9e29",
+      "stateLayout": {
+        "start": 1,
+        "len": 112
+      },
+      "standardRevision": "3fbec524abfbc20e87652eb938db218f8c17db17",
+      "transferEntrypoint": "transfer",
+      "delegatorEntrypoint": "transfer_delegator",
+      "transferTag": "79c71c23",
+      "delegatorTag": "fd3ef14a",
+      "ownerSchemes": [
+        0,
+        1,
+        2,
+        3,
+        4
+      ],
+      "maxTokenInputs": 8,
+      "maxTokenOutputs": 8,
+      "operations": [
+        "transfer",
+        "borrow",
+        "mint",
+        "burn",
+        "wrap",
+        "unwrap",
+        "trade"
+      ],
+      "fungibility": "single-holder-class",
+      "nativeExtensions": true,
+      "wrapper": {
+        "fingerprint": "0634803d0cb750fb555f5eccbd57d18d9638736b675caab290e46a8acdbb25dd",
+        "artifactKey": "KCC20Wrapper.placeholder.json",
+        "artifactSha256": "2461e39a285d1f135f4891659cb78b3b6e5d2b28b32e153b61e2e336eab02115",
+        "artifactCanonicalSha256": "0eba9f91c89c180f3683e61e11bae9ab9b8cfe8674e98e58e9f2b2b1e920be83",
+        "scriptSha256": "23cbd5473860cab4e63890d24ae1bd6732fce5beaa34f594dad01e845e3e9b9f",
+        "scriptLength": 3895,
+        "stateLayout": {
+          "start": 1,
+          "len": 44
+        },
+        "templateHash": "c4e08636c63cbd33e3a0703167a480cc4af3a42444f24c4d526df84104280515",
+        "tokenTemplateHash": "5d6cacdf57c734536fcb8a9c833f0318671226727ec77c503a98fc5be59f9e29"
+      }
+    },
+    {
+      "id": "argent-reference-kcc20-v1",
+      "artifactKey": "ArgentKCC20.reference.json",
+      "transferEntrypoint": "transfer",
+      "delegatorEntrypoint": "transfer_delegator",
+      "transferTag": "79c71c23",
+      "delegatorTag": "fd3ef14a",
+      "ownerSchemes": [
+        0,
+        1,
+        2,
+        3,
+        4
+      ],
+      "maxTokenInputs": 3,
+      "maxTokenOutputs": 3,
+      "operations": [
+        "transfer",
+        "borrow",
+        "wrap",
+        "unwrap",
+        "trade"
+      ],
+      "fungibility": "single-holder-class",
+      "displayDecimals": 0,
+      "artifactSha256": "eb95459fdcfd63c3736be623984f49529899fb03288f1363e340eb3acf74e513",
+      "artifactCanonicalSha256": "dab8e196dc29fccc10b51a50a48cf45d9253de63822c7fcd703702cc70673ab9",
+      "scriptSha256": "f3d52b46bc8994a0b564557ea474cd4f79d2c054dcddbc2b017aaad3b306b1e8",
+      "scriptLength": 4031,
+      "templateHash": "734850b0af0aeef49f009167bf9ddd238fd8c5cdbe214234f97181ac6f5cc498",
+      "stateLayout": {
+        "start": 34,
+        "len": 112
+      },
+      "standardRevision": "3fbec524abfbc20e87652eb938db218f8c17db17",
+      "nativeExtensions": false,
+      "wrapper": {
+        "fingerprint": "455772a93ec788b755a832655eee96d14050c3dfb2263a4fd8d7dd19705632d4",
+        "artifactKey": "ArgentKCC20Wrapper.placeholder.json",
+        "artifactSha256": "fc3b21bdd90cef56d18f4eb2e05b2b0938cb631cfda2a247c99caeec4e505235",
+        "artifactCanonicalSha256": "0e1c99e12b53299305317ac663d69e7190e38a8fd33b53355fff86f847c74480",
+        "scriptSha256": "4ae0e302539180a2586b22dfe2aeb579bd867e680d3fddf712b724b7d3d41fa8",
+        "scriptLength": 3965,
+        "stateLayout": {
+          "start": 1,
+          "len": 44
+        },
+        "templateHash": "1fbe92003266693d2a527d1fc8a4cb1397773f2922702b921aec723a541a6420",
+        "tokenTemplateHash": "734850b0af0aeef49f009167bf9ddd238fd8c5cdbe214234f97181ac6f5cc498"
+      }
+    }
+  ]
+};