Skip to main content

Monomer Reference

All 128 monomers organized by family (64 Core + 64 Extended). Each entry includes the exact signature, domain constraints, return type, edge cases, and usage examples.
All monomers return Value::I64 unless explicitly noted. The only exception is MC_03.DIV8 which returns Value::Tuple([i64, i64]).Argument coercion: When passing i64 to arithmetic/logic monomers, values are narrowed to u8 (low 8 bits). bool values are coerced to u8 (true→1, false→0). Control monomers (MC_24–MC_31) preserve bool as-is.

Family 0: Arithmetic (MC_00 – MC_07)

All arithmetic monomers operate on 8-bit unsigned values with saturation semantics (results clamped to 0–255).

MC_00 — ADD8

Signature: ADD8(a: u8, b: u8) → i64 Saturating addition. Result is min(a + b, 255).
let r = MC_00.ADD8(100, 50);   // 150
let s = MC_00.ADD8(200, 100);  // 255 (saturates, does NOT overflow)
let z = MC_00.ADD8(0, 0);      // 0
Edge cases:
  • ADD8(255, 1)255 (saturation)
  • ADD8(0, 0)0

MC_01 — SUB8

Signature: SUB8(a: u8, b: u8) → i64 Saturating subtraction. Result is max(a - b, 0).
let r = MC_01.SUB8(100, 30);   // 70
let z = MC_01.SUB8(5, 10);     // 0 (saturates at zero, no underflow)
Edge cases:
  • SUB8(0, 255)0 (saturation)
  • SUB8(100, 100)0

MC_02 — MUL8

Signature: MUL8(a: u8, b: u8) → i64 Saturating multiplication. Result is min(a * b, 255).
let r = MC_02.MUL8(10, 20);    // 200
let s = MC_02.MUL8(20, 20);    // 255 (saturates)
Edge cases:
  • MUL8(0, anything)0
  • MUL8(255, 2)255 (saturation)

MC_03 — DIV8

Signature: DIV8(a: u8, b: u8) → Tuple(i64, i64) Integer division with remainder. Returns (quotient, remainder).
let (q, r) = MC_03.DIV8(17, 5);    // q=3, r=2
let (q2, r2) = MC_03.DIV8(10, 3);  // q2=3, r2=1
Always destructure DIV8. It is the only monomer that returns a tuple.Division by zero causes a runtime error. Always guard:
if (b != 0) {
    let (q, r) = MC_03.DIV8(a, b);
}
Edge cases:
  • DIV8(0, 5)(0, 0)
  • DIV8(5, 0)runtime error (use try/catch or guard)
  • DIV8(255, 1)(255, 0)

MC_04 — MOD8

Signature: MOD8(a: u8, b: u8) → i64 Modulo operation. Returns a % b.
let r = MC_04.MOD8(17, 5);   // 2
let z = MC_04.MOD8(10, 2);   // 0
Edge cases:
  • MOD8(x, 0)runtime error
  • MOD8(0, x)0

MC_05 — NEG8

Signature: NEG8(a: u8) → i64 Arithmetic negation. Returns 256 - a (two’s complement in u8 range).
let r = MC_05.NEG8(1);    // 255
let z = MC_05.NEG8(0);    // 0

MC_06 — ABS8

Signature: ABS8(a: u8) → i64 Absolute value. For u8, this is identity (all values are already non-negative).
let r = MC_06.ABS8(42);   // 42

MC_07 — POW8

Signature: POW8(base: u8, exp: u8) → i64 Saturating exponentiation. Result is min(base^exp, 255).
let r = MC_07.POW8(2, 7);    // 128
let s = MC_07.POW8(2, 8);    // 255 (saturates)
let z = MC_07.POW8(0, 5);    // 0
let o = MC_07.POW8(5, 0);    // 1

Family 1: Logic (MC_08 – MC_15)

Bitwise operations on 8-bit values.

MC_08 — AND8

Signature: AND8(a: u8, b: u8) → i64 Bitwise AND.
let r = MC_08.AND8(0xFF, 0x0F);   // 15 (0x0F)
let z = MC_08.AND8(0xAA, 0x55);   // 0

MC_09 — OR8

Signature: OR8(a: u8, b: u8) → i64 Bitwise OR.
let r = MC_09.OR8(0xF0, 0x0F);   // 255 (0xFF)

MC_10 — XOR8

