Documentation
Docs46. Token & Resource Standards (KRS)

46. Token & Resource Standards (KRS)

The Kortana Resource Standards (KRS) framework establishes an authoritative, formally verified library of smart contract interfaces, state machines, and mathematical invariants for the Kortana ecosystem (§21, §9.1.3, §9.8). Rather than treating token specifications as loose, copy-paste Solidity templates vulnerable to reentrancy attacks and state corruption, the Kortana protocol codifies standards as mathematically proven state transition systems.

The KRS architecture is built on three core protocol principles:

  1. Standardization Without Gatekeeping: In accordance with §3 Principle 3, the KRS registry standardizes rather than gatekeeps. Any developer can implement and deploy a standard at any lifecycle stage; the registry records how thoroughly a standard's state machine and security invariants have been reviewed, audited, and tested.
  2. Immutable Standard Identifiers (R9.1.3.2): Once published, a standard's numeric identifier (e.g. KRS-20, KRS-721, KRS-9064) is immutable forever. Breaking interface changes require minting a new numeric identifier rather than modifying an existing specification.
  3. Three-Tier Taxonomy: Standards are structured into three distinct operational tiers:
    • Tier 1 (Ethereum Equivalence): 100% ABI selector and storage layout parity with standard ERC token contracts.
    • Tier 2 (Kortana-Native Finance & Identity): Advanced financial, authorization, and escrow primitives utilizing native Quorlin capability security.
    • Tier 3 (DePIN & Physical Hardware): High-throughput micro-settlement, device identity, and cryptographic sensor telemetry commitments.

46.1 Tier 1: Ethereum-Equivalent Standards (KRS-20, KRS-721, KRS-1155)

Tier 1 standards provide bit-for-bit ABI compatibility and storage equivalence with Ethereum's most widely adopted token specifications, enabling immediate plug-and-play interoperability with existing Web3 wallets, decentralized exchanges, and indexers:

  • KRS-20 (Fungible Token Standard): Implements the full ERC-20 interface (totalSupply, balanceOf, transfer, transferFrom, approve, allowance, and Transfer/Approval events). Built natively in Quorlin, KRS-20 enforces static capability declarations (writes balances, writes allowances), eliminating reentrancy vulnerabilities by design. Differential testing in test/differential/krs20_vs_erc20_test.cpp proves identical execution outcomes against solc-compiled ERC-20 bytecode while consuming significantly less gas.
  • KRS-721 (Non-Fungible Token Standard): Implements the complete ERC-721 standard for unique digital assets and NFTs (ownerOf, safeTransferFrom, tokenURI, setApprovalForAll). KRS-721 enforces strict safe receiver semantics (onERC721Received) only when the target recipient address contains executable code, preventing unintended token burns.
  • KRS-1155 (Multi-Token Standard): Hybrid multi-token standard enabling batch balance queries (balanceOfBatch) and atomic multi-asset transfers (safeBatchTransferFrom). Optimized storage packing in the KVM register machine dramatically lowers the gas cost of minting and transferring semi-fungible game items, tickets, and fractional assets.
contract MyToken is KRS20 {
    state balances: map<address, number>
    state allowances: map<address, map<address, number>>
    state total_supply: number

    init(initial_supply: number) writes balances, total_supply {
        total_supply = initial_supply
        balances[caller()] = initial_supply
    }

    entry transfer(recipient: address, amount: number) writes balances {
        require(balances[caller()] >= amount, "Insufficient balance")
        balances[caller()] = balances[caller()] - amount
        balances[recipient] = balances[recipient] + amount
        emit Transfer(caller(), recipient, amount)
    }
}

46.2 Tier 2: Kortana-Native Financial & Identity Standards

Tier 2 standards leverage the full expressive power of Quorlin's capability model to implement advanced financial instruments, identity registries, and programmable escrows:

  • KRS-1579 (Real-World Asset / RWA): A comprehensive tokenization framework for physical assets, real estate, and tokenized securities. Incorporates compliance whitelisting, jurisdictional transfer locks, legal ownership metadata hashes, and verifiable attestation dependencies.
  • KRS-2186 (Delegated Authorization): Capability-based access control standard (createGrant, useGrant, revokeGrant). Allows accounts to grant scoped, time-bounded, and gas-metered execution permissions to third-party relayers or smart contract proxies without revealing private keys.
  • KRS-4317 (Obligation & Debt): Formalized credit and promissory note standard supporting structured amortization schedules, interest accrual, partial repayments, and automated collateral liquidation hooks.
  • KRS-6821 (Attestation Registry): An on-chain verifiable credential registry for KYC/AML compliance, credit scoring, and proof of residency. Attestations are signed cryptographically by certified issuers and verified on chain in constant time.
  • KRS-7743 (Structured Payment): Milestone-based automated payment routing, split payments, recurring subscriptions, and conditional disbursements (createPayment, settle).
  • KRS-9064 (Programmable Escrow): Multi-party, arbiter-mediated programmable escrow standard with automated timeout recovery, dispute arbitration, and non-custodial deposit settlement (createEscrow, release, refund, dispute).

