# Protocol Specification

> **InterLink Chain provides a fully EVM-equivalent execution environment — enabling developers to deploy, test, and operate Solidity smart contracts with zero modification using the tools they already know.**

***

### Design Goal: Full EVM Equivalence, Not Just Compatibility

Many blockchain networks claim "EVM compatibility" but implement only a subset of the Ethereum Virtual Machine specification, leading to subtle bugs, broken tooling, and developer frustration. InterLink Chain takes a fundamentally different approach:

**InterLink's EVM execution environment is not a reimplementation or a partial port — it is a fully equivalent EVM engine that processes bytecode identically to Ethereum Mainnet.** Every standard opcode, every precompiled contract, every gas metering rule operates exactly as a Solidity developer expects.

The result: any smart contract that compiles and deploys on Ethereum will compile and deploy on InterLink Chain without a single line of code change. No porting. No debugging compatibility issues. No rewriting test suites.

***

### Opcode & Precompile Compatibility

#### Standard EVM Opcodes

InterLink supports the **complete set of EVM opcodes** up to and including the Shanghai/Cancun upgrade specifications:

* ✅ All arithmetic, comparison, and bitwise operations
* ✅ SHA3 (Keccak-256) hashing
* ✅ Environment opcodes (`ADDRESS`, `BALANCE`, `ORIGIN`, `CALLER`, `CALLVALUE`, `GASPRICE`, etc.)
* ✅ Block information (`BLOCKHASH`, `COINBASE`, `TIMESTAMP`, `NUMBER`, `DIFFICULTY`, `GASLIMIT`, `CHAINID`, `BASEFEE`)
* ✅ Stack, memory, and storage operations (`PUSH`, `POP`, `MLOAD`, `MSTORE`, `SLOAD`, `SSTORE`)
* ✅ Control flow (`JUMP`, `JUMPI`, `PC`, `JUMPDEST`)
* ✅ System operations (`CREATE`, `CREATE2`, `CALL`, `DELEGATECALL`, `STATICCALL`, `SELFDESTRUCT`, `REVERT`)
* ✅ Logging (`LOG0` through `LOG4`)

#### Ethereum Precompiled Contracts

All standard Ethereum precompiled contracts are available at their canonical addresses:

| Address | Precompile                                 | Status      |
| ------- | ------------------------------------------ | ----------- |
| `0x01`  | ECDSA Recovery (`ecRecover`)               | ✅ Supported |
| `0x02`  | SHA-256 Hash                               | ✅ Supported |
| `0x03`  | RIPEMD-160 Hash                            | ✅ Supported |
| `0x04`  | Identity (Data Copy)                       | ✅ Supported |
| `0x05`  | Modular Exponentiation (`modexp`)          | ✅ Supported |
| `0x06`  | BN256 Elliptic Curve Addition              | ✅ Supported |
| `0x07`  | BN256 Elliptic Curve Scalar Multiplication | ✅ Supported |
| `0x08`  | BN256 Elliptic Curve Pairing               | ✅ Supported |
| `0x09`  | Blake2 Compression (`BLAKE2b`)             | ✅ Supported |

#### InterLink-Specific Precompiled Contracts

In addition to standard Ethereum precompiles, InterLink extends the EVM with **protocol-native precompiled contracts** that expose core InterLink functionality directly to smart contracts:

| Address | Precompile                    | Function                                                                                                                                             |
| ------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0x800` | **InterLink ID Verification** | Verify whether an address holds a valid InterLink ID on-chain. Returns verification status and ID metadata (issuance timestamp, verification level). |
| `0x801` | **AMM Pool Query**            | Query protocol-embedded AMM pool state: reserves, price, TVL, 24h volume for any IRC-20/ITL pair.                                                    |
| `0x802` | **RWA Token Registry**        | Query the on-chain registry of tokenized businesses: token address, business verification status, cumulative transaction volume, pool address.       |
| `0x803` | **Staking Info**              | Query validator set, delegation amounts, staking rewards, and slashing history.                                                                      |

**Usage Example (Solidity):**

```solidity
// Verify InterLink ID before allowing a sensitive operation
interface IInterLinkID {
    function isVerified(address account) external view returns (bool verified, uint256 verifiedAt);
}

