compact-core-compact-standard-library

star 21

This skill should be used when the user asks about the Compact standard library (CompactStandardLibrary), stdlib types (Maybe, Either, JubjubPoint, MerkleTreeDigest, MerkleTreePath, ContractAddress, ZswapCoinPublicKey, UserAddress), deprecated stdlib names (CurvePoint, NativePoint, CoinInfo), stdlib constructor functions (some, none, left, right), elliptic curve functions (ecAdd, ecMul, ecMulGenerator, hashToCurve, jubjubPointX, jubjubPointY, constructJubjubPoint), Merkle tree path verification (merkleTreePathRoot, merkleTreePathRootNoLeafHash), or when the user needs to verify which functions exist in the standard library or prevent hallucination of non-existent stdlib functions.

devrelaicom By devrelaicom schedule Updated 6/2/2026
play_arrow Run Skill in Manus View GitHub

name: compact-core:compact-standard-library description: This skill should be used when the user asks about the Compact standard library (CompactStandardLibrary), stdlib types (Maybe, Either, JubjubPoint, MerkleTreeDigest, MerkleTreePath, ContractAddress, ZswapCoinPublicKey, UserAddress), deprecated stdlib names (CurvePoint, NativePoint, CoinInfo), stdlib constructor functions (some, none, left, right), elliptic curve functions (ecAdd, ecMul, ecMulGenerator, hashToCurve, jubjubPointX, jubjubPointY, constructJubjubPoint), Merkle tree path verification (merkleTreePathRoot, merkleTreePathRootNoLeafHash), or when the user needs to verify which functions exist in the standard library or prevent hallucination of non-existent stdlib functions. version: 0.1.0

Compact Standard Library Reference

This is the single authoritative index of everything import CompactStandardLibrary; provides. Every type, constructor, circuit, and builtin documented here has been verified against the Compact compiler. For contract anatomy and scaffold patterns, see compact-structure. For language mechanics (types, operators, control flow), see compact-language-ref. For ledger ADT state design and privacy, see compact-ledger. For token mint/send/receive operations and patterns, see compact-tokens. This skill follows a verification-first philosophy: when in doubt, verify -- never assume a function exists.

Verification Protocol

RULE: Never assume a stdlib function exists. Before using any function from CompactStandardLibrary, verify it appears in the export inventory below. If a function is not listed, it does not exist.

Verification Techniques

Technique Tool What It Tells You
Search the Compact source on GitHub octocode (githubSearchCode against LFDT-Minokawa/compact) Finds real usage and definitions. If no results, the symbol likely does not exist.
Compile a minimal contract compact compile --skip-zk <file> The ultimate verification. If it compiles, the function exists with that signature.
Dispatch the verify agent /midnight-verify:verify with the claim Runs source-first verification and (optionally) executes a minimal contract end-to-end.

Verification Checklist

  1. Check the export inventory in this skill
  2. Verify the function signature matches (parameter types, return type, generic parameters)
  3. If uncertain, search the Compact source via octocode for real usage examples
  4. For critical code, compile a minimal contract with compact compile --skip-zk

Common Hallucination Traps: See the complete "Common Mistakes & Non-Existent Functions" table at the end of this document for the full list of functions that do NOT exist in the standard library.

Complete Export Inventory

Every export from import CompactStandardLibrary;, organized by category. Use this as the definitive checklist before referencing any stdlib symbol.

Types

Name Kind Brief Description Reference Location
Maybe<T> type Optional value container references/types-and-constructors.md
Either<A, B> type Disjoint union (sum type) references/types-and-constructors.md
JubjubPoint type Elliptic curve point references/types-and-constructors.md
MerkleTreeDigest type Merkle root hash wrapper references/types-and-constructors.md
MerkleTreePathEntry type Sibling + direction in path references/types-and-constructors.md
MerkleTreePath<#n, T> type Path from leaf to root references/types-and-constructors.md
ContractAddress type Contract address wrapper references/types-and-constructors.md
ZswapCoinPublicKey type Coin public key for shielded ops references/types-and-constructors.md
UserAddress type User address wrapper references/types-and-constructors.md
ShieldedCoinInfo type Newly created shielded coin compact-tokens/references/token-operations.md
QualifiedShieldedCoinInfo type Existing shielded coin with index compact-tokens/references/token-operations.md
ShieldedSendResult type Send result with change compact-tokens/references/token-operations.md

