1. Introduction to Quorlin

Quorlin is the native smart contract programming language of the Kortana blockchain platform. Designed to bridge the gap between high-level expressive software design and rigorous, secure blockchain execution, Quorlin features a syntax that looks like Java and reads like plain English. Contracts written in Quorlin are saved with the .ql file extension and compile down to low-level register bytecode executed by the Kortana Virtual Machine (KVM).

Beyond its syntax, Quorlin is built with ecosystem interoperability at its core. Although it executes on a register-based virtual machine, the language natively maintains compatibility with Ethereum’s Application Binary Interface (ABI) and standard EVM signatures. This enables Quorlin contracts on the Kortana network to seamlessly call—and be called by—existing Solidity contracts and standard Ethereum client tooling.

---

1.1 Philosophy and Language Vision

Smart contract vulnerabilities often stem from syntax ambiguity, unreadable code, or complex boilerplate that obscures developer intent. Quorlin addresses these challenges by introducing intuitive, natural language keywords while enforcing strict type semantics and explicit function mutability contracts.

Key syntax principles of Quorlin include:

• Natural Mutability Declarations: Instead of using abstract modifiers like view, pure, or non-constant qualifiers, Quorlin functions explicitly declare their intentions using English verbs: reads for read-only state operations and writes for state-modifying operations.
• Readable Types and Literals: Technical primitive types are mapped directly to human concepts. A 256-bit unsigned integer is represented simply as number, booleans are represented as truth (with literal values yes and no), and void returns are explicitly declared as nothing.
• Self-Documenting Expressions: Guard conditions use clear statement structures such as require <condition>, "<error message>", making contract logic read like formal specifications.

Consider this minimal token contract written in standard Quorlin:

contract DafoCoin {

    number totalSupply;
    map<address, number> balances;

    event Transfer(address indexed from, address indexed to, number amount);

    constructor {
        totalSupply = 1000000;
        balances[caller] = 1000000;
    }

    reads number balanceOf(address owner) {
        return balances[owner];
    }

    writes truth transfer(address recipient, number amount) {
        number held = balances[caller];
        require held >= amount, "not enough";

        balances[caller] = held - amount;
        balances[recipient] = balances[recipient] + amount;
        emit Transfer(caller, recipient, amount);
        return yes;
    }
}

---

1.2 Primitive Type System and Mapping

Quorlin provides a precise core type system. During compilation, the compiler translates Quorlin source types into internal semantic types (Type), which are then mapped to standard Ethereum ABI types when emitting contract descriptors.

Type Translation Matrix

Quorlin Source Type	Internal Type	Ethereum ABI Name	Description
number	Type::U256	uint256	Unsigned 256-bit integer for state variables, balances, and arithmetic.
truth	Type::Bool	bool	Logical boolean value (yes or no).
address	Type::Address	address	20-byte Kortana/Ethereum-compatible account or contract identifier.
text	Type::Text	string	UTF-8 encoded dynamic character string.
nothing	Type::Void	void	Represents functions that return no value.

In addition to primitive types, Quorlin supports composite state structures:

1. Mappings (map<K, V>): Key-value lookup tables stored directly in global state.
2. Records (record): User-defined custom data structures holding named fields.

---

1.3 Smart Contract Architecture

Every Quorlin program consists of a single contract declaration encapsulating state storage, events, constructor logic, and executable functions.

contract EscrowVault {

    // --- State Storage ---
    address seller;
    address buyer;
    number lockedAmount;
    truth isSettled;

    // --- Events ---
    event Deposited(address indexed buyer, number amount);
    event Released(address indexed seller, number amount);

    // --- Constructor ---
    constructor {
        seller = caller;
        isSettled = no;
    }

    // --- State-Modifying Method ---
    writes truth deposit(address targetBuyer, number amount) {
        require isSettled == no, "Already settled";
        require lockedAmount == 0, "Vault already funded";

        buyer = targetBuyer;
        lockedAmount = amount;

        emit Deposited(buyer, amount);
        return yes;
    }

    // --- Read-Only Method ---
    reads truth getStatus() {
        return isSettled;
    }
}

Context Built-Ins and Control Flow

• caller: Implicitly provides the address of the message sender performing the transaction.
• require <condition>, "<message>": Validates runtime state. If the condition evaluates to no (false), transaction execution immediately reverts with the specified string error message.
• yes / no: Native boolean constants mapping directly to true and false values.

---

1.4 The Four-Stage Compilation Pipeline

The Quorlin compilation process transforms high-level .ql source text into verified KVM binary modules through four distinct compiler stages: Lexing, Parsing, Semantic Analysis, and Code Generation.

Source Code (.ql)
       │
       ▼
┌──────────────┐
│  1. Lexer    │  ── Tokenization & Literal Parsing
└──────────────┘
       │
       ▼
┌──────────────┐
│  2. Parser   │  ── AST Construction & Grammar Validation
└──────────────┘
       │
       ▼
┌──────────────┐
│  3. Analyzer │  ── Type Checking, Mutability Verification, Symbol Resolution
└──────────────┘
       │
       ▼
┌──────────────┐
│ 4. CodeGen   │  ── Register Allocation & KVM Bytecode Emission
└──────────────┘
       │
       ▼
 Executable KVM Module

1. Lexical Analysis (Lexer)

