39. `quorlinc`

quorlinc is the official, standalone compiler for the Quorlin capability-secure smart contract programming language (§21). Engineered from the ground up in modern C++23 as a native executable within the kortana-node repository (cmd/quorlinc/main.cpp), quorlinc provides a complete, independent compilation toolchain that transforms high-level Quorlin source code (.ql) into deployable, capability-verified Kortana Virtual Machine binary modules (.kvm / .bin) and Ethereum-compatible ABI JSON specifications (.abi.json).

Unlike traditional smart contract compilers that produce unstructured, dynamic bytecode requiring complex runtime stack management, quorlinc acts as a mathematically strict constraint system. The compiler processes contracts through a multi-pass pipeline: lexical analysis (lexer.cpp), recursive-descent parsing and AST construction (parser.cpp), static semantic analysis and capability effect verification (sema.cpp), and 32-register code generation (codegen.cpp). Every stage enforces provable bounds: recursion depth is bounded, types are static and non-coercible, arithmetic operations are checked for overflow by default, and state effects (reads and writes) are validated before bytecode generation begins. quorlinc operates with deterministic precision, ensuring that bit-for-bit identical binaries and module hashes are generated across Linux, macOS, and Windows build environments. Command-line execution returns standardized exit codes: 0 (kOk) for successful compilation, 1 (kCompileError) for lexical, syntax, type, or capability violations, and 2 (kUsageError) for file I/O or CLI parameter errors.

39.1 Compiling Contracts

Compiling a smart contract with quorlinc executes a formal multi-stage compilation pipeline that validates correctness before any bytecode is produced (§21.1–§21.4):

Lexical Scanning & Tokenization (lexer.cpp): Converts raw .ql UTF-8 source streams into typed token streams (token.hpp). The lexer identifies keywords (contract, reads, writes, require, emit), literals, identifiers, and comments while rejecting non-ASCII characters or malformed tokens.
Syntax Parsing & AST Construction (parser.cpp): Builds a strongly typed Abstract Syntax Tree (AST) representing contract fields, storage mappings, events, constructors, and function definitions. Because Quorlin intentionally omits dynamic loops and inheritance, AST construction is linear and provably bounded.
Semantic Capability Analysis (sema.cpp): Enforces mandatory capability constraints. Functions declared with reads are statically verified to contain zero state-mutating AST nodes (SStore, TStore, Create, balance transfers, event emissions, or non-static external calls). Any attempt to mutate state within a reads scope causes an immediate compile-time error.
Code Generation & Register Allocation (codegen.cpp): Lowers the verified AST into 32-register KVM instructions. High-level mathematical expressions map directly to named register operations (r0–r31), small literals compile to LoadI, large constants compile to constant pool LoadK entries, and reads function calls compile to StaticCall opcodes.

quorlinc Token.ql -o build/

The compilation process is deterministic, ensuring that identical source code produces bit-for-bit identical bytecode across different operating systems and compiler builds.

39.2 Output Files

When invoked with the -o or --out <dir> flag, quorlinc emits three deterministic compilation artifacts named after the declared contract:

<Contract>.bin (or .kvm): The executable KVM binary module. It begins with the mandatory 4-byte magic prefix 4B 56 4D 00 ("KVM\0"), followed by a 2-byte module version (1), 4-byte entry point instruction offset, 4-byte instruction count, constant pool table, and fixed-width 4-byte instruction stream. The binary carries zero timestamps, paths, or build metadata, ensuring 100% reproducible builds.
<Contract>.abi.json: The standard Ethereum JSON Application Binary Interface (ABI) specification. It describes all public and external methods, parameter names, canonical types (uint256 for number, bool for truth, address, string for text), mutability specifiers (view for reads, nonpayable/payable for writes), and event topic signatures. This ABI integrates seamlessly with ethers.js, viem, Hardhat, and web3 frontends.
<Contract>.hash: The 32-byte Keccak-256 cryptographic digest calculated directly over the encoded .bin module bytes (R8.3). This hash serves as the canonical code_hash committed to the Merkle-Patricia State Trie upon deployment and enables deterministic CREATE2 address derivation.

Compilation produces these deterministic artifacts directly without intermediate wrappers.

39.3 Compiler Flags & Options

The quorlinc CLI provides a focused set of flags designed for terminal workflows, build automation, and UNIX piping:

-o, --out <dir>: Directs the compiler to write <Contract>.bin, <Contract>.abi.json, and <Contract>.hash into the specified target directory, automatically creating parent folders if needed.
--bytecode: Emits only the raw hexadecimal deployable bytecode string to stdout, allowing direct piping into deployment scripts (e.g. quorlinc Token.ql --bytecode | kortana-cli tx deploy --code -). Diagnostics and error messages are routed strictly to stderr to prevent corrupting piped streams.
--abi: Emits only the formatted ABI JSON document to stdout, ideal for piping directly into frontend artifact directories.
--hash: Computes and prints only the 32-byte deterministic module hash (code_hash) for build verification and contract address pre-calculation.
--strict-storage-layout --standard <KRS-ID>: Enforces strict storage slot verification against declared token standards (such as KRS-20, KRS-721, KRS-1155), preventing silent storage misalignments with external indexers.
-h, --help: Displays the comprehensive command-line reference and exit code documentation.

39.4 Intermediate Representation (IR)

quorlinc includes built-in compiler introspection and static analysis tools to assist smart contract engineers and security auditors (§21.5):

IR Dump Mode (quorlinc --dump-ir): Prints a human-readable linear Intermediate Representation (IR) displaying register allocations, basic block control flow graphs, constant pool mappings, and static capability effect assertions. Auditors can inspect exactly how high-level Quorlin expressions translate into KVM register windows before binary emission.
Static Analysis & Type Checking (quorlinc --check): Performs full lexical, syntactic, and semantic type validation without generating output binaries. It verifies that all variable accesses are in scope, types are strictly matched, arithmetic operations are bounded, and capability declarations are satisfied.
Security Invariant Validation: The static analysis engine proves at compile time that functions cannot trigger reentrancy vulnerabilities, access uninitialized storage slots, or overflow checked integer types, providing mathematical assurance before smart contracts are committed to the blockchain.

39.5 Storage Layout & Standard Verification

To guarantee complete interoperability with Ethereum ecosystem indexers, subgraphs, and analytics pipelines, quorlinc provides automated storage layout verification via the --strict-storage-layout flag (§14.3, R8.4):

Deterministic Storage Layout: Storage in Quorlin follows standard Ethereum storage slot formulas. Mapping keys are located at Keccak-256(Key || SlotIndex), and record struct fields are packed sequentially starting at Keccak-256(Key || SlotIndex) + FieldIndex.
KRS Standard Layout Enforcer: When a contract claims compliance with a Tier-1 standard (such as KRS-20 for fungible tokens), passing --strict-storage-layout --standard KRS-20 validates that the contract's state variable declarations match the mandatory slot layout expected by standard indexers (e.g. slot 0 for balances mapping, slot 1 for allowances mapping, slot 2 for total supply).
Compile-Time Rejection of Misaligned Layouts: If an engineer accidentally declares state variables out of standard order, quorlinc fails compilation immediately with a descriptive diagnostic, preventing subtle indexing bugs where external tools read incorrect storage slots.