Signature: XOR8(a: u8, b: u8) → i64 Bitwise XOR.
let r = MC_10.XOR8(0xFF, 0xFF);  // 0
let s = MC_10.XOR8(0xAA, 0x55);  // 255

MC_11 — NOT8

Signature: NOT8(a: u8) → i64 Bitwise NOT (complement).
let r = MC_11.NOT8(0);     // 255
let s = MC_11.NOT8(255);   // 0
let t = MC_11.NOT8(0xF0);  // 15 (0x0F)

MC_12 — SHL8

Signature: SHL8(a: u8, n: u8) → i64 Left shift by n bits, masked to 8 bits.
let r = MC_12.SHL8(1, 4);    // 16
let s = MC_12.SHL8(1, 7);    // 128
let z = MC_12.SHL8(1, 8);    // 0 (shifted out)

MC_13 — SHR8

Signature: SHR8(a: u8, n: u8) → i64 Right shift by n bits.
let r = MC_13.SHR8(128, 4);  // 8
let s = MC_13.SHR8(255, 1);  // 127

MC_14 — ROTL8

Signature: ROTL8(a: u8, n: u8) → i64 Rotate left by n bits within 8-bit range.
let r = MC_14.ROTL8(0x80, 1);  // 1 (bit wraps around)

MC_15 — ROTR8

Signature: ROTR8(a: u8, n: u8) → i64 Rotate right by n bits within 8-bit range.
let r = MC_15.ROTR8(1, 1);  // 128 (bit wraps around)

Family 2: Memory (MC_16 – MC_23)

Array and memory operations.

MC_16 — ALLOC

Signature: ALLOC(size: i64) → array Creates an array of size elements, all initialized to 0.
let arr = MC_16.ALLOC(10);   // [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

MC_17 — LOAD

Signature: LOAD(arr: array, idx: i64) → i64 Reads element at index idx from arr.
let arr = [10, 20, 30];
let val = MC_17.LOAD(arr, 1);   // 20
Edge case: LOAD(arr, -1) or index ≥ len → runtime error.

MC_18 — STORE

Signature: STORE(arr: array, idx: i64, val: i64) → array Returns a new array with element at idx replaced by val.
let arr = [10, 20, 30];
let arr2 = MC_18.STORE(arr, 1, 99);   // [10, 99, 30]
// arr is still [10, 20, 30] (value semantics)

MC_19 — LEN_MEM

Signature: LEN_MEM(arr: array) → i64 Returns the length of the array.

MC_20 — COPY

Signature: COPY(arr: array) → array Returns a copy of the array (identity in PCD since all values are immutable).

MC_21 — SWAP

Signature: SWAP(arr: array, i: i64, j: i64) → array Returns a new array with elements at indices i and j swapped.

MC_22 — ZERO

Signature: ZERO(arr: array) → array Returns a new array with all elements set to 0.

MC_23 — FENCE

Signature: FENCE() → i64 Memory barrier / synchronization point. Returns 0. Used to enforce ordering between parallel compositions.

Family 3: Control (MC_24 – MC_31)

Control flow monomers. These preserve bool arguments (no u8 coercion).

MC_24 — IF

Signature: IF(cond: bool, then_val, else_val) → value Conditional select. Returns then_val if cond is true, else_val otherwise.
let r = MC_24.IF(x > 0, "positive", "non-positive");
In most PCD code, you use the if/else syntax instead of calling MC_24 directly. The planner desugars if/else into MC_24.

MC_25 — CALL

Signature: CALL(fn_ref, arg) → value Indirect function call. Used internally by the planner for closure dispatch.

MC_26 — LOOP

Signature: LOOP(n: i64, body_fn) → value Internal loop primitive. The loop(N) syntax desugars to this.

MC_27 — RET

Signature: RET(val) → value Return from function. The return keyword desugars to this.

MC_28 — JUMP

Signature: JUMP(target: i64) → value Internal jump. Used by the BIR emitter. Not available in PCD source.

MC_29 — HALT

Signature: HALT(code: i64) → void Halt execution with exit code. The OUTPUT directive desugars to this.

MC_30 — NOOP

Signature: NOOP() → i64 No operation. Returns 0. Used as placeholder or synchronization point.

MC_31 — YIELD

Signature: YIELD(val) → value Yields a value in streaming contexts. Used internally for BIR streaming output.

Family 4: I/O (MC_32 – MC_39)

Input/output operations.

MC_32 — READ

Signature: READ(fd: i64, buf: array, n: i64) → i64 Low-level read from file descriptor. Returns bytes read.

