compact-core:compact-structure

Compact Smart Contract Structure

Every Compact program follows a consistent anatomy that maps directly to on-chain state, ZK circuit generation, and off-chain prover integration.

Contract Anatomy

A Compact contract is organized in this order:

pragma language_version >= 0.22;

import CompactStandardLibrary;

// 1. Custom types (enums, structs)
export enum State { active, inactive }
export struct Config { threshold: Uint<64>, admin: Bytes<32> }

// 2. Ledger declarations (on-chain state)
export ledger owner: Bytes<32>;
export sealed ledger config: Config;
export ledger state: State;
export ledger balances: Map<Bytes<32>, Uint<64>>;

// 3. Witness declarations (off-chain data providers)
witness local_secret_key(): Bytes<32>;

// 4. Constructor (one-time initialization)
constructor(threshold: Uint<64>) {
  owner = disclose(get_public_key(local_secret_key()));
  config = disclose(Config { threshold: threshold, admin: owner });
  state = State.active;
}

// 5. Helper circuits (internal logic)
circuit get_public_key(sk: Bytes<32>): Bytes<32> {
  return persistentHash<Vector<2, Bytes<32>>>([
    pad(32, "myapp:pk:"), sk
  ]);
}

// 6. Exported circuits (transaction entry points)
export circuit do_something(): [] {
  assert(state == State.active, "Contract inactive");
  // ... logic
}

Pragma and Imports

Every contract starts with a version pragma and standard library import:

pragma language_version >= 0.22;
import CompactStandardLibrary;

Tip: Run compact compile --language-version to check which language version your compiler supports.

The pragma specifies a minimum version without patch numbers. The standard library provides persistentHash, persistentCommit (takes rand: Bytes<32> parameter), transientHash, and transientCommit. Language built-ins include pad, disclose, assert, and default.

Data Types Quick Reference

Category	Types
Primitives	Field, Boolean, Bytes<N>, Uint<N>, Uint<0..MAX>
Collections	Vector<N, T>, Maybe<T>, Either<L, R>
Ledger ADTs	Counter, Map<K, V>, Set<T>, List<T>, MerkleTree<N, T>, HistoricMerkleTree<N, T>
Opaque	Opaque<"string">, Opaque<"Uint8Array">
Custom	enum, struct

For detailed type documentation, operations, and casting rules, consult references/data-types.md.

Ledger Declarations

Ledger fields define on-chain state. Three modifiers control visibility and mutability:

export ledger publicField: Field;           // Public, readable externally
ledger privateField: Field;                 // Not exported, internal only
export sealed ledger immutable: Bytes<32>;  // Set once in constructor, immutable

All ledger operations (reads, writes, ADT method calls) are publicly visible on-chain except for MerkleTree and HistoricMerkleTree insertions, which store values using cryptographic hashes.

For ADT operations (Counter, Map, Set, List, MerkleTree), consult references/ledger-declarations.md.

Circuits

Circuits are on-chain functions that produce ZK proofs. Return type is [] (empty tuple), not Void.

export circuit transfer(to: Bytes<32>, amount: Uint<64>): [] { ... }
circuit internal_helper(): Bytes<32> { ... }
export pure circuit compute(x: Field): Field { ... }

• export makes the circuit a transaction entry point
• pure signals no side effects — the compiler's identify-pure-circuits pass checks for ledger access, witness calls, and calls to impure circuits. Primarily affects ZK proving key generation and pureCircuits export
• Non-exported circuits are internal helpers

For circuit rules, witness declarations, constructors, and pure circuits, consult references/circuits-and-witnesses.md.

Witnesses

Witnesses provide off-chain data to circuits. Declaration only in Compact — implementation is in TypeScript:

witness local_secret_key(): Bytes<32>;
witness get_user_data(id: Bytes<32>): Maybe<UserRecord>;
witness store_locally(data: Field): [];

Witnesses run locally on the prover's machine. Their values are confidential but untrusted by the contract.

Key Rules

Disclosure

Values flowing from witnesses to ledger operations or conditionals require disclose():

// Conditional on witness value
if (disclose(caller == owner)) { ... }

// Writing witness-derived value to ledger
owner = disclose(get_public_key(local_secret_key()));

Enum Syntax

Use dot notation, not Rust-style double colons:

state = State.active;       // Correct
state = State::active;      // Wrong - parse error

Type Casting

Use as keyword. Some casts require intermediate steps:

const f: Field = myUint as Field;              // Uint -> Field (safe)
const b: Bytes<32> = (amount as Field) as Bytes<32>;  // Uint -> Bytes (via Field)
const u: Uint<0..1> = flag as Uint<0..1>;      // Boolean -> Uint

Exports for TypeScript

To access types from the TypeScript DApp, export them:

export enum GameState { waiting, playing }
export struct Config { value: Field }
export { Maybe, Either }   // Re-export stdlib types

Common Mistakes

Mistake	Correct
ledger { field: Type; }	export ledger field: Type;
circuit fn(): Void	circuit fn(): []
pragma >= 0.20.0	pragma >= 0.20
enum State { ... } (no export)	export enum State { ... }
if (witness_val == x)	if (disclose(witness_val == x))
Cell<Field>	Field (Cell implicit, cannot be written)
public_key(sk)	persistentHash<...>([pad(...), sk])
counter.value()	counter.read()
Choice::rock	Choice.rock
pure function helper()	pure circuit helper()
witness fn(): T { body }	witness fn(): T; (no body)

For comprehensive mistake documentation with explanations, consult references/common-mistakes.md.

Common Patterns

• Authentication — Hash-based identity verification using persistentHash
• Commit-Reveal — Two-phase schemes for hidden-then-revealed values
• Disclosure in conditionals — Wrapping witness comparisons in disclose()
• Merkle tree membership — Privacy-preserving set membership proofs
• Counter-based rounds — Breaking user linkability across transactions

For complete pattern implementations with code, consult references/patterns.md.

Reference Files

Topic	File
All data types, operations, casting rules	references/data-types.md
Ledger modifiers, ADT operations (Counter, Map, Set, etc.)	references/ledger-declarations.md
Circuit types, witnesses, constructors, pure circuits	references/circuits-and-witnesses.md
Common syntax mistakes with explanations	references/common-mistakes.md
Authentication, commit-reveal, Merkle trees, disclosure	references/patterns.md