@kaspacom/kcc20-tx-builder 0.2.5 → 0.4.0

package/docs/INTEGRATION.md

@@ -0,0 +1,215 @@
+# Integrating the TX Builder
+
+This guide describes the API shipped in `@kaspacom/kcc20-tx-builder@0.2.5`.
+The host application supplies wallet identity, network configuration, contract
+artifacts, chain data, and an initialized Kaspa WASM runtime. The package
+constructs operations and transaction JSON. The host signs, validates,
+broadcasts, and tracks the result.
+
+## Install from the public registry
+
+```sh
+npm install --save-exact @kaspacom/kcc20-tx-builder@0.2.5 \
+  --registry=https://registry.npmjs.org/ \
+  --@kaspacom:registry=https://registry.npmjs.org/
+```
+
+The scoped registry option matters when a project or user `.npmrc` maps
+`@kaspacom` to GitHub Packages. Public npm installation does not require a
+GitHub token. Commit your lockfile and pin the same package version across
+browser and server adapters.
+
+Node consumers need Node.js 20 or newer. Browser consumers need a bundler
+that supports ESM and their platform's Kaspa WASM build. ESM and CommonJS
+exports are available:
+
+```js
+import { KCC20_PSKT_BUILDER_INPUT_SCHEMA } from '@kaspacom/kcc20-tx-builder';
+```
+
+```js
+const { KCC20_PSKT_BUILDER_INPUT_SCHEMA } = require('@kaspacom/kcc20-tx-builder');
+```
+
+## Start with amount calculations
+
+This example runs without a wallet, RPC connection, or WASM runtime:
+
+```js
+import {
+  parseKcc20DisplayAmountToBaseUnits,
+  formatKcc20BaseUnitsForDisplay,
+  calculateKcc20OrderTotalSompi,
+} from '@kaspacom/kcc20-tx-builder';
+
+const baseUnits = parseKcc20DisplayAmountToBaseUnits('1.25', 8, 'amount');
+console.log(baseUnits); // '125000000'
+console.log(formatKcc20BaseUnitsForDisplay(baseUnits, 8)); // '1.25'
+
+const order = calculateKcc20OrderTotalSompi('1.25', '100000000', 8);
+console.log(order?.totalSompi); // '125000000'
+```
+
+Use decimal strings for token amounts and sompi values. Use `bigint` for
+arithmetic. A token's display decimals are separate from the KAS unit scale;
+read them from its verified metadata. The helpers accept token decimals from
+0 through 8. Check `roundedDown` and `roundedTokenAmountBaseUnits` when quoting
+orders because some prices require rounding to an exact sompi amount.
+
+## Configure a persistent engine
+
+The following adapter is TypeScript. Its parameters are dependencies supplied
+by your application, not objects exported by the package:
+
+```ts
+import {
+  createKcc20PsktBuilderEngine,
+  type KaspaWasmRuntime,
+  type Kcc20PsktBuilderInput,
+} from '@kaspacom/kcc20-tx-builder';
+
+export function createWalletBuilder(
+  loadedKaspa: KaspaWasmRuntime,
+  applicationRpcConnection: {
+    getUtxosByAddresses(request: { addresses: string[] }): Promise<unknown>;
+  },
+  artifactProvider: (key: string) => Promise<unknown>,
+) {
+  const engine = createKcc20PsktBuilderEngine({
+    wasm: loadedKaspa,
+    artifacts: {},
+    artifactProvider,
+    config: { KASPA_NETWORK: 'testnet-10' },
+    sourceProvider: {
+      getUtxosByAddresses: (request) =>
+        applicationRpcConnection.getUtxosByAddresses(request),
+    },
+  });
+
+  return (preparedInput: Kcc20PsktBuilderInput) => engine.build(preparedInput);
+}
+```
+
+Initialize WASM before calling this adapter. Select and connect your RPC
+endpoint in the host. The builder does not connect or disconnect a supplied
+`sourceProvider`. Reuse a persistent engine to retain its artifact cache.
+Supply fresh indexed covenant state and wallet funding sources for each build.
+
+For a browser, serve the package's JSON artifacts through your asset pipeline:
+
+```ts
+export async function artifactProvider(key: string): Promise<unknown> {
+  const response = await fetch(`/kcc20-artifacts/${encodeURIComponent(key)}`);
+  if (!response.ok) throw new Error(`Cannot load artifact ${key}: ${response.status}`);
+  const rawBytes = new Uint8Array(await response.arrayBuffer());
+  return {
+    artifact: JSON.parse(new TextDecoder().decode(rawBytes)),
+    rawBytes,
+  };
+}
+```
+
+Copy the installed package's `artifacts/*.json` files to that asset directory
+as part of the host build. A server can load those same files once using its
+own filesystem adapter and pass an envelope containing both the parsed
+`artifact` and its exact `rawBytes` through `artifacts`. Snapshot builders
+require those bytes to verify the frozen SHA-256 artifact pins.
+Filesystem access belongs in the host, outside this package.
+
+`rpcClientFactory` is an alternative for hosts that need the builder to create
+an RPC client. Prefer `sourceProvider` when the application already owns a
+connection. Configure network and RPC explicitly rather than relying on the
+engine's TN10 defaults.
+
+## Prepare the input
+
+The engine accepts the in-process envelope:
+
+```ts
+import {
+  KCC20_PSKT_BUILDER_INPUT_SCHEMA,
+  type Kcc20PsktBuilderInput,
+} from '@kaspacom/kcc20-tx-builder';
+
+export function toBuilderInput(
+  preparedRequest: Record<string, unknown>,
+): Kcc20PsktBuilderInput {
+  return {
+    schema: KCC20_PSKT_BUILDER_INPUT_SCHEMA,
+    builder: {},
+    request: preparedRequest,
+  };
+}
+```
+
+`request.builderKey` selects the operation. The remaining request fields are
+operation-specific: wallet owner and address, network, params, and decoded
+covenant sources. This envelope adapter does not prepare or validate them.
+Use the operation helpers listed in [the API guide](API.md) to construct intent,
+then let your host resolve the required sources and assemble the engine request.
+There is no universal funded request that works for every operation.
+
+Operation helpers such as `buildKcc20TransferTokenOperation` return a wallet
+operation envelope with an initially missing funded PSKT. That object is not
+directly an engine input. The host must convert its intent and sources into
+`request`, build the PSKT, and attach the funded result to its signing flow.
+
+Do not confuse `KCC20_PSKT_BUILDER_INPUT_SCHEMA` with
+`KCC20_BUILDER_INPUT_SCHEMA` from `models.ts`. The latter describes the separate
+shared source/context model. Passing that model directly to `engine.build`
+fails its schema check.
+
+## Consume the result
+
+The engine returns an operation-specific record with
+`schema: 'kcc20-in-process-pskt-builder-output/v1'`, `psktTransactionJson`,
+`signInputs`, and, where needed, covenant `scripts` and `metadata`.
+`psktTransactionJson` is JSON text, not an already signed transaction.
+The return type is `Record<string, unknown>`; narrow and validate the fields
+your wallet adapter consumes.
+
+1. Present the intended action, amounts, recipients, and fees to the user.
+2. Build using fresh sources and check the resulting inputs and outputs.
+3. Use the wallet's PSKT signing interface with the returned signing instructions.
+4. Independently validate the signed transaction and authorization in your trusted host.
+5. Broadcast through your host and reconcile confirmation or reorg state through your indexer.
+
+The package does not provide wallet discovery, signing UI, authentication,
+broadcast orchestration, or confirmation tracking. Browser-built transaction
+JSON remains untrusted input at a backend boundary.
+
+## Artifacts and privileged builders
+
+The package pins script hashes for five shipped artifacts. The engine validates
+artifacts against those hashes; mixing independently compiled artifacts with
+this package version can fail the build. Upgrade artifacts and builder together.
+JSON subpath loading depends on the host's module loader, so the asset-provider
+approach avoids imposing a JSON import syntax on consumers.
+
+`allowBackendOnly` defaults to disabled. The matcher builder
+`kcc20orderbook.matcher-settle-crossed` requires an engine explicitly configured
+with `allowBackendOnly: true` in a trusted server. That flag does not authorize
+a caller. Keep matcher scheduling, authorization, and any private keys in the
+server host. `buildKcc20Pskt` does not expose this opt-in; configure an engine
+for privileged work.
+
+## Handle errors
+
+Some helpers throw `Kcc20BuilderError`, exposing `code` and string-valued
+`details`. Other helpers and the engine throw ordinary `Error` instances;
+do not assume every failure has a structured code. Handle both:
+
+```ts
+import { Kcc20BuilderError } from '@kaspacom/kcc20-tx-builder';
+
+export function describeBuildFailure(error: unknown): string {
+  if (error instanceof Kcc20BuilderError) return `${error.code}: ${error.message}`;
+  if (error instanceof Error) return error.message;
+  return 'Transaction construction failed';
+}
+```
+
+Refresh sources after spent or stale UTXO failures. An artifact mismatch needs
+a package/artifact compatibility check. A missing WASM capability needs a
+compatible runtime. Do not retry signing or broadcast automatically after an
+ambiguous submission; reconcile its transaction ID in your host first.