contract ProtectedVault {
    IInterLinkID constant ID_VERIFIER = IInterLinkID(address(0x800));

    modifier onlyVerified() {
        (bool verified, ) = ID_VERIFIER.isVerified(msg.sender);
        require(verified, "InterLink ID required");
        _;
    }

    function withdraw(uint256 amount) external onlyVerified {
        // Only verified humans can withdraw — bots are structurally excluded
        _processWithdrawal(msg.sender, amount);
    }
}
```

***

### IRC Token Standards

InterLink defines its own token standard specifications — **IRC (InterLink Request for Comments)** — which maintain full interface compatibility with their Ethereum ERC counterparts while being formally adopted as InterLink-native standards.

#### IRC-20: Fungible Token Standard

**Compatible with: ERC-20**

IRC-20 is the standard interface for fungible tokens on InterLink Chain. Every RWA business token, utility token, and wrapped asset on the network implements IRC-20.

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IIRC20 {
    function name() external view returns (string memory);
    function symbol() external view returns (string memory);
    function decimals() external view returns (uint8);
    function totalSupply() external view returns (uint256);
    function balanceOf(address account) external view returns (uint256);
    function transfer(address to, uint256 amount) external returns (bool);
    function allowance(address owner, address spender) external view returns (uint256);
    function approve(address spender, uint256 amount) external returns (bool);
    function transferFrom(address from, address to, uint256 amount) external returns (bool);

    event Transfer(address indexed from, address indexed to, uint256 value);
    event Approval(address indexed owner, address indexed spender, uint256 value);
}
```

**Key points for developers:**

* Interface is **byte-for-byte identical** to ERC-20 — existing contracts and libraries (OpenZeppelin, Solmate) work without modification
* IRC-20 tokens issued via the RWA Engine are automatically paired with ITL in protocol-embedded AMM pools
* All IRC-20 transfers emit standard `Transfer` events, compatible with existing indexers (The Graph, custom event listeners)

#### IRC-721: Non-Fungible Token Standard

**Compatible with: ERC-721**

IRC-721 defines the standard for non-fungible tokens (NFTs) on InterLink Chain. Full support for metadata extensions, enumeration, and safe transfer hooks.

```solidity
interface IIRC721 {
    function balanceOf(address owner) external view returns (uint256);
    function ownerOf(uint256 tokenId) external view returns (address);
    function safeTransferFrom(address from, address to, uint256 tokenId) external;
    function transferFrom(address from, address to, uint256 tokenId) external;
    function approve(address to, uint256 tokenId) external;
    function getApproved(uint256 tokenId) external view returns (address);
    function setApprovalForAll(address operator, bool approved) external;
    function isApprovedForAll(address owner, address operator) external view returns (bool);

    event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);
    event Approval(address indexed owner, address indexed approved, uint256 indexed tokenId);
    event ApprovalForAll(address indexed owner, address indexed operator, bool approved);
}
```

#### IRC-1155: Multi-Token Standard

**Compatible with: ERC-1155**

IRC-1155 supports both fungible and non-fungible tokens within a single contract — ideal for gaming assets, loyalty programs, and multi-class business tokens.

#### IRC-4337: Smart Account & Account Abstraction

**Compatible with: ERC-4337**

IRC-4337 defines InterLink's account abstraction framework, enabling Smart Accounts with:

* **Gasless transactions** — Businesses sponsor gas for their customers via the Paymaster mechanism
* **Session keys** — Time-limited, scope-restricted signing keys for seamless UX
* **Social recovery** — Recover account access through trusted guardians without seed phrases
* **Batch operations** — Multiple on-chain actions in a single user operation
* **Programmable validation** — Custom signature schemes, multi-sig, biometric authentication