The lexer converts the raw source code string into a sequence of strongly-typed tokens. Identifier starts (a-z, A-Z, _) and parts (including digits 0-9) are scanned, while keywords like contract, reads, writes, record, and indexed are mapped directly to TokenKind enumerations.

2. Syntactic Parsing (Parser)

The parser accepts the token stream and generates a structured Abstract Syntax Tree (AST) represented as a SourceUnit. The parser checks that the code conforms to Quorlin's grammar rules, ensuring correct contract declarations, variable layouts, expression groupings, and function signatures.

3. Semantic Analysis (Analyzer)

Semantic analysis validates language semantics. The Analyzer:

• Resolves identifiers and state variable names.
• Enforces strong type checking across expressions and assignments.
• Verifies function mutability (prohibiting state modifications inside reads functions).
• Validates struct access and custom record fields.

If any semantic checks fail, compilation halts with detailed diagnostics before bytecode generation, preventing the creation of malformed binary modules.

4. Code Generation (CodeGenerator)

Once semantic analysis passes, the code generator emits binary instructions targeted for the Kortana Virtual Machine (KVM) ISA. Label fixups for jumps, function selectors, constant pool indices, and opcode formats are resolved into an executable module.

---

1.5 The Kortana Virtual Machine (KVM) Execution Model

The Kortana Virtual Machine (KVM) is a high-performance, register-based virtual machine designed specifically for execution on the Kortana blockchain network.

KVM Binary Module Layout

Compiled Quorlin programs are packaged into standard big-endian binary modules. The file structure begins with a fixed 18-byte header followed by constant storage and 32-bit instructions:

┌─────────────────────────────────────────────────────────┐
│                      Module Header                      │
│─────────────────────────────────────────────────────────│
│ Magic Bytes ("KVM\0")                         : 4 Bytes │
│ Format Version                                : 2 Bytes │
│ Constant Pool Count                           : 4 Bytes │
│ Instruction Count                             : 4 Bytes │
│ Entry Point (Instruction Index)              : 4 Bytes │
├─────────────────────────────────────────────────────────┤
│                     Constant Pool                       │
│─────────────────────────────────────────────────────────│
│ 32-Byte Constants (Big-Endian Arrays)         : Variable│
├─────────────────────────────────────────────────────────┤
│                     Instruction Code                    │
│─────────────────────────────────────────────────────────│
│ Fixed-Width 32-Bit Instruction Words          : Variable│
└─────────────────────────────────────────────────────────┘

Instruction Set Formats

KVM uses fixed 32-bit instruction words categorized into four fundamental layout formats:

1. R-Form (Register): Operates on up to three 5-bit register addresses (rd, rs1, rs2) with a 9-bit function code modifier (funct). Used for ALU operations, comparisons, and bitwise math.
2. I-Form (Immediate): Contains a destination register (rd), a source register (rs1), and a 14-bit unsigned immediate value (imm). Used for immediate arithmetic and memory offsets.
3. J-Form (Jump): Contains a direct 24-bit jump address (imm) for control flow transfers.
4. Plain Form: Opcode-only zero-operand instructions used for execution halting and termination (Stop, Ret, Invalid).

World State Host Integration

During execution, the KVM interpreter interfaces with the host blockchain environment via the StateHost subsystem. Every storage operation (get_storage and set_storage) interacts with Kortana's Unified State Trie. When a contract modifies state, set_storage measures the write delta against existing storage slots, enabling accurate dynamic gas calculation.

---

1.6 Tooling and EVM Interoperability

Quorlin contracts are fully compatible with external Ethereum tools and standard web3 client stacks.

                  ┌──────────────────────────────┐
                  │ Quorlin Contract Source (.ql)│
                  └──────────────┬───────────────┘
                                 │
                        compile(source)
                                 │
           ┌─────────────────────┴─────────────────────┐
           ▼                                           ▼
┌──────────────────────┐                    ┌─────────────────────┐
│ KVM Bytecode Module  │                    │ Ethereum JSON ABI   │
│ (Executes on Kortana)│                    │ (Tooling & Clients) │
└──────────────────────┘                    └─────────────────────┘

JSON ABI Generation

The compiler automatically outputs canonical Ethereum-compliant JSON ABIs alongside KVM binary modules. Human-readable Quorlin types are translated to EVM-equivalent standard type names:

[
  {
    "type": "constructor",
    "inputs": []
  },
  {
    "type": "function",
    "name": "balanceOf",
    "stateMutability": "view",
    "inputs": [
      { "name": "owner", "type": "address", "internalType": "address" }
    ],
    "outputs": [
      { "name": "", "type": "uint256", "internalType": "number" }
    ]
  },
  {
    "type": "function",
    "name": "transfer",
    "stateMutability": "nonpayable",
    "inputs": [
      { "name": "recipient", "type": "address", "internalType": "address" },
      { "name": "amount", "type": "uint256", "internalType": "number" }
    ],
    "outputs": [
      { "name": "", "type": "bool", "internalType": "truth" }
    ]
  }
]

Standard Interface Compliance

Quorlin standard libraries include formal interface signatures for cross-contract interactions, including token standard compatibility layers like IERC20. Function selectors are derived directly from canonical EVM signatures (e.g., transfer(address,uint256) hashed via Keccak256), allowing Quorlin smart contracts to directly interoperate with Ethereum ecosystem standards.