package/docs/LIVE_TRANSFER.md

@@ -0,0 +1,106 @@
+# Transfer using your own indexer and RPC
+
+The browser and Node examples use the same
+[`liveTransferOperation`](../examples/shared/live-transfer.ts) adapter. It retrieves
+decoded holder state from an endpoint you configure, confirms the output through
+RPC, and passes the validated holder to the existing transfer helper. No KaspaCom
+application backend is involved.
+
+## Decoded-state endpoint
+
+Serve an HTTP GET endpoint returning:
+
+```ts
+import type { Kcc20IndexedCovenantUtxo } from "@kaspacom/kcc20-tx-builder/action-source-resolver";
+type HolderResponse = {
+  network: "testnet-10";
+  utxos: Kcc20IndexedCovenantUtxo[];
+};
+```
+
+Map your indexer's transaction ID, output index, KAS amount, native covenant ID,
+address and decoded state to this shape. An application alias must not replace
+the native covenant ID. Amounts must be decimal strings. This adapter supports
+unborrowed native holders owned by a Schnorr public key. It rejects duplicate
+outpoints and malformed rows. Paginate in your indexer adapter if a response
+would exceed 1,000 rows.
+
+A complete deterministic response can be generated without a backend:
+
+```sh
+cd examples
+npm run --silent recipe -- transfer --arguments > transfer-arguments.json
+node --input-type=module -e 'import fs from "node:fs"; const a=JSON.parse(fs.readFileSync("transfer-arguments.json")); console.log(JSON.stringify({network:"testnet-10",utxos:a[1].activeUtxos},null,2))' > holder-response.json
+```
+
+This includes actual address strings, outpoints, base-unit amounts, native IDs,
+owner identifiers, extension commitments and borrow fields. All outpoints are
+synthetic. They demonstrate the schema and are rejected by a live node.
+
+For real use, fill these fields from your indexer's decoded current outputs.
+RPC alone does not provide token amount, owner scheme or extension commitment.
+The adapter rebuilds the holder script from decoded state and the packaged
+artifact, verifies its address, then checks the RPC outpoint, script, KAS amount
+and native covenant ID. A fabricated or stale snapshot cannot bypass those
+comparisons. The selected RPC remains a trusted source of chain data.
+
+## Transfer configuration
+
+Save `transfer.json` in `examples`. Replace the marked values with your own
+TN10 account and verified token metadata:
+
+```json
+{
+  "network": "testnet-10",
+  "stateUrl": "https://your-indexer.example/holders",
+  "wallet": {
+    "walletAddress": "kaspatest:YOUR_ADDRESS",
+    "kcc20Owner": "YOUR_64_HEX_OWNER"
+  },
+  "covenantId": "YOUR_64_HEX_NATIVE_COVENANT_ID",
+  "decimals": 2,
+  "recipientOwner": "RECIPIENT_64_HEX_OWNER",
+  "tokenAmount": "12.50"
+}
+```
+
+TypeScript applications can import `LiveTransferConfig` from the shared adapter.
+`decimals` comes from verified token metadata. It determines the requested base
+units; it cannot be inferred from a holder amount. The recipient is an x-only
+public key. The adapter checks that the sender address belongs to the supplied
+owner key. This example requires one holder large enough for the transfer and
+separate KAS funding. Use the consolidation recipe for fragmented balances.
+
+## Backend
+
+```sh
+cd examples
+KASPA_WRPC_URL=wss://your-tn10-node npm run --silent backend -- transfer transfer.json > unsigned.json
+```
+
+The CLI checks the connected node's network, retrieves and validates the holder,
+builds locally, writes the unsigned transaction and signing instructions, and
+closes RPC. A server handler can call the same adapter with a process-owned
+connection. Apply authorization before any server signing. Do not accept arbitrary
+state URLs from unauthenticated callers: configure or allowlist indexer endpoints
+in your own server to avoid turning it into an HTTP proxy.
+
+## Frontend
+
+Start the Vite example, enter the RPC URL, paste the same configuration JSON into
+the text area, and click **Build transfer from indexer**. The state endpoint must
+allow your application's origin through CORS. HTTPS applications need HTTPS state
+URLs and WSS RPC. Review the complete unsigned transaction before the separate
+**Sign** and **Broadcast** actions.
+
+The same function can be imported directly:
+
+```ts
+const operation = await liveTransferOperation(wasm, rpc, loadArtifact, config);
+const unsigned = await createBuilder(wasm, rpc, loadArtifact)(operation);
+```
+
+The network check belongs to the host connection setup, as shown in both runnable
+apps. An input can be spent after validation: on a node rejection, refresh state
+and rebuild. If submission times out, check the transaction ID and spent inputs
+before retrying. These examples do not claim live wallet or node acceptance.