Constructor Circuits

Name Kind Brief Description Reference Location
some<T> circuit Construct Maybe containing value references/types-and-constructors.md
none<T> circuit Construct empty Maybe references/types-and-constructors.md
left<A, B> circuit Construct left Either variant references/types-and-constructors.md
right<A, B> circuit Construct right Either variant references/types-and-constructors.md

Hashing & Commitment Circuits

Name Kind Brief Description Reference Location
persistentHash<T> circuit SHA-256 hash; stable across upgrades compact-language-ref/references/stdlib-functions.md
transientHash<T> circuit Circuit-efficient hash; may change compact-language-ref/references/stdlib-functions.md
persistentCommit<T> circuit SHA-256 commitment with randomness compact-language-ref/references/stdlib-functions.md
transientCommit<T> circuit Circuit-efficient commitment compact-language-ref/references/stdlib-functions.md
degradeToTransient circuit Convert Bytes<32> to Field compact-language-ref/references/stdlib-functions.md
upgradeFromTransient circuit Convert Field to Bytes<32> compact-language-ref/references/stdlib-functions.md

Elliptic Curve Circuits

Name Kind Brief Description Reference Location
ecAdd circuit Add two JubjubPoints references/cryptographic-functions.md
ecMul circuit Scalar multiply JubjubPoint references/cryptographic-functions.md
ecMulGenerator circuit Scalar multiply generator references/cryptographic-functions.md
hashToCurve<T> circuit Map value to JubjubPoint references/cryptographic-functions.md
jubjubPointX circuit Get X coordinate of JubjubPoint references/cryptographic-functions.md
jubjubPointY circuit Get Y coordinate of JubjubPoint references/cryptographic-functions.md
constructJubjubPoint circuit Construct JubjubPoint from X, Y references/cryptographic-functions.md

Merkle Tree Path Circuits

Name Kind Brief Description Reference Location
merkleTreePathRoot<#n, T> circuit Compute root from leaf + path references/cryptographic-functions.md
merkleTreePathRootNoLeafHash<#n> circuit Compute root from pre-hashed leaf references/cryptographic-functions.md

Utility Builtins

Name Kind Brief Description Reference Location
pad builtin Create Bytes from string literal compact-language-ref/references/stdlib-functions.md
disclose builtin Mark value as publicly visible compact-language-ref/references/stdlib-functions.md
assert builtin Abort if condition is false compact-language-ref/references/stdlib-functions.md
default<T> builtin Default value for any type compact-language-ref/references/stdlib-functions.md

Block Time Circuits

Name Kind Brief Description Reference Location
blockTimeLt circuit Block time less than comparison compact-language-ref/references/stdlib-functions.md
blockTimeGte circuit Block time greater-or-equal comparison compact-language-ref/references/stdlib-functions.md
blockTimeGt circuit Block time greater than comparison compact-language-ref/references/stdlib-functions.md
blockTimeLte circuit Block time less-or-equal comparison compact-language-ref/references/stdlib-functions.md

Coin Management Circuits

Name Kind Brief Description Reference Location
tokenType circuit Compute token color from domain sep + contract compact-tokens/references/token-operations.md
nativeToken circuit Native token color (zero) compact-tokens/references/token-operations.md
ownPublicKey witness Current user's coin public key compact-tokens/references/token-operations.md
mintShieldedToken circuit Mint new shielded coin compact-tokens/references/token-operations.md
receiveShielded circuit Accept shielded coin compact-tokens/references/token-operations.md
sendShielded circuit Send from existing coin compact-tokens/references/token-operations.md
sendImmediateShielded circuit Send from just-created coin compact-tokens/references/token-operations.md
mergeCoin circuit Merge two existing coins compact-tokens/references/token-operations.md
mergeCoinImmediate circuit Merge existing + new coin compact-tokens/references/token-operations.md
evolveNonce circuit Derive next nonce compact-tokens/references/token-operations.md
shieldedBurnAddress circuit Burn address for shielded coins compact-tokens/references/token-operations.md
createZswapInput circuit Low-level zswap input compact-tokens/references/token-operations.md
createZswapOutput circuit Low-level zswap output compact-tokens/references/token-operations.md
mintUnshieldedToken circuit Mint unshielded token compact-tokens/references/token-operations.md
sendUnshielded circuit Send unshielded token compact-tokens/references/token-operations.md
receiveUnshielded circuit Receive unshielded token compact-tokens/references/token-operations.md
unshieldedBalance circuit Query unshielded balance compact-tokens/references/token-operations.md
unshieldedBalanceLt circuit Balance less than comparison compact-tokens/references/token-operations.md
unshieldedBalanceGte circuit Balance greater-or-equal comparison compact-tokens/references/token-operations.md
unshieldedBalanceGt circuit Balance greater than comparison compact-tokens/references/token-operations.md
unshieldedBalanceLte circuit Balance less-or-equal comparison compact-tokens/references/token-operations.md

