compact-core:compact-standard-library

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 and MCP codebase. 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.

MCP Verification Techniques

Technique	Tool	What It Tells You
Search Compact codebase	midnight-search-compact with the function name	Finds real usage in Compact repos. If no results, the function likely does not exist.
Search official docs	midnight-search-docs with the function name	Finds official API documentation. Cross-check signatures against this skill.
Compile a minimal contract	midnight-compile-contract with a contract that calls the function	The ultimate verification. If it compiles, the function exists with that signature.

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, use midnight-search-compact to find real usage examples
4. For critical code, compile a minimal contract with midnight-compile-contract

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 midnight-search-compact with the type name (e.g., MerkleTreeDigest) to find real-world usage patterns across the Compact codebase.

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 midnight-compile-contract 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