package/docs/RECIPES.md

@@ -0,0 +1,175 @@
+# Operation recipes
+
+The [recipe registry](../examples/shared/recipes.ts) imports the package's existing
+helpers with their original TypeScript signatures. These helpers describe an
+operation; the shared `createBuilder` adapter constructs its transaction locally.
+All examples target TN10. Supply current decoded state from your own indexer or
+transaction decoder, plus current UTXOs from your own RPC connection.
+
+## Run a helper and build its transaction
+
+Save a JSON array containing the helper's arguments, in signature order, to
+`arguments.json`. The CLI calls the selected helper and emits its operation:
+
+```sh
+cd examples
+npm run --silent recipe -- deploy arguments.json > operation.json
+KASPA_WRPC_URL=wss://your-tn10-node npm run --silent backend -- build operation.json > unsigned.json
+```
+
+For frontend applications, use the same typed registry directly:
+
+```ts
+import { recipes } from "./shared/recipes";
+const operation = recipes.deploy(
+  wallet,
+  {
+    ticker: "DEMO",
+    tokenName: "Example token",
+    decimals: 2,
+    maxSupply: "1000",
+    premintSupply: "1000",
+    mintPolicy: "fixed",
+    mintPricePerTokenSompi: "0",
+  },
+  { network: "testnet-10" },
+);
+const unsigned = await build(operation);
+```
+
+## Complete offline recipes
+
+Every registry entry has a complete typed argument tuple in
+[`recipe-fixtures.ts`](../examples/shared/recipe-fixtures.ts), including decoded
+state and matching RPC entries derived from the packaged contract scripts.
+Run any recipe without a wallet, node or private repository:
+
+```sh
+cd examples
+npm run --silent recipe -- wrap --offline > unsigned-wrap.json
+npm run --silent recipe -- wrap --arguments > wrap-arguments.json
+npm run --silent recipe -- wrap wrap-arguments.json > wrap-operation.json
+```
+
+Replace `wrap` with `deploy`, `transfer`, `mint`, `publicMint`, `mintAvailability`,
+`consolidate`, `reveal`, `deployMarket`, `unwrap`, `order`, `buyOrder`, `fill`,
+`fillBid`, `sweep`, `sweepBids`, `cancel`, `cancelBid`, `consolidateWrapped`,
+`deployFeeTicketRoot`, `updateFeeTicketRoot`, `createFeeTicket`, `burnFeeTicket`,
+or `transferFeeTicket`. The frontend's **Offline recipe** selector runs the same
+fixtures and always keeps signing and broadcasting disabled.
+
+`order`, `fill`, `sweep`, and `cancel` demonstrate the ask side. The bid variants
+exercise the opposite side. `mint` uses the authority owner; `publicMint` uses a
+different owner against an active public minter. The availability recipe pauses
+that minter. Sweep fee totals come from the package's per-leg fee helper, including
+the minimum protocol fee.
+
+All 24 recipes build real unsigned transactions with the bundled WASM. Tests
+assemble signatures with public test-vector keys and compare browser/Node unsigned
+transactions and signing instructions. Fixtures are independent snapshots, not a
+chain simulator. They reuse synthetic funding and cannot be submitted. Replace
+them with current decoded state and RPC entries for live use; see the
+[live transfer adapter](LIVE_TRANSFER.md) for a complete retrieval example.
+
+## Native tokens
+
+| Recipe             | Existing helper                          | Inputs beyond the wallet                                                        |
+| ------------------ | ---------------------------------------- | ------------------------------------------------------------------------------- |
+| `deploy`           | `buildKcc20DeployTokenOperation`         | Draft supplies, decimals, mint policy, treasury and protocol fee configuration. |
+| `transfer`         | `buildKcc20TransferTokenOperation`       | Token identity/decimals, display amount, recipient owner, current holder UTXOs. |
+| `mint`             | `buildKcc20MintTokenOperation`           | Token mint policy, amount, active authority UTXOs, optional recipient.          |
+| `mintAvailability` | `buildKcc20MintAvailabilityOperation`    | Token, active mint-authority state, requested enabled state.                    |
+| `consolidate`      | `buildKcc20NativeConsolidationOperation` | Token, owner holder UTXOs, optional target amount.                              |
+| `reveal`           | `buildKcc20VerifyTokenOperation`         | Token identity and a spendable holder/authority snapshot.                       |
+
+```ts
+const mint = recipes.mint(
+  wallet,
+  {
+    token,
+    tokenAmount: "10.00",
+    activeUtxos: minterUtxos,
+  },
+  { network: "testnet-10" },
+);
+const unsignedMint = await build(mint);
+```
+
+`token` must include its actual decimals and mint policy. Controlled minting
+requires the authority owner. A public mint can be paused. Mint-authority state
+includes extension data that a holder snapshot does not contain. Public mint
+amount limits and paid-mint minimums are validated by the helper.
+
+## Wrappers and orderbook
+
+| Recipe               | Existing helper                              | Required state                                                                          |
+| -------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `deployMarket`       | `buildKcc20WrapperMarketDeployOperation`     | Token identity, market configuration and fee-ticket identity if used.                   |
+| `wrap`               | `buildKcc20WrapTokenOperationFromSnapshot`   | Native holder, wrapper candidates, native covenant IDs, token decimals and amount.      |
+| `unwrap`             | `buildKcc20UnwrapTokenOperationFromSnapshot` | Wrapped holder, wrapper reserve, market identity and amount.                            |
+| `order`              | `buildKcc20OrderOperation`                   | Trading context and buy/sell draft; buy uses a market root, sell uses a wrapped holder. |
+| `fill`               | `buildKcc20FillOperation`                    | Trading context, selected bid/ask, fill amount, funding/holder sources.                 |
+| `sweep`              | `buildKcc20SweepOperation`                   | Trading context, ordered bid/ask legs and sufficient buyer/seller sources.              |
+| `cancel`             | `buildKcc20CancelOperation`                  | Owner's bid/ask and matching market context.                                            |
+| `consolidateWrapped` | `buildKcc20WrappedConsolidationOperation`    | Matching wrapped-holder sources and market context.                                     |
+
+```ts
+const order = recipes.order(
+  wallet,
+  tradingContext,
+  {
+    wrappedMarketId: tradingContext.wrapper.marketId,
+    side: "buy",
+    tokenAmount: "10.00",
+    unitPriceSompi: "100000000",
+  },
+  { network: "testnet-10" },
+);
+const unsignedOrder = await build(order);
+```
+
+The context contains token decimals, the wrapper identity and its buildability,
+current wrapped UTXOs, and optional fee-ticket UTXOs. Preserve the distinction
+between native token identity, wrapper identity, and market identity. Use helper
+parameter types rather than constructing a request from UI labels. The bid/ask
+side controls which builder runs and which sources it consumes. Fees, locked
+KAS deposits, price scale, partial-fill change, and token change must be shown
+before signing. Never reuse a quote after its input order has changed.
+
+## Fee tickets
+
+| Recipe                | Existing helper                     | Required state                                                           |
+| --------------------- | ----------------------------------- | ------------------------------------------------------------------------ |
+| `deployFeeTicketRoot` | `buildFeeTicketRootDeployOperation` | Utility token ID, denomination, discount and optional supported markets. |
+| `updateFeeTicketRoot` | `buildFeeTicketRootUpdateOperation` | Root configuration, current root UTXOs and new denomination.             |
+| `createFeeTicket`     | `buildFeeTicketCreateOperation`     | Root configuration, root UTXOs, utility holders and quantity.            |
+| `burnFeeTicket`       | `buildFeeTicketBurnOperation`       | Owner tickets and root configuration.                                    |
+| `transferFeeTicket`   | `buildFeeTicketTransferOperation`   | Owner tickets, recipient and root configuration.                         |
+
+```ts
+const root = recipes.deployFeeTicketRoot(
+  wallet,
+  {
+    utilityTokenId,
+    utilityTokenAmount: "100",
+    discountBps: 2500,
+  },
+  { network: "testnet-10" },
+);
+const unsignedRoot = await build(root);
+```
+
+`utilityTokenAmount` is an integer denomination in base units. Batch creation
+requires a matching artifact and root capability; use the engine's existing
+`resolveFeeTicketBatchCreateCapability` rather than assuming every root supports
+multiple tickets. Creating tickets burns the selected utility amount.
+
+## Backend-only matcher
+
+`kcc20orderbook.matcher-settle-crossed` is intentionally excluded from the public
+example registry. The engine accepts it only with `allowBackendOnly: true`.
+Use a separate server instance, validated crossed-order snapshots, and explicit
+operator configuration. Never enable it in the frontend, expose operator
+credentials through a client configuration object, or forward all of `process.env`
+to the engine. Public minting, transfer, and user order actions do not require
+this matcher or KaspaCom's backend.