Ledger ADT Types

Name Kind Brief Description Reference Location
Counter ledger ADT Numeric counter compact-ledger/references/types-and-operations.md
Map<K, V> ledger ADT Key-value store compact-ledger/references/types-and-operations.md
Set<T> ledger ADT Unique element collection compact-ledger/references/types-and-operations.md
List<T> ledger ADT Ordered sequence compact-ledger/references/types-and-operations.md
MerkleTree<N, T> ledger ADT Privacy-preserving set compact-ledger/references/types-and-operations.md
HistoricMerkleTree<N, T> ledger ADT MerkleTree with root history compact-ledger/references/types-and-operations.md

Types

Types provided by the standard library. All are available after import CompactStandardLibrary;.

Type Generic Parameters Fields Summary Default Value
Maybe<T> T -- any type is_some: Boolean, value: T { is_some: false, value: default<T> }
Either<A, B> A, B -- any types is_left: Boolean, left: A, right: B { is_left: false, left: default<A>, right: default<B> } (right variant, based on struct defaults)
JubjubPoint none x: Field, y: Field { x: 0, y: 0 }
MerkleTreeDigest none field: Field { field: 0 }
MerkleTreePathEntry none sibling: MerkleTreeDigest, goesLeft: Boolean { sibling: { field: 0 }, goesLeft: false }
MerkleTreePath<#N, T> #N -- depth, T -- leaf type leaf: T, path: Vector<#N, MerkleTreePathEntry> Default leaf + default path
ContractAddress none bytes: Bytes<32> { bytes: 0x00...00 }
ZswapCoinPublicKey none bytes: Bytes<32> { bytes: 0x00...00 }
UserAddress none bytes: Bytes<32> { bytes: 0x00...00 }
ShieldedCoinInfo none nonce: Bytes<32>, color: Bytes<32>, value: Uint<128> All-zero fields
QualifiedShieldedCoinInfo none nonce: Bytes<32>, color: Bytes<32>, value: Uint<128>, mt_index: Uint<64> All-zero fields
ShieldedSendResult none change: Maybe<ShieldedCoinInfo>, sent: ShieldedCoinInfo Default Maybe + default coin

Verification: Use octocode to search the LFDT-Minokawa/compact repository for the type name (e.g., MerkleTreeDigest) to find real-world usage patterns.

For full field documentation and TypeScript representations, see references/types-and-constructors.md.

Constructor Functions

Four circuits for constructing Maybe and Either values:

circuit some<T>(value: T): Maybe<T>;
circuit none<T>(): Maybe<T>;
circuit left<A, B>(value: A): Either<A, B>;
circuit right<A, B>(value: B): Either<A, B>;

const found = some<Field>(42);
if (found.is_some) {
  const v = found.value;  // 42
}

const recipient = left<ZswapCoinPublicKey, ContractAddress>(ownPublicKey());

For full patterns including nested Maybe/Either, pattern matching idioms, and default value behavior, see references/types-and-constructors.md.

Hashing & Commitment Functions

Function Signature Domain Store in Ledger?
persistentHash<T> (value: T): Bytes<32> Persistent Yes
transientHash<T> (value: T): Field Transient No
persistentCommit<T> (value: T, rand: Bytes<32>): Bytes<32> Persistent Yes
transientCommit<T> (value: T, rand: Field): Field Transient No
degradeToTransient (x: Bytes<32>): Field Conversion --
upgradeFromTransient (x: Field): Bytes<32> Conversion --