```solidity
// Simplified IRC-4337 UserOperation structure
struct UserOperation {
    address sender;           // Smart Account address
    uint256 nonce;            // Anti-replay nonce
    bytes initCode;           // Account creation code (if first transaction)
    bytes callData;           // Encoded function call(s)
    uint256 callGasLimit;     // Gas for execution
    uint256 verificationGasLimit; // Gas for validation
    uint256 preVerificationGas;   // Gas for bundler overhead
    uint256 maxFeePerGas;     // IIP-1559 max fee
    uint256 maxPriorityFeePerGas; // IIP-1559 priority fee
    bytes paymasterAndData;   // Paymaster address + sponsorship data
    bytes signature;          // Signed authorization
}
```

**Paymaster Integration Example:**

```solidity
// A business sponsors gas for its verified customers
contract BusinessPaymaster is IPaymaster {
    address public businessOwner;
    IIRC20 public businessToken; // The business's RWA token

    function validatePaymasterUserOp(
        UserOperation calldata userOp,
        bytes32 userOpHash,
        uint256 maxCost
    ) external returns (bytes memory context, uint256 validationData) {
        // Verify the user holds the business's RWA token (is a customer)
        require(businessToken.balanceOf(userOp.sender) > 0, "Not a customer");
        
        // Business pays gas — user pays nothing
        return (abi.encode(userOp.sender), 0);
    }
}
```

***

### IIP Protocol Standards

#### IIP-1559: Dynamic Fee Market

**Compatible with: EIP-1559**

InterLink implements the IIP-1559 fee mechanism with two components:

* **Base Fee** — Algorithmically adjusted per block based on network utilization. Burned to create deflationary pressure on ITL supply.
* **Priority Fee (Tip)** — Optional fee paid directly to validators for transaction priority.

On InterLink, the base fee is calibrated to maintain **near-zero transaction costs** during normal network utilization, reflecting the design principle that businesses should not bear prohibitive per-transaction overhead.

| Parameter                    | Value                            |
| ---------------------------- | -------------------------------- |
| **Minimum Base Fee**         | `[TBD]` gwei                     |
| **Target Block Utilization** | 50% of gas limit                 |
| **Max Fee Change Per Block** | 12.5% (same as Ethereum)         |
| **Base Fee Destination**     | Burned (removed from ITL supply) |
| **Priority Fee Destination** | Block-producing validator        |

#### IIP-712: Typed Structured Data Signing

**Compatible with: EIP-712**

Standard for signing human-readable, structured messages. Critical for:

* Off-chain order signing (gasless approvals)
* Domain-separated signatures preventing cross-chain replay
* User-friendly transaction confirmation in wallets

#### IIP-155: Replay Protection

**Compatible with: EIP-155**

All transactions include the InterLink chain ID in their signature hash, preventing replay attacks from other EVM networks.

| Network               | Chain ID |
| --------------------- | -------- |
| **InterLink Mainnet** | `[TBD]`  |
| **InterLink Testnet** | `[TBD]`  |

***

### Developer Tooling Compatibility

InterLink's full EVM equivalence means developers use their existing toolkit without modification:

| Tool                | Status             | Notes                                                             |
| ------------------- | ------------------ | ----------------------------------------------------------------- |
| **Hardhat**         | ✅ Fully Compatible | Configure `hardhat.config.js` with InterLink RPC URL and chain ID |
| **Foundry (Forge)** | ✅ Fully Compatible | `forge create --rpc-url <INTERLINK_RPC>`                          |
| **Remix IDE**       | ✅ Fully Compatible | Add InterLink as custom network via Injected Provider             |
| **MetaMask**        | ✅ Fully Compatible | Add InterLink as custom RPC network                               |
| **ethers.js**       | ✅ Fully Compatible | `new ethers.JsonRpcProvider("https://rpc.interlink.network")`     |
| **viem**            | ✅ Fully Compatible | Define InterLink chain configuration                              |
| **web3.js**         | ✅ Fully Compatible | Standard Web3 provider initialization                             |
| **The Graph**       | ✅ Compatible       | Custom subgraph deployment to InterLink node                      |
| **OpenZeppelin**    | ✅ Fully Compatible | All contracts deploy without modification                         |
| **Solmate**         | ✅ Fully Compatible | Gas-optimized contracts work identically                          |

