Inco Lightning

The core Inco Lightning smart contracts library for building confidential applications on EVM chains.

Documentation

Full guides, tutorials, and API references live at docs.inco.org.

Architecture

The Inco Lightning protocol consists of two main contracts that work together:

• IncoLightning: The core encrypted operations contract - handles encrypted inputs, operations (arithmetic, bitwise, comparisons), trivial encryption, and access control
• IncoVerifier: The attestation contract - manages TEE lifecycle, decryption attestations, and advanced access control with signed vouchers

  Client App
     |
     v
+---------------------+  verify   +----------------------+
| IncoLightning       | --------> | IncoVerifier         |
| (encrypted ops)     |  proofs   | (attestation)        |
|  EncryptedInput     |           |  AdvancedAccessCtrl  |
|  EncryptedOps       |           |  DecryptionAttester  |
|  TrivialEncryption  |           |  TEELifecycle        |
|  AccessControlList  |           |  SignatureVerifier   |
|  Fee Management     |           +----------------------+
+---------------------+                ^   ^
     | events                          |   | quotes/attestations
     v                                 |   |
  Covalidator TEE  ---------------------+   +-- Quote Verifier

Key Components

| Contract | Module | Purpose | | ------------- | --------------------- | ------------------------------------------------------- | | IncoLightning | EncryptedInput | Accept client-encrypted values with replay protection | | IncoLightning | EncryptedOperations | 29 operations (arithmetic, bitwise, comparison, random) | | IncoLightning | TrivialEncryption | Create encrypted handles from plaintext constants | | IncoLightning | BaseAccessControlList | Persistent + transient access permissions | | IncoLightning | Fee Management | Collect fees for covalidator processing | | IncoVerifier | AdvancedAccessControl | EIP-712 signed vouchers for access delegation | | IncoVerifier | DecryptionAttester | Verify covalidator signatures on decryptions | | IncoVerifier | TEELifecycle | Bootstrap, upgrade, and manage TEE nodes | | IncoVerifier | SignatureVerifier | Multi-signature threshold verification |

Install dependencies

bun install

Build

See Foundry version requirements for version guidance.

forge build

Test

To run all the unit tests:

forge test

Coverage

To run test coverage:

make coverage

This generates an lcov report, filters out node_modules, autogenerated contracts and other contracts that we don't want to include in the report (Lib.XXXnet.sol, etc.). Eventually, it genhtml the filtered lcov in coverage and a lcov-badge visible in this readme. You can check the latest coverage stats here.

Note: Coverage requires lcov (brew install lcov on macOS) and Foundry v1.3.6. See Foundry version requirements.

Directory Structure

| Directory | Description | | -------------- | -------------------------------------------------- | | src/ | Main contract source code | | src/libs/ | Release libraries that link to versioned executors | | src/version/ | Version configuration (IncoLightningConfig.sol) | | test/ | Unit tests | | script/ | Utility scripts |

Makefile Commands

| Command | Description | | --------------- | ------------------------------------ | | make build | Build contracts with Foundry | | make test | Run unit tests | | make coverage | Generate coverage report (uses lcov) | | make lint | Lint Solidity files |

Deploy

For comprehensive deployment and upgrade instructions, see lightning-deployment/.

Contract version is defined in IncoLightningConfig.sol.

Manifest file

manifest.yaml is a file that tracks Inco Lightning smart contract releases (versioned instances of the executor contract) and deployments (actual instances of the contract on particular chains). The release names correspond to the names of the solidity libs that are libraries that statically link to the correct executor for the corresponding release.

Release names have a one-to-one correspondence with on-chain addresses - the same unique release will have the same address across chains and will run the same major version of the protocol.

The release names have the following format:

incoLightning_<major>_<minor>_<patch>__<salt>

The salt is derived from the version and additional value called the pepper. The salt determines the on-chain address of the release, whence the pepper can be used to for releases of the same contract versions with separate state and addresses (e.g. for testing purposes).