Skip to content
Skills Library
Programming · Learning & explanation

compact-core:compact-language-ref

/compact-core:compact-language-ref

This skill should be used when the user asks about Compact language mechanics, syntax reference, types (Field, Bytes, Uint, Boolean, Opaque, Vector, Maybe, Either, enums, structs), type casting with "as", operators, arithmetic, control flow, for loops, modules, imports, include, pragma, stdlib functions (persistentHash, transientHash, disclose, assert, pad, default), map and fold operations, or Compact compiler errors and wrong syntax patterns.

Licence
Apache-2.0
Last repository change
23.10.2026

Assessment and security

85/ 100Class: good
Format15 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

This skill should be used when the user asks about Compact language mechanics, syntax reference, types (Field, Bytes, Uint, Boolean, Opaque, Vector, Maybe, Either, enums, structs), type casting with "as", operators, arithmetic, control flow, for loops, modules, imports, include, pragma, stdlib functions (persistentHash, transientHash, disclose, assert, pad, default), map and fold operations, or Compact compiler errors and wrong syntax patterns.

Original author description

This skill should be used when the user asks about Compact language mechanics, syntax reference, types (Field, Bytes, Uint, Boolean, Opaque, Vector, Maybe, Either, enums, structs), type casting with "as", operators, arithmetic, control flow, for loops, modules, imports, include, pragma, stdlib functions (persistentHash, transientHash, disclose, assert, pad, default), map and fold operations, or Compact compiler errors and wrong syntax patterns.

How it works

  1. Types Quick Reference
  2. Operators
  3. Type Casting Quick Reference
  4. Control Flow
  5. Module System
  6. Standard Library Functions
  7. Troubleshooting Quick Reference
  8. Reference Routing
Original SKILL.md headings · 238 lines, 1,978 words
SKILL.md preview
---
name: compact-core:compact-language-ref
description: This skill should be used when the user asks about Compact language mechanics, syntax reference, types (Field, Bytes, Uint, Boolean, Opaque, Vector, Maybe, Either, enums, structs), type casting with "as", operators, arithmetic, control flow, for loops, modules, imports, include, pragma, stdlib functions (persistentHash, transientHash, disclose, assert, pad, default), map and fold operations, or Compact compiler errors and wrong syntax patterns.
version: 0.1.0
---

# Compact Language Reference

> **Last verified:** 2026-09-18 — core language syntax (control flow, types & values, operators/casts, `map`/lambda) compile-verified against Compact compiler `0.31.1` / language `0.23` / runtime `0.16.0` (`compact compile --skip-zk`, confirmed via `contract-info.json`); stdlib symbols cross-checked against the already-verified `compact-standard-library`.

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. `else if` chains compile, as do nested `if`/`else` blocks. 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:

```compact
pragma language_version 0.23;
```

> **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;` | `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` |
Files in this package (7)
  • SKILL.md 14 KB
  • references/control-flow.md 8 KB
  • references/modules-and-imports.md 9 KB
  • references/operators-and-expressions.md 11 KB
  • references/stdlib-functions.md 10 KB
  • references/troubleshooting.md 11 KB
  • references/types-and-values.md 10 KB

Versions

The database has no other skills named compact-core:compact-language-ref.

Database snapshot: 13.11.2026 · package version 3bb6de3b7221 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90compact-core:compact-structure
    This skill should be used when the user asks to write, structure, or scaffold a Compact smart contract for Midnight, or asks about contract anatomy, pragma and imports, ledger declarations (including sealed ledger), data types (Field, Bytes, Uint, enums, structs), circuits,…
  • 90compact-core:compact-circuit-costs
    This skill should be used when the user asks about Compact circuit costs, ZK proof generation costs, gate counts, loop unrolling behavior, hash function cost tradeoffs (transientHash vs persistentHash), commitment function costs (transientCommit vs persistentCommit), pure…
  • 100add-uint-support
    Add unsigned integer (uint) type support to PyTorch operators by updating AT_DISPATCH macros. Use when adding support for uint16, uint32, uint64 types to operators, kernels, or when user mentions enabling unsigned types, barebones unsigned types, or uint support.
  • 100fp-types-ref
    Quick reference for fp-ts types. Use when user asks which type to use, needs Option/Either/Task decision help, or wants fp-ts imports.
  • 100fp-types-ref
    Quick reference for fp-ts types. Use when user asks which type to use, needs Option/Either/Task decision help, or wants fp-ts imports.
  • 90vibe-types:scala
    Scala 3 compile-time safety techniques — opaque types, enums/ADTs/GADTs, givens, match types, inline, capture checking. Use this skill whenever the user writes Scala 3 code, mentions type safety, asks about compiler errors, discusses ADTs, opaque types, given instances, context…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.