46.3 Tier 3: DePIN & IoT Hardware Standards

Tier 3 standards are purpose-built for Decentralized Physical Infrastructure Networks (DePIN), energy grids, compute clusters, and IoT sensor hardware:

  • KRS-3311 (Streaming Settlement): Continuous, second-by-second micro-payment streaming for bandwidth, compute, and energy metering. Utilizes O(1) constant-time arithmetic to calculate streaming balances dynamically upon withdrawal, enabling millions of micro-transactions with zero state bloat.
  • KRS-5502 (Device Registry): Hardware-bound machine identity registry anchoring hardware secure enclaves (TEE/TPM) and public key credentials directly to physical IoT devices. Prevents device spoofing and enables hardware-signed data verification.
  • KRS-8290 (Telemetry Commitment): High-throughput verifiable hardware sensor and telemetry data commitment standard. Aggregates thousands of off-chain sensor readings into cryptographic Merkle state roots, allowing DePIN networks to commit verifiable physical proofs on chain with minimal gas overhead.

46.4 Standard Lifecycle & Governance Registry

The lifecycle of every KRS standard is formally tracked and enforced in governance/krs_registry.cpp across seven distinct states:

  PROPOSED --> REVIEWED --> TESTNET-ACTIVE --> MAINNET-CANDIDATE --> MAINNET-ACTIVE
     |                                                                   |
     +---------------------> WITHDRAWN                                   v
                                                                     DEPRECATED
  1. PROPOSED: Initial standard draft submitted against the standard specification template.
  2. REVIEWED: Formal design review complete; state transitions and mathematical invariants verified.
  3. TESTNET-ACTIVE: Implemented, deployed, and validated on the Poseidon Testnet with 100% green test suites and differential runs.
  4. MAINNET-CANDIDATE: Two-pass security audit complete with all findings resolved.
  5. MAINNET-ACTIVE: Approved by on-chain governance vote and active on Mainnet.
  6. DEPRECATED: Superseded by a newer standard (already-deployed contracts continue executing normally in accordance with R21.3.1).
  7. WITHDRAWN: Abandoned before mainnet deployment with zero state footprint.

Developers and node operators can query active standards and their lifecycle states using kortana-cli krs list-standards or via the ktn_getKrsResource JSON-RPC method.

46.5 Strict Storage Layout Verification & Interoperability

To prevent subtle storage layout mismatches between Quorlin smart contracts and external Ethereum analytics pipelines (such as The Graph subgraphs, Dune Analytics, and indexers), the Quorlin compiler provides automated storage verification via --strict-storage-layout (§14.3, R8.4):

  • Deterministic Slot Calculations: In standard Ethereum contracts, state mapping variables are stored at slot Keccak-256(Key || SlotIndex).
  • Compile-Time Standard Enforcement: When compiling a contract claiming compliance with a standard (e.g. quorlinc Token.ql --strict-storage-layout --standard KRS-20), quorlinc inspects the contract's AST to verify that declared state variables occupy the exact storage slots mandated by the specification (e.g. slot 0 for balances, slot 1 for allowances, slot 2 for total supply).
  • Silent Bug Prevention: If state variables are declared out of order, compilation fails immediately with a descriptive diagnostic, preventing situations where on-chain balances execute correctly but remain invisible to external indexers.

Part XIII — Appendices

Appendix A: Genesis Configuration Reference

The Genesis Configuration defines the initial cryptographic state and baseline parameters of the Kortana blockchain. The reference configuration structure includes:

{
  "chainId": 72511,
  "initialSupply": "10000000000000000000000000000",
  "baseFeePerGas": "1000000000",
  "gasLimit": "30000000",
  "allocations": [
    {
      "address": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
      "balance": "4000000000000000000000000000"
    }
  ],
  "validators": [
    {
      "address": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
      "blsPublicKey": "0x8f1234abcd...",
      "stake": "100000000000000000000000",
      "commissionBps": 500
    }
  ]
}

The genesis parser computes the initial state root, initializes the ParamStore system contract, and commits height 0 to the headers and state_trie RocksDB column families.

Appendix B: Complete RPC Method Reference

