compact-core:compact-witness-ts

TypeScript Witness Implementation & Contract Runtime

This skill covers the TypeScript half of every Compact contract: implementing witnesses, understanding compiler-generated types, and using the Contract runtime. For Compact witness declarations and disclosure rules, see compact-structure. For privacy patterns using witnesses, see compact-privacy-disclosure. For standard library functions referenced in witnesses, see compact-standard-library.

Compiler Output

Running compact compile src/mycontract.compact src/managed/mycontract produces a managed/ directory containing the generated TypeScript API:

src/managed/mycontract/
├── contract/
│   ├── index.js        # Runtime implementation
│   ├── index.js.map    # Source map
│   └── index.d.ts      # Type declarations
├── compiler/           # Compiler metadata
├── keys/               # ZK proving/verifying keys
└── zkir/               # ZK intermediate representation (.bzkir files)

Key exports from contract/index.js:

import { Ledger, Witnesses, ImpureCircuits, Circuits, Contract, pureCircuits } from "./managed/mycontract/contract/index.js";

• Ledger — TypeScript type matching the contract's ledger declarations
• Witnesses — Interface defining required witness implementations
• ImpureCircuits — Type describing circuit functions that require witnesses (parameterized by private state PS)
• Circuits — Type describing available circuit functions
• Contract — Class that binds witnesses to circuits
• pureCircuits — Module-level const export for local-only pure circuit calls (no proof generated)
• ledger() — Function to parse on-chain state into typed objects

Type Mapping Quick Reference

Compact Type	TypeScript Type	Notes
Field	bigint	Runtime bounds checked (max field value)
Uint<N> / Uint<0..N>	bigint	Runtime bounds checked
Boolean	boolean
Bytes<N>	Uint8Array	Runtime length checked (N bytes)
Opaque<"string">	string	Pass-through
Opaque<"Uint8Array">	Uint8Array	Pass-through
enum variants	number	Runtime membership checked
struct { a: A, b: B }	{ a: A, b: B }	Plain object
Vector<N, T> / tuples	T[]	Runtime length checked
Maybe<T>	{ is_some: boolean; value: T }	Must export from Compact to use type
Either<L, R>	{ is_left: boolean; left: L; right: R }	Flat object with discriminator
Counter	bigint	Via ledger()
Map<K, V>	Custom accessor object	Via ledger(); has member(), size(), isEmpty(), Symbol.iterator
Set<T>	Custom accessor object	Via ledger(); has member(), size(), isEmpty(), Symbol.iterator
MerkleTreePath<value_type>	Nested structure	Array of sibling hashes + directions

For complete type mapping details, runtime validation, and casting rules, see references/type-mappings.md.

Witness Implementation Pattern

Every witness function follows the same pattern:

import { WitnessContext } from "@midnight-ntwrk/compact-runtime";
import { Ledger } from "./managed/mycontract/contract/index.js";

// 1. Define private state type
type MyPrivateState = {
  readonly secretKey: Uint8Array;
};

// 2. Create factory function
const createMyPrivateState = (secretKey: Uint8Array): MyPrivateState => ({
  secretKey,
});

// 3. Implement witnesses object — keys must match Compact witness names exactly
export const witnesses = {
  local_secret_key: ({
    privateState,
  }: WitnessContext<Ledger, MyPrivateState>): [MyPrivateState, Uint8Array] => [
    privateState,
    privateState.secretKey,
  ],
};

Key rules:

• First parameter is always WitnessContext<Ledger, PrivateState>
• Return type is always [PrivateState, ReturnValue] — a tuple of updated private state and the declared return value
• Object keys in witnesses must match Compact witness function names exactly
• Additional parameters (after WitnessContext) match the Compact witness declaration parameters

For WitnessContext API details, common patterns, and state management, see references/witness-implementation.md.

Private State Design

Private state holds off-chain data that witnesses access. It persists across circuit calls within a session:

// Simple: single secret key
type SimpleState = { readonly secretKey: Uint8Array };

// Complex: multiple values, per-contract scoping
type ComplexState = {
  readonly secretKey: Uint8Array;
  readonly localData: Map<string, string[]>;
};

To mutate private state, return a new object in the witness tuple:

store_data: (
  { privateState, contractAddress }: WitnessContext<Ledger, ComplexState>,
  data: bigint[],
): [ComplexState, Uint8Array] => {
  const updatedData = new Map(privateState.localData);
  updatedData.set(contractAddress, data.map(String));
  return [
    { ...privateState, localData: updatedData },
    someComputedValue,
  ];
},

Contract Class Usage

The compiler-generated Contract class binds witnesses to circuits:

import { Contract, pureCircuits, ledger } from "./managed/mycontract/contract/index.js";

// Local testing only — instantiate Contract directly with witnesses
const contractInstance = new Contract(witnesses);

// Production — use CompiledContract.make() from @midnight-ntwrk/compact-js
import { CompiledContract } from "@midnight-ntwrk/compact-js";
const compiledContract = await CompiledContract.make(contractInstance);

// Pure circuits — module-level export, local computation, no proof, no transaction
const hash = pureCircuits.computeHash(inputData);

// Read ledger state from on-chain data
const ledgerState = ledger(contractStateData);
const currentValue = ledgerState.myField;

For Contract class details, circuits vs impureCircuits, and the ledger function, see references/contract-runtime.md.

Reference Files

Topic	Reference File
Complete type mapping table, CompactType<T>, runtime validation, casting rules	references/type-mappings.md
WitnessContext API, return tuples, common patterns, state transitions	references/witness-implementation.md
Contract class, circuits vs impureCircuits, pureCircuits, ledger()	references/contract-runtime.md

Verification

Witness implementations can be mechanically verified against their contract declarations:

/midnight-verify:verify <contract.compact> <witnesses.ts>

This verifies:

• Type correctness — the witness TypeScript type-checks against the compiled contract's generated Witnesses type
• Structural patterns — name matching (exact casing), return tuple shape ([PrivateState, ReturnValue]), WitnessContext first parameter, private state immutability, no side effects
• Behavioral correctness — the contract executes successfully with the witness implementation

Strongly recommend running /midnight-verify:verify after writing or modifying any witness implementation. Do not consider a witness implementation complete until verification passes.