MC_33 — WRITE

Signature: WRITE(fd: i64, data: string, len: i64) → i64 Low-level write to file descriptor. Returns bytes written.
let msg = "hello\n";
MC_33.WRITE(1, msg, MC_43.LEN(msg));   // write to stdout (fd=1)

MC_34 — OPEN

Signature: OPEN(path: string, flags: i64) → i64 Open a file. Returns file descriptor. flags: 0=read, 1=write, 2=read+write.

MC_35 — CLOSE

Signature: CLOSE(fd: i64) → i64 Close a file descriptor. Returns 0 on success.

MC_36 — SEEK

Signature: SEEK(fd: i64, offset: i64, whence: i64) → i64 Seek within a file. whence: 0=SET, 1=CUR, 2=END.

MC_37 — FLUSH

Signature: FLUSH(fd: i64) → i64 Flush file descriptor buffers.

MC_38 — STAT

Signature: STAT(path: string) → i64 Returns file size in bytes, or -1 if file doesn’t exist.

MC_39 — SYNC

Signature: SYNC() → i64 Sync all file system buffers. Returns 0.

Family 5: String (MC_40 – MC_47)

String manipulation. All string operations return new strings (immutable).

MC_40 — CONCAT

Signature: CONCAT(a: string, b: string) → string Concatenate two strings. The + operator on strings is sugar for this.
let r = MC_40.CONCAT("hello", " world");   // "hello world"

MC_41 — SPLIT

Signature: SPLIT(s: string, delim: string) → array Split string by delimiter. Returns array of substrings.
let parts = MC_41.SPLIT("a,b,c", ",");   // ["a", "b", "c"]
Edge cases:
  • SPLIT("", ",")[""]
  • SPLIT("abc", "")["a", "b", "c"]

MC_42 — SUBSTR

Signature: SUBSTR(s: string, start: i64, len: i64) → string Extract substring starting at start with length len.
let sub = MC_42.SUBSTR("hello world", 6, 5);   // "world"
Edge cases:
  • start ≥ string length → empty string
  • start + len > string length → truncated to available characters

MC_43 — LEN

Signature: LEN(s: string) → i64 Returns character count of string. Also works on arrays.
let n = MC_43.LEN("hello");     // 5
let m = MC_43.LEN([1, 2, 3]);   // 3
let z = MC_43.LEN("");           // 0

MC_44 — UPPER

Signature: UPPER(s: string) → string Convert to uppercase.
let u = MC_44.UPPER("hello");   // "HELLO"

MC_45 — CHAR_AT

Signature: CHAR_AT(s: string, idx: i64) → string Returns single character at position idx as a string.
let ch = MC_45.CHAR_AT("hello", 0);   // "h"
let ch2 = MC_45.CHAR_AT("hello", 4);  // "o"
Edge case: Index out of bounds → runtime error. Always check MC_43.LEN first.

MC_46 — LOWER

Signature: LOWER(s: string) → string Convert to lowercase.
let l = MC_46.LOWER("HELLO");   // "hello"

MC_47 — TRIM

Signature: TRIM(s: string) → string Remove leading and trailing whitespace.
let t = MC_47.TRIM("  hello  ");   // "hello"

Family 6: Crypto (MC_48 – MC_55)

Cryptographic operations.

MC_48 — HASH

Signature: HASH(data: string) → string SHA-256 hash. Returns hex string (64 characters).
let h = MC_48.HASH("hello");
// "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

MC_49 — HMAC

Signature: HMAC(key: string, data: string) → string HMAC-SHA256. Returns hex string.
let mac = MC_49.HMAC("secret", "message");

MC_50 — ENCRYPT

Signature: ENCRYPT(key: string, plaintext: string) → string AES-256 encryption. Returns base64-encoded ciphertext.

MC_51 — DECRYPT

Signature: DECRYPT(key: string, ciphertext: string) → string AES-256 decryption. Input is base64-encoded ciphertext.

MC_52 — SHA256

Signature: SHA256(data: string) → string Alias for MC_48.HASH. SHA-256 hash returning hex string.

MC_53 — RAND

Signature: RAND(max: i64) → i64 Returns a random integer in [0, max).
Using RAND in a policy circuit will cause Φ_c < 1 because the output is non-deterministic. RAND is intended for non-critical applications only.

MC_54 — SIGN

Signature: SIGN(private_key: string, data: string) → string Digital signature (Ed25519). Returns hex-encoded signature.

