Project Structure

This document describes the organization of the Attestor Core codebase, including the L{CORE} privacy layer integration.

Overview

attestor-core/
├── src/                      # Main TypeScript source code
├── cartesi/                  # Cartesi rollup (L\{CORE\} backend)
├── docs/                     # Documentation
├── proto/                    # Protobuf definitions
├── provider-schemas/         # Provider JSON schemas
├── contracts/                # Solidity contracts
└── lib/                      # Compiled output (generated)

Architecture Layers

L{CORE} operates as a two-layer architecture:

Layer	Location	Runtime	Purpose
Attestor	src/	TEE (EigenCloud)	API, Reclaim verification, database
Cartesi	cartesi/	Rollup (EigenCloud)	Deterministic state, privacy controls

---

Source Code (src/)

L{CORE} Client (src/lcore/)

Client library for interacting with the Cartesi L{CORE} backend.

src/lcore/
├── index.ts                  # Exports
├── client.ts                 # LCoreClient - GraphQL/inspect queries
├── encryption.ts             # NaCl box encryption (X25519-XSalsa20-Poly1305)
└── discretize.ts             # Value discretization for privacy

Server (src/server/)

The attestor server implementation. Runs in a TEE (Trusted Execution Environment).

src/server/
├── index.ts                  # Server exports
├── socket.ts                 # WebSocket connection handler
├── create-server.ts          # HTTP/WebSocket server creation
├── handlers/                 # RPC request handlers
│   ├── index.ts              # Handler exports
│   ├── init.ts               # Connection initialization
│   ├── createTunnel.ts       # TCP tunnel creation
│   ├── disconnectTunnel.ts   # Tunnel disconnection
│   ├── claimTunnel.ts        # Claim verification
│   ├── claimTeeBundle.ts     # TEE bundle claims
│   ├── fetchCertificateBytes.ts  # Certificate fetching
│   ├── toprf.ts              # TOPRF operations
│   └── createTaskOnMechain.ts    # Mechain task creation
├── tunnels/                  # Tunnel implementations
│   └── make-tcp-tunnel.ts    # TCP tunnel factory
└── utils/                    # Server utilities
    ├── assert-valid-claim-request.ts  # Claim validation
    ├── config-env.ts         # Environment configuration
    ├── dns.ts                # DNS utilities
    ├── gcp-attestation.ts    # GCP attestation
    ├── keep-alive.ts         # Connection keep-alive
    ├── nitro-attestation.ts  # AWS Nitro attestation
    ├── process-handshake.ts  # TLS handshake processing
    ├── proxy-session.ts      # Proxy session management
    ├── tee-verification.ts   # TEE verification
    └── validation.ts         # Input validation

API Routes (src/api/)

HTTP API endpoints including L{CORE} integration.

src/api/
├── routes/
│   ├── index.ts              # Route registration
│   ├── lcore.ts              # L\{CORE\} API endpoints (/api/lcore/*)
│   ├── operators.ts          # Operator management
│   ├── admins.ts             # Admin operations
│   ├── api-keys.ts           # API key management
│   ├── auth.ts               # Authentication
│   ├── audit.ts              # Audit logging
│   └── stats.ts              # Statistics endpoints
├── auth/                     # Authentication middleware
├── operators/                # Operator logic
└── utils/                    # API utilities

Client (src/client/)

The client SDK for creating claims.

src/client/
├── index.ts                  # Client exports and AttestorClient class
├── create-claim.ts           # createClaimOnAttestor function
├── tunnels/                  # Client-side tunnel implementations
│   ├── make-rpc-tcp-tunnel.ts    # RPC TCP tunnel
│   └── make-rpc-tls-tunnel.ts    # RPC TLS tunnel
└── utils/
    ├── attestor-pool.ts      # Connection pooling
    ├── client-socket.ts      # WebSocket client
    └── message-handler.ts    # Message handling

Providers (src/providers/)

Data provider implementations for different data sources.

src/providers/
├── index.ts                  # Provider registry
└── http/                     # HTTP provider (generic API verification)
    ├── index.ts              # HTTP provider implementation
    ├── utils.ts              # HTTP utilities
    └── patch-parse5-tree.ts  # HTML parsing patches

External RPC (src/external-rpc/)

Browser and JSC (JavaScriptCore) RPC client for mobile/browser environments.

src/external-rpc/
├── index.ts                  # External RPC exports
├── setup-browser.ts          # Browser environment setup
├── setup-jsc.ts              # JSC environment setup
├── handle-incoming-msg.ts    # Message handling
├── event-bus.ts              # Event bus
├── types.ts                  # Type definitions
└── jsc-polyfills/            # JSC environment polyfills

Mechain Integration (src/mechain/)

Integration with Mechain for on-chain settlement.

src/mechain/
├── index.ts                  # Mechain exports
├── constants/index.ts        # Constants
├── types/index.ts            # Type definitions
├── abis/                     # Contract ABIs
│   ├── governanceABI.ts
│   └── taskABI.ts
└── client/
    ├── index.ts
    └── create-claim-on-mechain.ts  # Mechain claim creation

Other Source Directories

