compact-core:compact-language-ref

Compact Language Reference

This skill covers Compact language mechanics: the type system, operators, expressions, type casting, control flow, the module system, and the standard library. It does not cover contract architecture (ledger declarations, circuit design, witness integration, constructor layout) -- those belong in compact-structure. Use this skill when you need to know how the language works rather than how to structure a contract.

Types Quick Reference

Compact is statically and strongly typed. Every expression has a type known at compile time.

Category	Type	Description
Primitive	Field	Scalar field element; unbounded within the field prime
Primitive	Boolean	true or false
Primitive	Bytes<N>	Fixed-size byte array of N bytes
Primitive	Uint<N>	N-bit unsigned integer; values 0 to 2^N - 1
Primitive	Uint<0..MAX>	Bounded unsigned integer; 0 to MAX inclusive; Uint<8> = Uint<0..255>
Opaque	Opaque<"string">	Hashed in circuits, full string in witnesses and TypeScript
Opaque	Opaque<"Uint8Array">	Hashed in circuits, Uint8Array in witnesses and TypeScript
Collection	Vector<N, T>	Fixed-size array of N elements; shorthand for [T, T, ..., T]
Collection	Maybe<T>	Optional; some<T>(v) / none<T>(); inspect .is_some, .value
Collection	Either<L, R>	Sum type; left<L,R>(v) / right<L,R>(v); inspect .is_left, .left, .right
Custom	enum	Named variants; dot notation (State.active); export for TypeScript
Custom	struct	Named fields; named, positional, and spread construction
Custom	Tuples [T, ...]	Heterogeneous fixed-size sequences; [] is the unit type

Numeric literals have tight bounded types: 42 has type Uint<0..42>. Subtyping allows implicit widening -- Uint<0..42> fits wherever Uint<64> is expected. All Uint types are subtypes of Field.

For full type documentation, default values, subtyping rules, and TypeScript representations, see references/types-and-values.md.

Operators

Arithmetic Operators

Compact provides three arithmetic operators. Division and modulo do not exist in the language.

Operator	Name	Uint Result Type	Notes
+	Add	Uint<0..m+n>	Result widens; cast back before assignment
-	Subtract	Uint<0..m>	Runtime error if result would be negative
*	Multiply	Uint<0..m*n>	Result widens; cast back before assignment

When either operand is Field, the result is Field and wraps modulo the field prime. Cast Uint to Field explicitly only if you want to force field arithmetic semantics. Because arithmetic widens result types, cast before assigning: balance = (balance + amount) as Uint<64>;.

Comparison Operators

Operator	Name	Operand Requirement
==	Equal	Any two values with types in a subtype relation
!=	Not equal	Any two values with types in a subtype relation
<	Less than	Both operands must be Uint (not Field)
<=	Less or equal	Both operands must be Uint (not Field)
>	Greater than	Both operands must be Uint (not Field)
>=	Greater or equal	Both operands must be Uint (not Field)

Relational operators do not work on Field. Cast to Uint first: (f as Uint<64>) > 0.

Boolean Operators

Operator	Name	Behavior
&&	Logical AND	Short-circuit; evaluates right only if left is true
||	Logical OR	Short-circuit; evaluates right only if left is false
!	Negation	Unary prefix; flips true to false and vice versa

All operands must have type Boolean.

For full details on operator type rules, conditional expressions, literal typing, and anonymous circuits (lambdas), see references/operators-and-expressions.md.

Type Casting Quick Reference

Compact uses the as keyword for casts. TypeScript-style angle-bracket casts are not supported.

Direct Casts

From	To	Kind	Example
Uint<0..m>	Field	Static (always safe)	myUint as Field
Uint<0..m>	Uint<0..n> (m <= n)	Static (widening)	small as Uint<64>
Uint<0..m>	Uint<0..n> (m > n)	Checked (runtime)	big as Uint<8>
Field	Uint<0..n>	Checked (runtime)	f as Uint<64>
Field	Boolean	Conversion	f as Boolean (0 -> false, else true)
Field	Bytes<N>	Conversion (checked)	f as Bytes<32>
Boolean	Uint<0..n>	Conversion	flag as Uint<0..1> (false -> 0, true -> 1). Checked when n=0 (fails at runtime if true)
Boolean	Field	Conversion	flag as Field (false -> 0, true -> 1)
Uint<0..m>	Boolean	Conversion	myUint as Boolean (0 -> false, non-zero -> true)
Bytes<N>	Field	Conversion (checked)	b as Field
enum	Field	Conversion	Choice.rock as Field (variant index)

Optional Multi-Step Casts

From	To	Direct	Via Field
Uint<N>	Bytes<M>	amount as Bytes<32>	(amount as Field) as Bytes<32>

Both routes compile and produce the same result. The Field intermediate step is optional.

For the complete cast path table, see references/operators-and-expressions.md.

Control Flow

Variable Declarations

All local bindings use const. No let, var, or reassignment. Multiple bindings in one statement: const x = 1, y = x + 1;. Destructuring works for tuples (const [a, b] = pair;) and structs (const { x, y } = point;).

Conditional Branching

Standard if/else with Boolean condition. No else if keyword -- use nested if/else. Ternary c ? a : b is also available. An if without else is allowed only when the circuit returns [].

For Loops

Two forms, both requiring compile-time-known bounds:

• Range: for (const i of 0..5) -- 0 inclusive to 5 exclusive
• Vector/tuple: for (const v of values) -- each element in order