MC_55 — VERIFY

Signature: VERIFY(public_key: string, data: string, signature: string) → i64 Verify digital signature. Returns 1 if valid, 0 if invalid.
let valid = MC_55.VERIFY(pub_key, message, sig);
if (valid == 1) {
    // signature is valid
}

Family 7: System (MC_56 – MC_63)

System operations and I/O.

MC_56 — READ (file)

Signature: READ(path: string) → string Read entire file contents as string.
let content = MC_56.READ("input.txt");
let stdin = MC_56.READ("/dev/stdin");
Edge case: File not found → runtime error (use try/catch).

MC_57 — WRITE_FILE

Signature: WRITE_FILE(path: string, data: string) → i64 Write string to file. Creates or overwrites. Returns 0 on success.
MC_57.WRITE_FILE("output.txt", "hello world");

MC_58 — WRITE (stdout)

Signature: WRITE(text: string) → i64 Write to stdout. Returns bytes written.
let _ = MC_58.WRITE("Hello!\n");

MC_59 — READ_LINE

Signature: READ_LINE() → string Read one line from stdin (without trailing newline).
let line = MC_59.READ_LINE();

MC_60 — EXEC

Signature: EXEC(command: string) → string Execute shell command. Returns stdout output.
EXEC is powerful and potentially dangerous. Policy circuits should BLOCK any use of EXEC from untrusted agents.

MC_61 — KILL

Signature: KILL(pid: i64, signal: i64) → i64 Send signal to process. Returns 0 on success.

MC_62 — SIGNAL

Signature: SIGNAL(sig: i64) → i64 Register or handle a signal. Returns previous handler status.

MC_63 — ENV

Signature: ENV(name: string) → string Read environment variable. Returns empty string if not set.
let home = MC_63.ENV("HOME");
let arg1 = MC_63.ENV("ARGV_1");    // argv[1] in native ELF
let arg2 = MC_63.ENV("ARGV_2");    // argv[2] in native ELF
In native ELF binaries, MC_63.ENV("ARGV_1") reads argv[1] from process arguments, not environment variables. ARGV_2 reads argv[2], etc. In non-native backends, it reads the actual environment variable.

Quick Reference Table

MCNameSignatureReturnsFamily
00ADD8(u8, u8)i64Arithmetic
01SUB8(u8, u8)i64Arithmetic
02MUL8(u8, u8)i64Arithmetic
03DIV8(u8, u8)Tuple(i64, i64)Arithmetic
04MOD8(u8, u8)i64Arithmetic
05NEG8(u8)i64Arithmetic
06ABS8(u8)i64Arithmetic
07POW8(u8, u8)i64Arithmetic
08AND8(u8, u8)i64Logic
09OR8(u8, u8)i64Logic
10XOR8(u8, u8)i64Logic
11NOT8(u8)i64Logic
12SHL8(u8, u8)i64Logic
13SHR8(u8, u8)i64Logic
14ROTL8(u8, u8)i64Logic
15ROTR8(u8, u8)i64Logic
16ALLOC(i64)arrayMemory
17LOAD(array, i64)i64Memory
18STORE(array, i64, i64)arrayMemory
19LEN_MEM(array)i64Memory
20COPY(array)arrayMemory
21SWAP(array, i64, i64)arrayMemory
22ZERO(array)arrayMemory
23FENCE()i64Memory
24IF(bool, val, val)valueControl
25CALL(fn, arg)valueControl
26LOOP(i64, fn)valueControl
27RET(val)valueControl
28JUMP(i64)valueControl
29HALT(i64)voidControl
30NOOP()i64Control
31YIELD(val)valueControl
32READ(i64, array, i64)i64I/O
33WRITE(i64, string, i64)i64I/O
34OPEN(string, i64)i64I/O
35CLOSE(i64)i64I/O
36SEEK(i64, i64, i64)i64I/O
37FLUSH(i64)i64I/O
38STAT(string)i64I/O
39SYNC()i64I/O
40CONCAT(string, string)stringString
41SPLIT(string, string)arrayString
42SUBSTR(string, i64, i64)stringString
43LEN(string|array)i64String
44UPPER(string)stringString
45CHAR_AT(string, i64)stringString
46LOWER(string)stringString
47TRIM(string)stringString
48HASH(string)stringCrypto
49HMAC(string, string)stringCrypto
50ENCRYPT(string, string)stringCrypto
51DECRYPT(string, string)stringCrypto
52SHA256(string)stringCrypto
53RAND(i64)i64Crypto
54SIGN(string, string)stringCrypto
55VERIFY(string, string, string)i64Crypto
56READ(string)stringSystem
57WRITE_FILE(string, string)i64System
58WRITE(string)i64System
59READ_LINE()stringSystem
60EXEC(string)stringSystem
61KILL(i64, i64)i64System
62SIGNAL(i64)i64System
63ENV(string)stringSystem