src/
├── db/                       # Database layer (Supabase)
├── config/index.ts           # Configuration
├── proto/                    # Protobuf generated types
│   ├── api.ts
│   └── tee-bundle.ts
├── types/                    # TypeScript type definitions
│   ├── index.ts
│   ├── claims.ts
│   ├── client.ts
│   ├── handlers.ts
│   ├── providers.ts
│   ├── providers.gen.ts      # Generated provider types
│   ├── rpc.ts
│   ├── signatures.ts
│   └── tunnel.ts
├── utils/                    # Shared utilities
│   ├── index.ts
│   ├── auth.ts               # Authentication
│   ├── claims.ts             # Claim utilities
│   ├── http-parser.ts        # HTTP response parser
│   ├── logger.ts             # Logging (pino)
│   ├── redactions.ts         # Data redaction
│   ├── tls.ts                # TLS utilities
│   ├── zk.ts                 # ZK proof utilities
│   └── signatures/           # Signature utilities
├── tests/                    # Test files
└── scripts/                  # Build and utility scripts
    ├── start-server.ts       # Server entry point
    ├── generate-receipt.ts   # Receipt generation CLI
    └── generate-provider-types.ts

---

Cartesi Integration (cartesi/)

Cartesi rollup with SQLite-based deterministic state management for L{CORE}.

cartesi/
├── src/
│   ├── index.ts              # Entry point (advance/inspect handlers)
│   ├── lcore-main.ts         # L\{CORE\} main router
│   ├── router.ts             # Request routing
│   ├── db.ts                 # Original SQLite schema
│   ├── lcore-db.ts           # L\{CORE\} SQLite schema and CRUD
│   ├── config.ts             # Configuration
│   ├── encryption.ts         # NaCl encryption utilities
│   ├── schema.d.ts           # TypeScript type definitions
│   ├── handlers/             # Business logic handlers
│   │   ├── lcore-index.ts    # L\{CORE\} handler router
│   │   ├── lcore-discovery.ts    # Schema/discovery queries
│   │   ├── lcore-encryption.ts   # Encrypted data access
│   │   ├── entity.ts         # Entity management
│   │   ├── computation.ts    # Derived calculations
│   │   ├── proof.ts          # Proof verification
│   │   └── approval.ts       # Access approval
│   ├── utils/                # Cartesi utilities
│   │   ├── index.ts
│   │   ├── notice-batcher.ts # Notice batching
│   │   ├── voucher-generator.ts  # Voucher generation
│   │   ├── domain-config.ts  # Domain configuration
│   │   └── db-maintenance.ts # Database maintenance
│   └── __tests__/            # E2E and integration tests
│       ├── e2e-helpers.ts
│       ├── e2e.schema.test.ts
│       ├── e2e.attestation.test.ts
│       ├── e2e.access-control.test.ts
│       └── live-e2e.test.ts
├── Dockerfile                # Cartesi machine image
├── package.json
└── README.md

L{CORE} Query Types

The Cartesi layer supports these inspect query types:

Query Type	Description
all_provider_schemas	List registered provider schemas
provider_schema	Get specific provider schema
attestations_by_owner	Get attestations for an address
check_access	Verify access permissions
grant_access	Grant data access (via InputBox)
revoke_access	Revoke data access (via InputBox)

---

Protocol Definitions

Protobuf (proto/)

proto/
├── api.proto                 # Main RPC protocol definition
└── tee-bundle.proto          # TEE bundle format

Provider Schemas (provider-schemas/)

JSON schemas for provider configuration validation.

provider-schemas/
└── http/                     # HTTP provider schemas
    ├── parameters.yaml       # Public parameters schema
    └── secret-parameters.yaml  # Secret parameters schema

---

Docker Images

Dockerfile	Purpose	Port
attestor.dockerfile	Attestor service	8001
cartesi-node.dockerfile	Cartesi Node wrapper	10000
cartesi/Dockerfile	Cartesi machine image	-

---

Configuration Files

File	Purpose
package.json	Dependencies and scripts
tsconfig.json	TypeScript configuration
tsconfig.build.json	Build-specific TypeScript config
.env.example	Environment variable template
.env.eigencloud	EigenCloud Attestor config
.env.cartesi-eigencloud	EigenCloud Cartesi Node config
docker-compose.yaml	Docker Compose configuration
prod.docker-compose.yaml	Production Docker Compose

---

Key Patterns

Module Imports

The project uses TypeScript path mapping:

// Use #src/* for internal imports
import { something } from '#src/utils/index.ts'

ES Modules

The project uses ES Modules ("type": "module" in package.json):

// ESM imports
import { createClaimOnAttestor } from '@reclaimprotocol/attestor-core'

Provider Architecture

Providers implement a common interface. See provider.md for creating custom providers.

L{CORE} Client Usage

import { LCoreClient } from '#src/lcore/index.ts'

const client = new LCoreClient({
  nodeUrl: 'http://${CARTESI_NODE_IP}:10000',
  rpcUrl: 'https://arb-sepolia.g.alchemy.com/v2/...',
  dappAddress: '0xAE0863401D5B953b89cad8a5E7c98f5136E9C26d',
  inputBoxAddress: '0x59b22D57D4f067708AB0c00552767405926dc768'
})

// Query attestations
const attestations = await client.getAttestationsByOwner('0x...')

---

Credits

L{CORE} is built on:

• Reclaim Protocol - zkTLS proof generation and attestation
• Cartesi - Deterministic rollup execution with Linux environment