package/docs/TRANSACTION_GUIDE.md

@@ -0,0 +1,163 @@
+# Build transactions in your application
+
+TX Builder constructs transactions locally in a browser or Node process. Your
+application supplies WASM, the packaged contract artifacts, and chain data.
+You do not need KaspaCom's backend to plan or build a transaction.
+
+Start with the [runnable examples](../examples/README.md). Both applications use
+[the same construction code](../examples/shared/build.ts) and build a deploy
+followed by a transfer. Their offline transactions are identical across runtimes.
+
+## Responsibilities
+
+| Part | Responsibility |
+| --- | --- |
+| Operation helpers | Validate the requested action, select supplied covenant sources, convert display amounts, and describe intent. |
+| Builder engine | Construct and serialize the funded unsigned transaction, attach covenant bindings, estimate fees, and return signing instructions. |
+| Application | Initialize WASM, load artifacts, retrieve funding UTXOs and decoded covenant state, show transaction intent, and manage RPC lifetime. |
+| Wallet or server signer | Confirm authorization and sign the required inputs, including covenant inputs. |
+| Application and node | Submit the signed transaction, handle rejection, and track acceptance. |
+
+A build is neither a signature nor proof of chain acceptance. Source snapshots
+can become stale between construction and submission. On a spent-input failure,
+refresh sources and rebuild; do not keep retrying the same transaction.
+
+## Install and initialize
+
+Use Node 22 for the examples. The package also supports its declared Node 20+
+range. Install `@kaspacom/kcc20-tx-builder` from the public npm registry; no GitHub
+Packages credentials are needed. Use the release version matching the examples.
+
+The host initializes WASM once. See [Node initialization](../examples/backend/runtime.ts)
+and [browser initialization](../examples/frontend/runtime.ts). Both use the
+included ISC-licensed `kaspa-wasm` bundle, version `1.1.1-toc.1`, and call
+`initWASM32Bindings({ validateClassNames: false })`. This allows bindings to work
+when bundlers rename WASM classes. WASM remains host-owned; importing the package
+does not initialize it or open a connection.
+
+[COMPATIBILITY.json](COMPATIBILITY.json) pins binary/file checksums, contract
+revision, compiler release, and artifact hashes. The runtime is included under
+`examples/vendor/kaspa` in this repository and package, so neither example
+fetches it from a private repository. The original runtime build's source commit
+is not recorded in the supplied bundle. File integrity is verified; a reproducible
+WASM source build is not claimed. The manifest also supplies an immutable public
+`downloadBaseUrl`. Download `kaspa.js`, `kaspa_bg.wasm`, `kaspa.d.ts`, and
+`LICENSE` from that base and verify each SHA-256 against `wasm.files` if you
+host the runtime separately. Keep the license with redistributed files.
+
+## Deploy a fixed-supply token
+
+```ts
+import { buildKcc20DeployTokenOperation } from '@kaspacom/kcc20-tx-builder/deploy-operation';
+
+const operation = buildKcc20DeployTokenOperation(
+  wallet, // { walletAddress: 'kaspatest:...', kcc20Owner: '<32-byte x-only public key>' }
+  {
+    ticker: 'DEMO', tokenName: 'Example token', decimals: 2,
+    maxSupply: '1000', premintSupply: '1000',
+    mintPolicy: 'fixed', mintPricePerTokenSompi: '0',
+  },
+  { network: 'testnet-10' },
+);
+const unsigned = await build(operation);
+```
+
+`build` comes from `createBuilder` in the shared example. That function creates
+one existing `createKcc20PsktBuilderEngine`, verifies packaged artifact hashes,
+and calls its `build` method. The complete adapter is executable code, not an
+unspecified server request.
+
+`engineInput(operation)` takes `operation.payload.signing.builderKey`, `params`,
+`owner`, `network`, and source/signer requirements and assembles
+`kcc20-in-process-pskt-builder-input/v1`. The separate shared-model input schema
+is not interchangeable with this engine schema. The helper's
+`missing-funded-pskt` status means construction is still required; historical
+`backend-funded-pskt-builder` labels do not require a KaspaCom backend.
+The local engine performs that construction.
+
+The fixed-supply example creates 1,000 tokens with two decimals: 100,000 base
+units. It locks KAS into the token output and returns KAS change to the funding
+wallet. Use decimal strings, not floating-point multiplication, for token
+amounts. KAS amounts and fees are integer sompi; 100,000,000 sompi is one KAS.
+The library's protocol fee defaults still apply to relevant operations; inspect
+the operation and resulting outputs before asking a wallet to sign.
+
+## Transfer from a decoded holder snapshot
+
+```ts
+import { buildKcc20TransferTokenOperation } from '@kaspacom/kcc20-tx-builder/token-operation';
+
+const operation = buildKcc20TransferTokenOperation(wallet, {
+  token: { covenantId: holder.covenantId, decimals: 2 },
+  activeUtxos: [holder],
+  recipientOwner, // 32-byte x-only public key, not an address string
+  tokenAmount: '12.50',
+}, { network: 'testnet-10' });
+const unsigned = await build(operation);
+```
+
+See [fixture.ts](../examples/shared/fixture.ts) for a complete holder snapshot:
+transaction ID, output index, address, KAS amount, native covenant ID, owner,
+token amount, extension commitment, and borrow state. The offline fixture derives
+that snapshot from its deploy result. Its outpoints are synthetic and must never
+be used as live funding.
+
+Use the [live transfer adapter and walkthrough](LIVE_TRANSFER.md) to retrieve and validate a complete holder snapshot.
+For live use, retrieve decoded state from your own indexer or decode the prior
+transaction and reveal script. RPC UTXOs alone do not contain every contract
+state field. Supply that state to the helper, then let the engine's source
+provider retrieve current RPC entries by address. Preserve the native covenant
+ID from RPC; an application's token identifier or script hash is not always the
+native covenant ID. The engine rebuilds the holder script and checks its address.
+
+The example transfers 1,250 base units, retains 98,750 as token change, and
+uses a separate KAS funding input. A fragmented token balance may require
+consolidation first. Funding selection can require one sufficiently large KAS
+UTXO even when the wallet's total balance is sufficient.
+
+## Inspect, sign, submit
+
+The engine returns `psktTransactionJson`, `signInputs`, optional `scripts`,
+`metadata`, and `submitTransactionSupported`. Inspect the full transaction,
+recipients, token change, covenant IDs, KAS change, and fee before signing.
+`inspect` computes the fee from input amounts minus output values.
+
+[The signing adapter](../examples/shared/signing.ts) includes the covenant input
+indexes from `scripts` as well as ordinary `signInputs`. After KasWare signs,
+it inserts the signature into the ordered ABI arguments and wraps the redeem
+script. Omitting this step produces a signed funding input but an invalid
+covenant spend. Preserve every builder-provided sighash and script template. The adapter preserves
+prebuilt witnesses on inputs the wallet does not sign, checks returned signature
+encoding and sighash bytes, and rejects changes to transaction intent. These
+checks do not replace cryptographic verification or node consensus validation.
+When using the WASM signer directly, map wire sighash `1` to `wasm.SighashType.All`;
+the WASM enum's numeric value is `0`, not the wire byte.
+
+The frontend checks the wallet account and TN10 network, then offers separate
+Sign and Broadcast actions. It submits through the selected RPC node. The backend
+example returns an unsigned transaction for an application or wallet to sign;
+it does not load private keys. The offline suite verifies construction and
+script assembly, not a wallet extension's current behavior or live acceptance.
+
+For server integrations, call the same shared `createBuilder` function from your
+handler with a process-owned RPC connection. Validate the caller's request and
+apply your own authorization before signing. Return the builder result as JSON;
+never forward your environment or signing credentials to a browser.
+
+## Failure handling
+
+| Failure | Application action |
+| --- | --- |
+| Insufficient KAS or no single funding UTXO | Refresh funding and obtain an adequate input; inspect the required output deposits and fee. |
+| No holder large enough | Check ownership and decimals; consolidate if the balance is fragmented. |
+| Active holder not found | Refresh decoded state and RPC UTXOs; the input may have been spent. |
+| Rebuilt script address mismatch | Check decoded state and artifact version; do not substitute another address. |
+| Artifact hash mismatch | Use the artifacts shipped with this package version. |
+| Wrong network or missing WASM capability | Correct host configuration before building. |
+| Wallet rejection | Keep the transaction unsigned and report cancellation. |
+| Node rejection or uncertain submission | Query acceptance and spent inputs before rebuilding or retrying. |
+
+Errors include both plain `Error` messages and structured builder errors. Do not
+assume every error has a `code`. Add transport timeouts appropriate to your host,
+and close failed connections. Browser applications should reuse one RPC
+connection rather than reconnecting for each build.