Extended Monomers (MC_64 – MC_127)

Extended monomers operate under CONTRACT closure (Φ_c = CONTRACT), not the Coq-proven Φ_c = 1 of Core monomers. They are available starting in v4.0.0-beta.2. Programs using Extended monomers compile with --open and receive the BRIK-64 Open badge.

Family 8: Float64 (MC_64 – MC_71)

IEEE 754 double-precision floating-point operations.
MCNameSignatureReturns
64FADD(f64, f64)f64
65FSUB(f64, f64)f64
66FMUL(f64, f64)f64
67FDIV(f64, f64)f64
68FABS(f64)f64
69FNEG(f64)f64
70FSQRT(f64)f64
71FMOD(f64, f64)f64
// Float64 example
PC circle_area {
    let radius = MC_64.FADD(5.0, 0.0);
    let pi = MC_64.FADD(3.14159, 0.0);
    let r_squared = MC_66.FMUL(radius, radius);
    let area = MC_66.FMUL(pi, r_squared);
}

Family 9: Math (MC_72 – MC_79)

Transcendental and mathematical functions.
MCNameSignatureReturns
72SIN(f64)f64
73COS(f64)f64
74TAN(f64)f64
75EXP(f64)f64
76LN(f64)f64
77LOG2(f64)f64
78POW(f64, f64)f64
79CEIL(f64)f64
// Math example
PC trig_demo {
    let angle = MC_64.FADD(1.5708, 0.0);
    let sine = MC_72.SIN(angle);
    let cosine = MC_73.COS(angle);
    let power = MC_78.POW(2.0, 10.0);
    let rounded = MC_79.CEIL(3.7);
}

Family 10: Network (MC_80 – MC_87)

MCNameSignatureReturns
80TCP_CONN(string, i64)i64
81TCP_SEND(i64, string)i64
82TCP_RECV(i64, i64)string
83UDP_SEND(string, i64, string)i64
84DNS(string)string
85HTTP_GET(string)string
86HTTP_POST(string, string)string
87TLS(i64)i64

Family 11: Graphics (MC_88 – MC_95)

MCNameSignatureReturns
88FB_INIT(i64, i64)i64
89FB_PIXEL(i64, i64, i64)i64
90FB_LINE(i64, i64, i64, i64, i64)i64
91FB_RECT(i64, i64, i64, i64, i64)i64
92FB_BLIT(array, i64, i64)i64
93FB_FLIP()i64
94FB_TEXT(i64, i64, string)i64
95FB_CLOSE()i64

Family 12: Audio (MC_96 – MC_103)

MCNameSignatureReturns
96AU_INIT(i64, i64)i64
97AU_PLAY(string)i64
98AU_STOP()i64
99AU_MIX(array)i64
100AU_VOL(i64)i64
101AU_SEEK(i64)i64
102AU_STREAM(string)i64
103AU_CLOSE()i64

Family 13: Filesystem+ (MC_104 – MC_111)

MCNameSignatureReturns
104DIR_LIST(string)array
105DIR_CREATE(string)i64
106DIR_DELETE(string)i64
107CHMOD(string, i64)i64
108CHOWN(string, i64)i64
109LINK(string, string)i64
110WATCH(string)i64
111TEMP()string

Family 14: Concurrency (MC_112 – MC_119)

MCNameSignatureReturns
112SPAWN(closure)i64
113JOIN(i64)value
114CHAN_NEW()i64
115CHAN_SEND(i64, value)i64
116CHAN_RECV(i64)value
117MUTEX()i64
118ATOMIC(i64, i64)i64
119YIELD()i64

Family 15: Interop/FFI (MC_120 – MC_127)

MCNameSignatureReturns
120FFI_LOAD(string)i64
121FFI_CALL(i64, string, array)value
122FFI_ALLOC(i64)i64
123FFI_FREE(i64)i64
124WASM_EXEC(string, string, array)value
125PY_EVAL(string)value
126JSON_PARSE(string)value
127JSON_EMIT(value)string