#### Quick Start: Hardhat Configuration

```javascript
// hardhat.config.js
require("@nomicfoundation/hardhat-toolbox");

module.exports = {
  solidity: "0.8.24",
  networks: {
    interlink: {
      url: "https://rpc.interlink.network",
      chainId: /* [TBD] */,
      accounts: [process.env.PRIVATE_KEY],
      gasPrice: "auto",
    },
    interlinkTestnet: {
      url: "https://testnet-rpc.interlink.network",
      chainId: /* [TBD] */,
      accounts: [process.env.PRIVATE_KEY],
      gasPrice: "auto",
    }
  }
};
```

#### Quick Start: Foundry

```bash
# Deploy a contract
forge create src/MyContract.sol:MyContract \
  --rpc-url https://rpc.interlink.network \
  --private-key $PRIVATE_KEY \
  --chain-id [TBD]

# Verify a contract
forge verify-contract <CONTRACT_ADDRESS> src/MyContract.sol:MyContract \
  --chain-id [TBD] \
  --verifier-url https://explorer.interlink.network/api
```

***

### JSON-RPC API

InterLink exposes the **standard Ethereum JSON-RPC API**, ensuring compatibility with all existing Ethereum tooling and infrastructure.

#### Supported Standard Methods

**Namespace: `eth_`**

| Method                      | Description                            |
| --------------------------- | -------------------------------------- |
| `eth_chainId`               | Returns the InterLink chain ID         |
| `eth_blockNumber`           | Returns the latest block number        |
| `eth_getBalance`            | Returns ITL balance of an address      |
| `eth_getTransactionCount`   | Returns the nonce of an address        |
| `eth_sendRawTransaction`    | Submits a signed transaction           |
| `eth_call`                  | Executes a read-only contract call     |
| `eth_estimateGas`           | Estimates gas for a transaction        |
| `eth_getBlockByNumber`      | Returns block data by number           |
| `eth_getBlockByHash`        | Returns block data by hash             |
| `eth_getTransactionByHash`  | Returns transaction data               |
| `eth_getTransactionReceipt` | Returns transaction receipt with logs  |
| `eth_getLogs`               | Returns event logs matching filter     |
| `eth_getCode`               | Returns contract bytecode              |
| `eth_getStorageAt`          | Returns storage value at position      |
| `eth_gasPrice`              | Returns current gas price              |
| `eth_feeHistory`            | Returns historical fee data (IIP-1559) |
| `eth_maxPriorityFeePerGas`  | Returns suggested priority fee         |
| `eth_subscribe`             | WebSocket event subscriptions          |
| `eth_unsubscribe`           | Cancel WebSocket subscription          |

**Namespace: `net_`**

| Method          | Description                       |
| --------------- | --------------------------------- |
| `net_version`   | Returns network ID                |
| `net_listening` | Returns whether node is listening |
| `net_peerCount` | Returns number of connected peers |

**Namespace: `web3_`**

| Method               | Description             |
| -------------------- | ----------------------- |
| `web3_clientVersion` | Returns client version  |
| `web3_sha3`          | Returns Keccak-256 hash |

**Namespace: `debug_` / `txpool_`**

Selected debug and transaction pool methods are available for developer tooling and diagnostics.

#### InterLink-Specific RPC Methods

**Namespace: `interlink_`**

| Method                           | Description                                                   |
| -------------------------------- | ------------------------------------------------------------- |
| `interlink_getIdentityStatus`    | Returns InterLink ID verification status for an address       |
| `interlink_getPoolState`         | Returns AMM pool reserves and pricing for an IRC-20/ITL pair  |
| `interlink_getBusinessProfile`   | Returns on-chain business profile and RWA token details       |
| `interlink_getValueCaptureStats` | Returns cumulative value capture metrics for a business token |
| `interlink_getValidatorSet`      | Returns current active validator set and staking info         |