The compiler unrolls every loop into flat circuit gates. return inside a loop body is rejected. Nested loops multiply gate count.

What Does Not Exist

Omitted	Reason	Alternative
while / do-while	Iteration count unknown at compile time	for with fixed range
Recursion	Unbounded call depth	Loops or repeated calls with fixed unrolling
let / var	Mutable state complicates circuit generation	const and shadowing
switch / match	Not part of the language	Nested if/else or ternary c ? a : b
try / catch	No exception model	assert(condition, "message")
break / continue	Every loop iteration must execute	if inside the loop body

For full documentation on variable declarations, destructuring, shadowing, blocks, return statements, and loop restrictions, see references/control-flow.md.

Module System

Pragma

Every source file begins with a version pragma:

pragma language_version >= 0.22;

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

Standard Library Import

import CompactStandardLibrary; brings all stdlib types (Counter, Map, Set, MerkleTree, Maybe, Either, CoinInfo) and utility functions into scope.

Include

include "path/to/file"; inserts contents verbatim. The compiler searches for path/to/file.compact in the current directory and COMPACT_PATH directories. No namespace isolation.

Modules

Modules group definitions into namespaces. Identifiers are private unless exported. Modules can accept generic type parameters specialized at import time.

Import Forms

Form	Example	Effect
Standard library	import CompactStandardLibrary;	Brings all stdlib names into scope
Local module	import Runner;	Brings exported names from a local module into scope
Prefixed	import Runner prefix Run_;	All imported names get the Run_ prefix
Selective	import { test as t } from Test;	Imports specific names with optional renaming
Generic	import Identity<Field>;	Specializes a generic module
Path-based	import "utils/Auth";	Imports from a file; file must contain a single module

Exports

Top-level export on circuits, types, and ledger fields defines the public API for TypeScript. Re-export stdlib types with export { Maybe, Either };.

For all import forms, generic modules, path resolution, and file organization patterns, see references/modules-and-imports.md.

Standard Library Functions

All functions are available after import CompactStandardLibrary;.

Hashing and Commitment Functions

Function	Signature	Purpose
persistentHash	persistentHash<T>(value: T): Bytes<32>	SHA-256 based hash; stable across compiler upgrades; safe to store in ledger
transientHash	transientHash<T>(value: T): Field	Circuit-efficient hash; may change across upgrades; use only within one circuit
persistentCommit	persistentCommit<T>(value: T, rand: Bytes<32>): Bytes<32>	SHA-256 based commitment with randomness; stable; safe to store in ledger
transientCommit	transientCommit<T>(value: T, rand: Field): Field	Circuit-efficient commitment with randomness; use only within one circuit

Use persistent variants when storing in ledger or comparing across transactions. Use transient variants for in-circuit intermediates where lower cost matters.

Conversion Functions

Function	Signature	Purpose
degradeToTransient	degradeToTransient(x: Bytes<32>): Field	Convert persistent-domain Bytes<32> to transient-domain Field
upgradeFromTransient	upgradeFromTransient(x: Field): Bytes<32>	Convert transient-domain Field back to persistent-domain Bytes<32>

Use these when mixing persistent and transient operations in a single circuit.

Utility Functions

Function	Signature	Purpose
pad	pad(length, value): Bytes<N>	Create fixed-size Bytes<N> from a string literal; pads with zero bytes; both args must be literals
disclose	disclose(value: T): T	Mark a witness-derived value as publicly visible; required for ledger writes, cross-contract calls, and returns
assert	assert(condition: Boolean, message: string): []	Abort the transaction if condition is false; the only error-handling mechanism
default	default<T>: T	Return the default value for any type (false, 0, all-zero bytes, first enum variant, etc.); keyword expression, not a function call

disclose is required whenever a witness-derived value is stored in the public ledger, returned from an exported circuit, or passed to another contract via a cross-contract call. Commitments protect their inputs and the commitment result from disclosure. No disclose() wrapper is needed, even when storing the commitment in the ledger.

For full documentation on each function including examples, disclosure rules, and persistent vs. transient guidance, see references/stdlib-functions.md.

Troubleshooting Quick Reference

Common wrong-to-correct patterns:

Wrong	Correct
ledger { field: Type; }	export ledger field: Type;
circuit fn(): Void	circuit fn(): []
pragma >= 0.22.0	pragma language_version >= 0.22;
Choice::rock	Choice.rock
public_key(sk)	persistentHash<Vector<2, Bytes<32>>>([pad(32, "myapp:pk:"), sk])
counter.value()	counter.read()
if (witness_val == x)	if (disclose(witness_val == x))
witness fn(): T { body }	witness fn(): T; (declaration only)

For the complete compiler error reference, debugging strategies, and detailed explanations of disclosure and cast errors, see references/troubleshooting.md.

Reference Routing

Topic	Reference File
Type system: primitives, opaque, collections, custom types, defaults, subtyping, TypeScript mappings	references/types-and-values.md
Arithmetic, comparison, boolean operators, cast path table, conditional expressions, literals, lambdas	references/operators-and-expressions.md
const declarations, if/else, for loops, return, blocks, destructuring, what does not exist	references/control-flow.md
Pragma, include, modules, import forms, exports, file organization patterns	references/modules-and-imports.md
persistentHash, transientHash, persistentCommit, transientCommit, pad, disclose, assert, default	references/stdlib-functions.md
Compiler error reference, wrong-to-correct syntax, non-existent functions, debugging strategies	references/troubleshooting.md