Use persistent variants when storing in ledger or comparing across transactions. Use transient variants for in-circuit intermediates where lower gate cost matters. The degradeToTransient and upgradeFromTransient functions convert between domains when mixing persistent and transient operations in a single circuit.

Verification: If you are unsure whether to use persistent or transient, ask: "Will this value be stored in ledger or compared across transactions?" If yes, use persistent. If it is an ephemeral in-circuit intermediate, transient is safe.

For full documentation with examples, disclosure rules, and persistent vs. transient guidance, see compact-language-ref/references/stdlib-functions.md.

Elliptic Curve Functions

All EC operations use JubjubPoint, not the deprecated NativePoint or CurvePoint.

Function Signature Purpose
ecAdd (a: JubjubPoint, b: JubjubPoint): JubjubPoint Add two curve points
ecMul (a: JubjubPoint, b: Field): JubjubPoint Scalar multiplication
ecMulGenerator (b: Field): JubjubPoint Multiply generator by scalar
hashToCurve<T> (value: T): JubjubPoint Map arbitrary value to curve point
jubjubPointX (p: JubjubPoint): Field Get X coordinate
jubjubPointY (p: JubjubPoint): Field Get Y coordinate
constructJubjubPoint (x: Field, y: Field): JubjubPoint Construct point from coordinates

Use cases: Pedersen commitments, key derivation building blocks, custom signature schemes. For example, Pedersen blinding: ecAdd(ecMulGenerator(rc), ecMul(colorBase, value)).

Verification: EC functions operate on JubjubPoint, not the deprecated NativePoint or CurvePoint. The type was renamed from CurvePoint → NativePoint → JubjubPoint. Always verify with compact compile --skip-zk when using EC operations. See references/cryptographic-functions.md for full documentation and examples.

Merkle Tree Path Functions

circuit merkleTreePathRoot<#n, T>(path: MerkleTreePath<n, T>): MerkleTreeDigest;
circuit merkleTreePathRootNoLeafHash<#n>(path: MerkleTreePath<n, Bytes<32>>): MerkleTreeDigest;

These circuits verify Merkle tree membership by recomputing the root from a leaf and its path siblings. Compare the result with tree.checkRoot(digest) to verify membership. The NoLeafHash variant is for cases where the leaf is already a pre-hashed Bytes<32> value (e.g., coin commitments in zswap), avoiding double-hashing.

For full documentation with off-chain path generation patterns and HistoricMerkleTree root verification, see references/cryptographic-functions.md.

Utility Functions

Function Signature Purpose
pad pad(length, value): Bytes<N> UTF-8 string to fixed-size bytes (both args must be literals)
disclose disclose(value: T): T Mark witness-derived value as publicly visible
assert assert(condition: Boolean, message: string): [] Abort transaction if false
default<T> default<T> Default value for any type

disclose is required whenever a witness-derived value flows to a ledger operation, is used in a cross-contract call, or is returned from an exported circuit. pad requires both arguments to be compile-time literals. assert is the only error-handling mechanism in Compact.

For deep documentation on each function including examples and disclosure rules, see compact-language-ref/references/stdlib-functions.md.

Block Time Functions

Function Signature Purpose
blockTimeLt (time: Uint<64>): Boolean True if block time < given time
blockTimeGte (time: Uint<64>): Boolean True if block time >= given time
blockTimeGt (time: Uint<64>): Boolean True if block time > given time
blockTimeLte (time: Uint<64>): Boolean True if block time <= given time

These circuits compare the current block timestamp against a given value. The time argument must be disclosed when derived from a witness. Use these for time-based access control, auction deadlines, and vesting schedules.

Coin Management Functions

Shielded token functions:

Function Description
tokenType Compute token color from domain separator + contract address
nativeToken Native token color (zero value)
ownPublicKey Current user's coin public key (witness, not a circuit)
mintShieldedToken Mint a new shielded coin with domain, amount, nonce, recipient
receiveShielded Accept a shielded coin into the transaction
sendShielded Send value from an existing (qualified) shielded coin
sendImmediateShielded Send value from a just-created shielded coin
mergeCoin Merge two existing (qualified) shielded coins
mergeCoinImmediate Merge an existing coin with a just-created coin
evolveNonce Derive next nonce from counter index + current nonce
shieldedBurnAddress Get the burn address for destroying shielded coins
createZswapInput Low-level: create a zswap input from a qualified coin
createZswapOutput Low-level: create a zswap output from a coin + recipient