#### RPC Endpoints

| Network     | HTTP RPC                                | WebSocket                            |
| ----------- | --------------------------------------- | ------------------------------------ |
| **Mainnet** | `https://rpc.interlink.network`         | `wss://ws.interlink.network`         |
| **Testnet** | `https://testnet-rpc.interlink.network` | `wss://testnet-ws.interlink.network` |

***

### Gas Model

InterLink implements IIP-1559 dynamic gas pricing with parameters specifically tuned for high-throughput, low-cost transaction processing:

#### Gas Costs

InterLink maintains **near-zero gas costs** by design. The network's gas price mechanism is calibrated so that at normal utilization levels, transaction fees are negligible — enabling businesses to sponsor thousands of customer transactions daily without material cost impact.

| Transaction Type              | Approximate Gas       | Approximate Cost |
| ----------------------------- | --------------------- | ---------------- |
| ITL Transfer                  | 21,000                | < $0.001         |
| IRC-20 Transfer               | \~65,000              | < $0.003         |
| IRC-20 Approve                | \~46,000              | < $0.002         |
| AMM Swap                      | \~150,000             | < $0.007         |
| Contract Deployment (simple)  | \~200,000–500,000     | < $0.025         |
| Contract Deployment (complex) | \~1,000,000–5,000,000 | < $0.25          |

> **Note:** Actual costs depend on network utilization and ITL market price. The protocol is designed to maintain sub-cent transaction costs at target throughput levels.

#### Block Gas Limit

| Parameter                    | Value                                                     |
| ---------------------------- | --------------------------------------------------------- |
| **Block Gas Limit**          | `[TBD]` (configured to support 2,000+ TPS at \~3s blocks) |
| **Target Block Utilization** | 50%                                                       |
| **Max Gas Per Transaction**  | Configurable by deployer (default block gas limit / 2)    |

***

### Smart Contract Development Guide

#### Contract Deployment Workflow

```
┌──────────────┐    ┌──────────────┐    ┌───────────────┐    ┌──────────────┐
│    Write     │───▶│   Compile    │───▶│   Deploy to   │───▶│   Verify     │
│   Solidity   │    │  (solc 0.8+) │    │   InterLink   │    │  on Explorer │
│   Contract   │    │              │    │   Testnet     │    │              │
└──────────────┘    └──────────────┘    └───────────────┘    └──────────────┘
                                               │
                                               ▼
                                        ┌───────────────┐    ┌──────────────┐
                                        │    Test &     │───▶│   Deploy to  │
                                        │   Audit       │    │   Mainnet    │
                                        └───────────────┘    └──────────────┘
```

#### Recommended Solidity Version

InterLink supports all Solidity compiler versions. For new projects, we recommend:

```solidity
pragma solidity ^0.8.20; // Uses latest safety features, overflow checks, custom errors
```

#### Security Best Practices

1. **Use established libraries** — OpenZeppelin and Solmate contracts are fully compatible and battle-tested
2. **Leverage InterLink ID verification** — Gate sensitive operations behind `IInterLinkID.isVerified()` to ensure only verified participants can interact
3. **Use IRC-4337 Smart Accounts** — Enable gasless UX for end users through the Paymaster mechanism
4. **Follow checks-effects-interactions pattern** — Standard reentrancy protection applies
5. **Emit events for all state changes** — Enables off-chain indexing and business analytics
6. **Test on InterLink Testnet** — Full feature parity with Mainnet, including InterLink ID simulation and AMM pool testing

#### Contract Verification

Deploy source code verification through the InterLink Explorer:

```bash
# Via Foundry
forge verify-contract <ADDRESS> src/Contract.sol:Contract \
  --verifier-url https://explorer.interlink.network/api \
  --chain-id [TBD]

# Via Hardhat
npx hardhat verify --network interlink <ADDRESS> <CONSTRUCTOR_ARGS>
```

Verified contracts display source code, ABI, and interaction interface on the InterLink Explorer — building transparency and trust for tokenized business assets.