@kaspacom/kcc20-tx-builder 0.5.0 → 0.6.0

package/src/engine.ts

@@ -1,5 +1,19 @@
 // @ts-nocheck
+import { planTokenOwnerWitness } from "./token-authorization.js";
 import { sha256 } from "@noble/hashes/sha256";
+import {
+  authenticateTokenArtifact,
+  authenticateTokenWrapper,
+  validateTokenProfileRegistry,
+  requireTokenCapability,
+  resolveTokenProfilePriceScale,
+} from "./token-profiles.js";
+import { buildAuthenticatedKcc20TransferPayload } from "./transfer-payload.js";
+import {
+  BUNDLED_TOKEN_PROFILES,
+  BUNDLED_TOKEN_PROFILE_DIGEST,
+} from "./token-profiles.generated.js";
+import type { TokenProfileRegistry } from "./token-profiles.js";
 import type { KaspaWasmRuntime } from "./runtime.js";
 import {
   DEFAULT_COMPUTE_BUDGET,
@@ -55,6 +69,7 @@ import {
   buildKcc20SetPublicMintActiveSigScript,
   buildKcc20TransferSigScript,
   dispatchTagFor,
+  templateHash,
   encodeKcc20StateRecordArrays,
   holderExtensionCommitment,
   mintExtensionCommitment,
@@ -81,6 +96,9 @@ export interface Kcc20PsktBuilderEngineOptions {
   };
   rpcClientFactory?: (config: unknown) => any;
   allowBackendOnly?: boolean;
+  walletSigningCapabilities?: { schnorr: boolean; ecdsa: boolean };
+  /** Trusted host registry; never populate this from transaction request data. */
+  tokenProfileRegistry?: { manifest: TokenProfileRegistry; sha256: string };
 }
 
 export interface FeeTicketBatchCreateCapability {
@@ -210,6 +228,10 @@ export function createKcc20PsktBuilderEngine(
   const WRAPPED_ARTIFACT_PATH = "KCC20Orderbook.placeholder.json";
   const FEE_TICKET_ARTIFACT_PATH = "KCC20FeeTicket.placeholder.json";
   const staticArtifactCache = new Map();
+  const tokenProfiles = validateTokenProfileRegistry(
+    options.tokenProfileRegistry?.manifest ?? BUNDLED_TOKEN_PROFILES,
+    options.tokenProfileRegistry?.sha256 ?? BUNDLED_TOKEN_PROFILE_DIGEST,
+  );
 
   function readStaticArtifact(path) {
     let cached = staticArtifactCache.get(path);
@@ -224,7 +246,18 @@ export function createKcc20PsktBuilderEngine(
               ? (artifact.artifact ?? artifact)
               : artifact;
           const normalized = normalizeSilverScriptArtifact(artifactValue);
-          assertKcc20ArtifactScriptHash(path, normalized);
+          const profile = tokenProfiles.profiles.find(
+            (p) => p.artifactKey === path,
+          );
+          if (profile) authenticateTokenArtifact(profile, artifactValue);
+          else {
+            const ownerProfile = tokenProfiles.profiles.find(
+              (p) => p.wrapper?.artifactKey === path,
+            );
+            if (ownerProfile)
+              authenticateTokenWrapper(ownerProfile, artifactValue);
+            else assertKcc20ArtifactScriptHash(path, normalized);
+          }
           return normalized;
         })
         .catch((error) => {
@@ -244,18 +277,28 @@ export function createKcc20PsktBuilderEngine(
   }
 
   async function resolveKcc20ArtifactForState(state, address, network) {
-    const artifact = await readStaticArtifact(KCC20_ARTIFACT_PATH);
-    const script = buildKcc20ScriptForState(artifact, state);
-    const candidateAddress = kaspaWasm
-      .addressFromScriptPublicKey(
-        kaspaWasm.payToScriptHashScript(script),
-        network,
+    for (const profile of tokenProfiles.profiles) {
+      const artifact = await readStaticArtifact(profile.artifactKey);
+      const script = buildKcc20ScriptForState(artifact, state);
+      const candidateAddress = kaspaWasm
+        .addressFromScriptPublicKey(
+          kaspaWasm.payToScriptHashScript(script),
+          network,
+        )
+        .toString();
+      if (candidateAddress !== address) continue;
+      requireTokenCapability(profile, "transfer");
+      if (
+        !profile.ownerSchemes.includes(
+          Number(state.ownerScheme ?? state.identifierType),
+        )
       )
-      .toString();
-    if (candidateAddress !== address) {
-      throw new Error("KCC20 UTXO address does not match the current artifact");
+        throw new Error("owner scheme is unsupported by this token profile");
+      return { version: profile.id, profile, artifact, script };
     }
-    return { version: "standard-native-v1", artifact, script };
+    throw new Error(
+      "KCC20 UTXO address does not match a bundled token profile",
+    );
   }
 
   function artifactEntrypointDispatchTag(artifact, entrypoint) {
@@ -306,13 +349,13 @@ export function createKcc20PsktBuilderEngine(
     ];
   }
 
-  async function readWrapperArtifacts() {
-    return [
-      {
-        artifact: await readStaticArtifact(WRAPPER_ARTIFACT_PATH),
-        version: "standard-native-v1",
-      },
-    ];
+  async function readWrapperArtifacts(profile) {
+    if (!profile.wrapper) return [];
+    return [{
+      artifact: await readStaticArtifact(profile.wrapper.artifactKey),
+      version: "standard-native-v1",
+      tokenProfileId: profile.id,
+    }];
   }
 
   function wrappedArtifactSupportsEntrypoint(info, name) {
@@ -545,7 +588,6 @@ export function createKcc20PsktBuilderEngine(
     }
 
     const builderKey = input.request?.builderKey;
-
     if (
       builderKey === "kcc20orderbook.matcher-settle-crossed" &&
       !options.allowBackendOnly
@@ -872,10 +914,7 @@ export function createKcc20PsktBuilderEngine(
       payToScriptHashScript,
     } = kw;
 
-    const utilityScript = buildNativeKcc20ScriptForState(
-      kcc20Artifact.script,
-      utilityState,
-    );
+    const utilityScript = buildKcc20ScriptForState(kcc20Artifact, utilityState);
     const rootAddress = requireKaspaAddress(rootUtxo.address);
     const utilityAddress = requireKaspaAddress(utilityUtxo.address);
     const rootArtifactInfo = selectFeeTicketArtifactForState(
@@ -2606,13 +2645,7 @@ export function createKcc20PsktBuilderEngine(
       params.wrappedRootAmount ?? "0",
       "wrappedRootAmount",
     );
-    const priceScale = parsePositiveU64(
-      params.priceScale ??
-        params.tokenDisplayScale ??
-        DEFAULT_KCC20_PRICE_SCALE,
-      "priceScale",
-    );
-    assertWrapperArtifactPriceScale(priceScale);
+    const requestedPriceScale = params.priceScale ?? params.tokenDisplayScale;
     const network = request.network || env.KASPA_NETWORK || "testnet-10";
     const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
     const rpcUrl = env.KASPA_WRPC_URL || DEFAULT_WRPC_URL;
@@ -2630,7 +2663,31 @@ export function createKcc20PsktBuilderEngine(
       "computeBudget",
     );
 
-    const wrapperArtifact = await readStaticArtifact(WRAPPER_ARTIFACT_PATH);
+    const evidence = params.tokenUtxo;
+    if (!evidence)
+      throw new Error(
+        "authenticated token output is required before wrapper deployment",
+      );
+    const sourceState = kcc20StateFromUtxo(evidence, request.owner);
+    const sourceProfile = await resolveKcc20ArtifactForState(
+      sourceState,
+      requireKaspaAddress(evidence.address),
+      network,
+    );
+    requireTokenCapability(sourceProfile.profile, "wrap");
+    if (!sourceProfile.profile.wrapper)
+      throw new Error("token profile has no wrapper adapter");
+    const priceScale = resolveTokenProfilePriceScale(
+      sourceProfile.profile,
+      requestedPriceScale === undefined
+        ? undefined
+        : parsePositiveU64(requestedPriceScale, "priceScale"),
+      DEFAULT_KCC20_PRICE_SCALE,
+    );
+    assertWrapperArtifactPriceScale(priceScale);
+    const wrapperArtifact = await readStaticArtifact(
+      sourceProfile.profile.wrapper.artifactKey,
+    );
     const wrappedArtifacts = await readWrappedArtifacts();
     const wrappedArtifact = wrappedArtifacts[0].artifact;
     const wrapperState = {
@@ -2688,6 +2745,29 @@ export function createKcc20PsktBuilderEngine(
     });
     await rpc.connect();
     try {
+      const evidenceUtxos = await getUtxosByAddresses(rpc, [evidence.address]);
+      const sourceEntry = findUtxoEntry(
+        evidenceUtxos.entries,
+        requireHex32(evidence.txidHex, "token evidence txid"),
+        parseVout(evidence.vout, "token evidence vout"),
+      );
+      if (!sourceEntry)
+        throw new Error("token evidence is spent or unavailable");
+      requireMatchingCovenantId(
+        sourceEntry,
+        contractCanonicalTokenId,
+        "wrapper token evidence",
+      );
+      const sourceSpk =
+        sourceEntry.scriptPublicKey ??
+        sourceEntry.entry?.scriptPublicKey ??
+        sourceEntry.utxoEntry?.scriptPublicKey;
+      if (
+        !sourceSpk ||
+        kw.addressFromScriptPublicKey(sourceSpk, network)?.toString() !==
+          evidence.address
+      )
+        throw new Error("token evidence script does not match RPC");
       const utxos = await getUtxosByAddresses(rpc, [walletAddress]);
       const fundingEntry = selectFundingEntry(
         utxos.entries,
@@ -2812,6 +2892,10 @@ export function createKcc20PsktBuilderEngine(
         submitTransactionSupported: true,
         metadata: {
           builderKey: "kcc20wrapper.deploy-market",
+          tokenProfileId: sourceProfile.profile.id,
+          tokenProfileRegistryHash:
+            options.tokenProfileRegistry?.sha256 ??
+            BUNDLED_TOKEN_PROFILE_DIGEST,
           contract: "KCC20Wrapper",
           network,
           walletAddress,
@@ -2942,10 +3026,7 @@ export function createKcc20PsktBuilderEngine(
       "computeBudget",
     );
 
-    const [wrapperArtifacts, wrappedArtifacts] = await Promise.all([
-      readWrapperArtifacts(),
-      readWrappedArtifacts(),
-    ]);
+    const wrappedArtifacts = await readWrappedArtifacts();
     const holderState = kcc20StateFromUtxo(holderUtxo, request.owner);
     if (holderState.identifierType !== 0) {
       throw new Error("wrap requires pubkey-owned KCC20 holder UTXO");
@@ -2966,6 +3047,8 @@ export function createKcc20PsktBuilderEngine(
       network,
     );
     const kcc20Artifact = kcc20ArtifactInfo.artifact;
+    requireTokenCapability(kcc20ArtifactInfo.profile, "wrap");
+    const wrapperArtifacts = await readWrapperArtifacts(kcc20ArtifactInfo.profile);
     const remaining = holderState.amount - tokenAmount;
     const priceScale = parsePositiveU64(
       wrapperUtxo.state?.priceScale ??
@@ -3007,7 +3090,9 @@ export function createKcc20PsktBuilderEngine(
 
     const wrapperArtifactInfo = selectWrapperArtifactForUtxo({
       kw,
-      artifacts: wrapperArtifacts,
+      artifacts: wrapperArtifacts.filter(
+        (info) => info.tokenProfileId === kcc20ArtifactInfo.profile.id,
+      ),
       state: wrapperState,
       utxo: wrapperUtxo,
       network,
@@ -3024,10 +3109,7 @@ export function createKcc20PsktBuilderEngine(
     const wrapperArtifact = wrapperArtifactInfo.artifact;
     const wrappedArtifact = wrappedArtifactInfo.artifact;
     const wrapperScript = wrapperArtifactInfo.script;
-    const holderScript = buildNativeKcc20ScriptForState(
-      kcc20Artifact.script,
-      holderState,
-    );
+    const holderScript = buildKcc20ScriptForState(kcc20Artifact, holderState);
     const wrapperAddress = requireKaspaAddress(wrapperUtxo.address);
     const holderAddress = requireKaspaAddress(holderUtxo.address);
     assertScriptAddress(
@@ -3072,7 +3154,7 @@ export function createKcc20PsktBuilderEngine(
           (entries) =>
             Boolean(
               findUtxoEntry(entries, wrapperTxid, wrapperVout) &&
-              findUtxoEntry(entries, holderTxid, holderVout),
+                findUtxoEntry(entries, holderTxid, holderVout),
             ),
           covenantUtxos,
         );
@@ -3358,10 +3440,7 @@ export function createKcc20PsktBuilderEngine(
       "computeBudget",
     );
 
-    const [wrapperArtifacts, wrappedArtifacts] = await Promise.all([
-      readWrapperArtifacts(),
-      readWrappedArtifacts(),
-    ]);
+    const wrappedArtifacts = await readWrappedArtifacts();
     const reserveState = kcc20StateFromUtxo(reserveUtxo, request.owner);
     if (reserveState.ownerScheme !== 4 || reserveState.isMintAuthority) {
       throw new Error("KCC20 reserve UTXO must be covenant-owned holder state");
@@ -3375,6 +3454,8 @@ export function createKcc20PsktBuilderEngine(
       network,
     );
     const kcc20Artifact = kcc20ArtifactInfo.artifact;
+    requireTokenCapability(kcc20ArtifactInfo.profile, "unwrap");
+    const wrapperArtifacts = await readWrapperArtifacts(kcc20ArtifactInfo.profile);
     const wrappedState = kcc20V3WrappedStateFromUtxo(
       wrappedUtxo,
       canonicalTokenId,
@@ -3442,7 +3523,9 @@ export function createKcc20PsktBuilderEngine(
 
     const wrapperArtifactInfo = selectWrapperArtifactForUtxo({
       kw,
-      artifacts: wrapperArtifacts,
+      artifacts: wrapperArtifacts.filter(
+        (info) => info.tokenProfileId === kcc20ArtifactInfo.profile.id,
+      ),
       state: wrapperState,
       utxo: wrapperUtxo,
       network,
@@ -3467,10 +3550,7 @@ export function createKcc20PsktBuilderEngine(
     const wrappedScript = wrappedArtifactInfo.script;
     const refundAware =
       wrappedArtifactRefundsHolderDeposits(wrappedArtifactInfo);
-    const reserveScript = buildNativeKcc20ScriptForState(
-      kcc20Artifact.script,
-      reserveState,
-    );
+    const reserveScript = buildKcc20ScriptForState(kcc20Artifact, reserveState);
     const wrapperAddress = wrapperArtifactInfo.address;
     const wrappedAddress = wrappedArtifactInfo.address;
     const reserveAddress = requireKaspaAddress(reserveUtxo.address);
@@ -8621,6 +8701,7 @@ export function createKcc20PsktBuilderEngine(
       minterAddress,
       network,
     );
+    requireTokenCapability(resolvedArtifact.profile, "mint");
     const artifact = resolvedArtifact.artifact;
     const recipientState = {
       amount: mintAmount,
@@ -9056,6 +9137,7 @@ export function createKcc20PsktBuilderEngine(
             minterAddress,
             network,
           );
+          requireTokenCapability(resolvedArtifact.profile, "mint");
           dispatchTagFor(resolvedArtifact.artifact, "set_public_mint_active");
           const minterTxid = requireHex32(
             activeMinterUtxo.txidHex,
@@ -9386,6 +9468,10 @@ export function createKcc20PsktBuilderEngine(
     ) {
       throw new Error("consolidation requires holder UTXOs from one artifact");
     }
+    const profile = resolvedArtifacts[0].profile;
+    if (holderUtxos.length > profile.maxTokenInputs) {
+      throw new Error("consolidation exceeds the token profile input bound");
+    }
     const artifact = resolvedArtifacts[0].artifact;
     for (const peerState of states.slice(1)) {
       assertKcc20MergeableStates(primaryState, peerState, owner);
@@ -9835,14 +9921,6 @@ export function createKcc20PsktBuilderEngine(
     if (inputState.isMintAuthority || inputState.amount <= 0n) {
       throw new Error("KCC20 transfer requires a holder UTXO");
     }
-    if (inputState.ownerScheme !== 0) {
-      throw new Error("KCC20 transfer requires a Schnorr P2PK holder UTXO");
-    }
-    if (bytesToHex(inputState.ownerIdentifier) !== owner) {
-      throw new Error(
-        "KCC20 transfer requires wallet to own the active holder UTXO",
-      );
-    }
     if (transferAmount > inputState.amount) {
       throw new Error("tokenAmount exceeds active holder balance");
     }
@@ -9856,6 +9934,25 @@ export function createKcc20PsktBuilderEngine(
       network,
     );
     const artifact = resolvedArtifact.artifact;
+    if (params.mode && params.mode !== "owner")
+      throw new Error(
+        "borrowed receive requires the explicit borrow transaction builder",
+      );
+    const authorization = planTokenOwnerWitness({
+      profile: resolvedArtifact.profile,
+      owner: bytesToHex(inputState.ownerIdentifier),
+      ownerScheme: inputState.ownerScheme,
+      publicKey: request.owner?.publicKey ?? request.owner?.kcc20Owner,
+      capabilities: options.walletSigningCapabilities ?? {
+        schnorr: true,
+        ecdsa: false,
+      },
+      role: "leader",
+    });
+    if (!resolvedArtifact.profile.ownerSchemes.includes(recipientOwnerScheme))
+      throw new Error(
+        "recipient owner scheme is unsupported by the token profile",
+      );
     const recipientState = {
       ...inputState,
       owner: hexToBytes(recipientOwner),
@@ -9901,18 +9998,28 @@ export function createKcc20PsktBuilderEngine(
           `active holder UTXO ${tokenTxid}:${tokenVout} not found`,
         );
       }
-      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");
+      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)) {
+      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;
+        : (covenantIdFromUtxoEntry(tokenEntry) ?? covenantId);
 
       let outputSompi = 0n;
       const recipientOutputIndex = 0;
@@ -9991,9 +10098,9 @@ export function createKcc20PsktBuilderEngine(
         outputs,
         subnetworkId: SUBNETWORK_ID_NATIVE,
         gas: 0n,
-        payload: buildTransferPayload({
+        payload: buildAuthenticatedKcc20TransferPayload({
           covenantId: spendCovenantId,
-          fromOwner: owner,
+          fromOwnerIdentifier: bytesToHex(inputState.ownerIdentifier),
           recipientOwner,
           recipientOwnerScheme,
           tokenAmount: transferAmount,
@@ -10007,11 +10114,13 @@ export function createKcc20PsktBuilderEngine(
           inputIndex: 0,
           scriptHex: bytesToHex(tokenScript),
           signType: 1,
+          signatureAlgorithm: authorization.signatureAlgorithm,
           signatureScript: {
             mode: "ordered-args",
             args: kcc20TransferOrderedArgs(
               artifact,
               changeState ? [recipientState, changeState] : [recipientState],
+              authorization.argument,
             ),
           },
         },
@@ -10038,6 +10147,10 @@ export function createKcc20PsktBuilderEngine(
         scripts,
         submitTransactionSupported: true,
         metadata: {
+          tokenProfileId: resolvedArtifact.profile.id,
+          tokenProfileRegistryHash:
+            options.tokenProfileRegistry?.sha256 ??
+            BUNDLED_TOKEN_PROFILE_DIGEST,
           builderKey: "kcc20.transfer",
           operation: "transfer-token",
           action: "transfer",
@@ -11264,37 +11377,6 @@ export function createKcc20PsktBuilderEngine(
     );
   }
 
-  function buildTransferPayload(fields) {
-    return new TextEncoder().encode(
-      JSON.stringify({
-        tn12: {
-          v: 1,
-          tmpl: "KCC20",
-          op: "transfer",
-          args: [
-            { name: "covenantId", type: "byte[32]", value: fields.covenantId },
-            { name: "fromOwner", type: "byte[32]", value: fields.fromOwner },
-            {
-              name: "recipientOwner",
-              type: "byte[32]",
-              value: fields.recipientOwner,
-            },
-            {
-              name: "recipientOwnerScheme",
-              type: "u64",
-              value: String(fields.recipientOwnerScheme),
-            },
-            {
-              name: "tokenAmount",
-              type: "u64",
-              value: fields.tokenAmount.toString(),
-            },
-          ],
-        },
-      }),
-    );
-  }
-
   function tokenOutput(
     kw,
     artifact,
@@ -13046,9 +13128,9 @@ export function createKcc20PsktBuilderEngine(
     );
     const publicMintActive = Boolean(
       source.publicMintActive ??
-      state.publicMintActive ??
-      mintPolicy.publicMintActive ??
-      false,
+        state.publicMintActive ??
+        mintPolicy.publicMintActive ??
+        false,
     );
     const extension = {
       kind: Number(source.kind ?? 1),
@@ -13186,20 +13268,41 @@ export function createKcc20PsktBuilderEngine(
     return values;
   }
 
-  function kcc20TransferOrderedArgs(artifact, nextStates) {
+  function profileForArtifact(artifact) {
+    const parts = templateParts(artifact);
+    const hash = bytesToHex(templateHash(parts.prefix, parts.suffix));
+    const profile = tokenProfiles.profiles.find((p) => p.templateHash === hash);
+    if (!profile) throw new Error("token artifact has no bundled profile");
+    return profile;
+  }
+
+  function kcc20TransferOrderedArgs(artifact, nextStates, witness) {
+    const profile = profileForArtifact(artifact);
+    if (nextStates.length > profile.maxTokenOutputs)
+      throw new Error("transfer exceeds profile output bound");
     const fields =
       encodeKcc20StateRecordArrays(nextStates).map(dataTemplateArg);
     return [
       ...fields,
-      { type: "signature", prefixHex: "00" },
-      dataTemplateArg(dispatchTagFor(artifact, "transfer")),
+      witness ?? { type: "signature", prefixHex: "00" },
+      dataTemplateArg(
+        dispatchTagFor(
+          artifact,
+          profileForArtifact(artifact).transferEntrypoint,
+        ),
+      ),
     ];
   }
 
   function kcc20TransferDelegatorOrderedArgs(artifact) {
     return [
       { type: "signature" },
-      dataTemplateArg(dispatchTagFor(artifact, "transfer_delegator")),
+      dataTemplateArg(
+        dispatchTagFor(
+          artifact,
+          profileForArtifact(artifact).delegatorEntrypoint,
+        ),
+      ),
     ];
   }
 

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from "./artifacts.js";
+export * from "./token-profiles.js";
+export * from "./token-profiles.generated.js";
 export * from "./action-source-resolver.js";
 export * from "./abi.js";
 export * from "./builder.js";
@@ -34,3 +36,8 @@ 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";
+
+export * from "./token-authorization.js";
+
+export * from "./profile-transfer.js";
+export * from "./transfer-payload.js";