Loading repository data…
Loading repository data…
ten-protocol / repository
Official Golang implementation of the TEN protocol
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
This repository contains the reference implementation of the Ten Protocol.
TEN is an encrypted EVM Ethereum Layer 2.
TEN uses Trusted Execution Environments (TEE) to execute transactions in a confidential environment, which means we diverge from the typical EVM node architecture.
There are three main components, each running as a separate process: the "Enclave", the "Host" and the "Gateway".
The "Gateway" exposes the standard Ethereum RPC and manages "Viewing Keys" on behalf of users. It is intended as a low-friction UX gateway into the encrypted network. It runs in a TEE, and users connect via HTTPS directly into the TEE process.
The "Host" component is the "controller" of the TEN node. It is the active component that drives one or multiple passive "Enclaves" The interactions between the host and the enclave are either responses to end-user queries or "administrative". The Host exposes an "encrypted RPC" (eRPC) for end-users. Basically, it doesn't have access to the user queries or responses.
The "Trusted Computed Base" is composed of the "Enclave" (the go codebase in this repo) and the dedicated encrypted relational database. The Enclave component's only interactions with the outside world are controlled by the "Host".
Below, we'll drill into each component and the services it runs.
This is the core component of TEN, which runs inside the TEE. See go/enclave
We use EGo, an open source SDK, for developing this confidential component.
The Enclave exposes a few interfaces over gRPC.
Note that the "Administrative" RPC is plaintext commands and responses that manage the lifecycle, while the "User" RPC takes encrypted inputs and returns encrypted outputs (or errors).
The Enclave component has these main responsibilities:
TEN has the goal to be fully compatible with the EVM, so smart contracts can be ported freely from other EVM-compatible chains. To achieve this and minimise the effort and incompatibilities, we depend on go-ethereum.
Note that the dependency on go-ethereum is not straightforward, since transaction execution is coupled with Ethereum-specific consensus rules,
which must be adapted.
See go/enclave/evm
As a general rule, the go-ethereum EVM execution is sandwiched between a "pre-processing" and a "post-processing" phase.
Transactions, eth_call and eth_estimateGas messages are executed similarly.
The EVM is configured to use the "Path-Based Storage", which stores data using a key-value store interface.
For reasons we'll detail below, TEN requires a relational database that itself must run as an enclave and stores data encrypted. The operation of storing data needs to be resistant to side-channel analysis, which would allow an attacker to infer information on what calculations are being made based on the patterns of data the Enclave is requesting or storing.
Note: In the current iteration, we use EdglessDB, an open source database tailor-made for confidential computing.
The data produced by the TEN network is private, so indexing services can't be built on top of it. This means the enclave itself has to be an "Indexing Service".
Alongside the "EVM State DB" required by go-ethereum, we also have a relational database structure , where we store user queryable information along with visibility metadata. Conceptually, this schema serves as an "Infura" infrastructure with data access controls.
See go/enclave/db
The mempool is the component which handles the incoming transactions and is responsible for selecting which transactions to include in the current batch and pick the order.
The big advantage of running the mempool inside the secure Enclave is that the ordering of transactions cannot be gamed by the sequencer, which prevents MEV.
We use the underlying mempool implementation from go-ethereum.
The TEN network has two node types: "sequencer" and "validators".
Only the "sequencer" has an active "mempool" and produces blocks. The validator nodes receive transactions from end users and validate them in order to return relevant errors to the user.
Note: To avoid confusion with the "Ethereum Blocks", throughout the codebase (and in this readme), we'll use "Batch" as the name for the "TEN Blocks".
Fundamentally, TEN works like any other blockchain and produces a "batch" that has a header and a payload. The difference is that the payload is encrypted and can only be read by enclaves that are part of the network.
The "Host" component is driving "batch production".
Note: L1 reorgs and High Availability introduce some interesting corner cases for batch production.
Each L2 batch has a sequence number and a height. Batches at the same height are guaranteed by the protocol to have the exact same transactions in the exact same order. This guarantees very fast "soft finality" Note: Multiple batches can be generated for the same height due to L1 reorgs.
The TEN protocol is tightly integrated with the L1.
This integration makes it natively resistant to L1 re-orgs and enables fast, reliable and decentralised L1->L2 bridging.
TEN features an L2 side of the bridge managed by the platform. The bridge is a generic message-based system similar to "Wormhole"
The TEN node is connected in real time to an Ethereum node and feeds L1 block headers and relevant events into the enclave. The first L2 batch produced that is linked to this new block, the platform generates synthetic L2 transactions based on every relevant transaction found there.
High level: when Alice deposits 10ABC from her account to the L1 bridge, TEN will execute a synthetic L2 transaction (that it deterministically generated from the L1 transaction), which moves 10WABC from the L2 bridge to Alice's address on Ten.
This logic is part of the consensus of Ten; every node receiving the same block containing the rollup and the deposits will generate the exact same synthetic transaction.
Note: Synthetic transactions are used for other interesting features as well.
Periodically, TEN batches are compressed and added to a "Rollup", which is a data structure that is submitted as a "Blob" to Ethereum. A node that is not connected via P2P or that is started later can catch up from Ethereum and process the same data as the live nodes.
The Rollup has a plaintext header, which is used by the L2->L1 bridge. See below.
Users of the TEN platform can send cross-chain messages by sending transactions to a well-known system contract. The messages generated by these transactions are assembled into a Merkle Tree, and the root is included in the Rollup header.
The L1 bridge implementation can decide to execute these messages when it considers them secure
This is where the TEN-specific cryptography is implemented. See go/enclave/crypto
These are the main components:
When a new node is initialised, each enclave generates a random ECDSA key-pair which it uses to sign over the payloads it produces. The public key is included in the attestation.
When the network is bootstrapped (or after each upgrade), the "genesis" node generates 32 bytes of entropy. We call it the "Master Seed".
This entropy is shared with all the other nodes that can prove (via attestation) that they run an approved version of software.
After receiving the secret, each node can generate (deterministically) all the other secrets.
All user-related RPC requests have to be encrypted with the "TEN public key", which is a key derived from the master seed.
The "TEN public key" is well-known, published in the "TEN Management Contract" by the genesis enclave.
From the user's point of view, this guarantees that only the TEN network can read those requests.
Note: For normal users, the "TEN Gateway" will abstract this.
Responses are encrypted with the "Viewing Key" of the requesting user.
This component manages viewing keys and handles the encryption and decryption.
The transactions received from users are gossiped with the other nodes are also encrypted with the "TEN Public Key".
The payloads of Batches and Rollups are encrypted with an AES cipher generated from the master seed.
Each EVM transaction has in its context a specific entropy unique to it. This entropy is generated from the master seed by hashing repeatedly using the batch hash and the transaction index in the batch.
The enclave exposes an RPC interface generated with proto-buf.
The interface is described in enclave.proto.
See go/common/rpc
Errors returned inside the enclave code are either relevant to the end-user who made a query or to the "Host" component.
End-user errors must be returned encrypted and passed on to the respective user.
Administrative errors are relevant to the "Host" component and are returned in plaintext.
The Host service is the software that is under the control of the operator. It does not run inside a secure Enclave, and there is no attestation on it.
From a threat model point of view, the Host service is seen as an adversary by an Enclave. Any data that it feeds into the Enclave will be verified and considered malicious.
A secure solution that uses confidential computing will generally try to minimize the TCB, and run as much as possible outside the secure Enclave, while still achieving the same security goals.
The Host service is the equivalent of a typical blockchain node, and is responsible for:
See go/host
The missing link to achieving fully private transactions while allowing end-users to continue using their favourite wallets (like MetaMask). This is a very thin component that is responsible for encrypting and decrypting traffic between the TEN node and its clients.
See the docs for more information.
The TEN integration tests are found in: integration/simulation.
The main tests are "simulations", which means they spin up both an L1 network and an L2 network, and then inject random transactions. Due to the non-determinism of both the "mining" protocol in the L1 network and the nondeterminism of POBI, coupled with the random traffic, it allows the tests to capture many corner cases without having to explicitly write individual tests for them.
The first simulation_in_mem_test runs fully in one single process on top of a mocked L1 network and with the networking components of the TEN node swapped out, and is just focused on producing random L1 blocks at very short intervals. The ethereummock implementation is based on the ethereum