Kortana implements 52 JSON-RPC methods across four distinct namespaces:

  • eth_ (30 Methods): eth_chainId, eth_blockNumber, eth_getBlockByHash, eth_getBlockByNumber, eth_getBlockTransactionCountByHash, eth_getBlockTransactionCountByNumber, eth_getUncleCountByBlockHash, eth_getUncleCountByBlockNumber, eth_syncing, eth_mining, eth_sendRawTransaction, eth_getTransactionByHash, eth_getTransactionByBlockHashAndIndex, eth_getTransactionByBlockNumberAndIndex, eth_getTransactionReceipt, eth_getTransactionCount, eth_getBalance, eth_getCode, eth_getStorageAt, eth_getProof, eth_accounts, eth_call, eth_estimateGas, eth_gasPrice, eth_maxPriorityFeePerGas, eth_feeHistory, eth_getLogs, eth_subscribe, eth_unsubscribe.
  • ktn_ (18 Methods): ktn_nodeInfo, ktn_syncStatus, ktn_getPoHInfo, ktn_getValidators, ktn_getValidatorInfo, ktn_validatorSetChange, ktn_getStakingInfo, ktn_getEquivocationEvidence, ktn_getEpochInfo, ktn_newEpoch, ktn_getGovernanceProposals, ktn_getParamStore, ktn_getMempoolInfo, ktn_addressInfo, ktn_sendTransaction, ktn_subscribe, ktn_unsubscribe, ktn_shutdown.
  • net_ (3 Methods): net_version, net_listening, net_peerCount.
  • web3_ (1 Method): web3_clientVersion.

Appendix C: Complete CLI Command Reference

Full command-line reference for kortana-cli and quorlinc:

  • kortana-cli keygen [--type bls|secp256k1|ed25519] [--out <path>]: Generate cryptographic key pairs.
  • kortana-cli wallet new|import|export: Manage non-custodial wallets and keystores.
  • kortana-cli tx stake|unstake|delegate|claim-rewards: Execute staking operations.
  • kortana-cli tx gov propose|vote: Submit and vote on governance parameter updates.
  • kortana-cli tx send|deploy: Broadcast value transfers and contract deployments.
  • kortana-cli query balance|block|tx|validator: Inspect on-chain state.
  • quorlinc <file.ql> [-o <out_dir>] [--optimize] [--dump-ir] [--check]: Compile and analyze Quorlin smart contracts.

Appendix D: Error Codes Reference

Standardized ErrorCode taxonomy utilized across kortana-node:

  • 0x00 Success: Operation completed successfully.
  • 0x10 InvalidSignature: Cryptographic signature verification failed.
  • 0x11 MalleableSignature: Signature violates EIP-2 low-S canonical constraints.
  • 0x20 NonceMismatch: Transaction nonce does not match account sequence.
  • 0x21 InsufficientBalance: Account balance cannot cover fee and value.
  • 0x30 ExceedsBlockGasLimit: Gas required exceeds block ceiling.
  • 0x31 UnderpricedGas: Declared gas price below 1 gwei protocol floor.
  • 0x40 CapabilityViolation: Quorlin function attempted unauthorized state mutation.
  • 0x50 StateRootMismatch: Calculated state root does not match block header.
  • 0x60 BftDoubleSign: Equivocation detected at identical view and height.

Appendix E: Glossary of Terms

  • dPOH: Delegated Proof of History — Continuous sequential SHA-256 Verifiable Delay Function providing verifiable time ordering.
  • KSC BFT: Kortana Consensus Byzantine Fault Tolerance — Pipelined HotStuff-family consensus protocol utilizing BLS12-381 signature aggregation.
  • QC: Quorum Certificate — Constant-size aggregated BLS12-381 signature certifying supermajority validator approval.
  • KVM: Kortana Virtual Machine — 32-register capability-secure execution environment.
  • KEVM: Kortana Ethereum Virtual Machine — Embedded evmone engine providing 100% Cancun hard fork opcode parity.
  • Quorlin: Purpose-built smart contract programming language enforcing static capability security.
  • DNR: Dinar — Native gas, staking, and governance token ($DNR) with 18 decimal places.
  • ParamStore: On-chain system contract (0x...0102) storing mutable governance parameters.

Appendix F: Upgrade Path & Hard Fork Protocol

Protocol upgrades in Kortana follow a deterministic, scheduled activation protocol:

  1. Governance Approval: Core parameter updates are approved via on-chain governance and assigned a specific future block activation height (H_upgrade).
  2. Binary Release: Core developers release upgraded kortanad binaries embedding the new consensus rules.
  3. Activation Height Transition: When the canonical chain reaches H_upgrade, nodes automatically activate the new execution rules and state transitions.
  4. Legacy Safety Guard: Any node running outdated binary versions that does not recognize the hard fork safely halts block processing at H_upgrade, preventing state corruption or accidental fork creation.
Previous 45. Responsible Disclosure