Unshielded token functions:

Function Description
mintUnshieldedToken Mint unshielded token with domain, amount, recipient
sendUnshielded Send unshielded token by color, amount, recipient
receiveUnshielded Receive unshielded token by color, amount
unshieldedBalance Query unshielded balance for a color
unshieldedBalanceLt Balance less than comparison
unshieldedBalanceGte Balance greater-or-equal comparison
unshieldedBalanceGt Balance greater than comparison
unshieldedBalanceLte Balance less-or-equal comparison

For complete signatures, parameters, nonce management, and merge strategies, see the compact-tokens skill.

Ledger ADT Operations

Type Key Methods Notes
Counter increment, decrement, read, lessThan Uint<16> step size
Map<K, V> insert, lookup, member, remove, size All ops visible on-chain
Set<T> insert, member, remove, size All ops visible on-chain
List<T> pushFront, popFront, head, length Ordered sequence
MerkleTree<N, T> insert, checkRoot, insertHash, isFull Insert hides leaf (via leaf_hash()); privacy via membership proofs
HistoricMerkleTree<N, T> Same + resetHistory Accepts proofs against past roots

For complete ADT operation tables, nested composition, and state design patterns, see the compact-ledger skill.

Common Mistakes & Non-Existent Functions

Wrong Correct Why
public_key(sk) persistentHash<Vector<2, Bytes<32>>>([pad(32, "domain:pk:"), sk]) public_key does not exist in stdlib
hash(value) persistentHash<T>(value) Generic hash does not exist; specify persistent or transient
verify(sig, msg, pk) Build from EC primitives No signature verification function exists
encrypt(value) / decrypt(value) Use commitments Encryption does not exist; use commit/reveal patterns
random() / randomBytes() Use witness functions No randomness source in circuits; witnesses provide off-chain randomness
counter.value() counter.read() .value() does not exist on Counter
map.get(key) map.lookup(key) .get() does not exist on Map
map.has(key) map.member(key) .has() does not exist on Map
map.set(key, value) map.insert(key, value) .set() does not exist on Map
map.delete(key) map.remove(key) .delete() does not exist on Map
NativePoint JubjubPoint NativePoint was renamed to JubjubPoint; CurvePoint is the oldest name for this type
CoinInfo ShieldedCoinInfo CoinInfo was renamed to ShieldedCoinInfo
SendResult ShieldedSendResult SendResult was renamed to ShieldedSendResult
persistentHash(value) (no generic) persistentHash<T>(value) Generic parameter is required
some(42) (no generic) some<Field>(42) Generic parameter is required for constructor circuits
circuit fn(): Void circuit fn(): [] Return type is [] (empty tuple), not Void
merkleTreePathRoot(path) (no generic) merkleTreePathRoot<#n, T>(path) Requires depth and leaf type generics
Custom registry for @midnight-ntwrk/* Not needed — all packages are on public npm .yarnrc.yml files in SDK repos are for contributors only

Reference Routing

This skill's references

Topic Reference File
Stdlib types (Maybe, Either, JubjubPoint, MerkleTree types, address types), constructors (some, none, left, right), re-exports references/types-and-constructors.md
Elliptic curve functions, Merkle tree path functions, hashing/commitment summary references/cryptographic-functions.md
Alphabetical index of every stdlib export with authoritative documentation location references/cross-reference-index.md

Cross-references to other skills

Topic Skill
Hashing, commitments, pad, disclose, assert, default (deep docs) compact-language-ref
Ledger ADT operations, state design, privacy compact-ledger
Token types, functions, operations, patterns compact-tokens
Contract anatomy, pragma, circuits, witnesses compact-structure
Install via CLI
npx skills add https://github.com/devrelaicom/midnight-expert --skill compact-core-compact-standard-library
Repository Details
star Stars 21
call_split Forks 5
navigation Branch main
article Path SKILL.md
More from Creator
devrelaicom
devrelaicom Explore all skills →