Arkiv is a decentralized data layer that brings queryable, time-scoped storage to Ethereum. It enables developers to store, query, and manage data with built-in expiration and annotation systems.

Why Arkiv?

Arkiv treats data as a first-class citizen on Ethereum:

Instant Queries — SQL-like queries with annotations, real-time data retrieval, no external indexing required.

Cost-Efficient — Pay only for storage duration (Expires In), automatic data pruning, no permanent storage fees.

Ethereum-Native — Built on Ethereum infrastructure, fully transparent and verifiable, compatible with existing Web3 tools.

Developer-Friendly — Simple CRUD operations, TypeScript SDK with full type safety, real-time event streaming.

Architecture

Arkiv uses a three-layer architecture:

Layer 1: Ethereum Mainnet Final settlement and security. Proof verification, commitments, and ultimate source of truth.

Layer 2: Arkiv Coordination Layer Data management and registry. DB-chain coordination, cross-chain synchronization, deterministic query resolution.

Layer 3: Specialized DB-Chains High-performance data operations. CRUD via JSON-RPC, indexed queries with annotations, programmable expiration (Expires In).

Use Cases

Temporary Data Storage — Session data with automatic expiration, cross-device clipboards, cached API responses.

Event & Analytics — Application logs with cleanup, user activity tracking, temporary metrics.

File & Media — Image metadata with expiration, document versioning, chunked file storage.

Real-Time Apps — Live chat, collaborative tools, IoT data streams.

Core Concepts

Entities — Data records containing content, annotations, and expiration time.

Annotations — Key-value pairs for querying:

typescriptExample
1type = "note"      // String annotation
2priority = 5       // Numeric annotation

Expires In — Automatic expiration (in seconds):

typescriptExample
1expiresIn: 1800    // 30 minutes
2expiresIn: 86400   // 24 hours
3expiresIn: 604800  // 7 days

Query Language — SQL-like syntax:

sqlExample
1type = "note" && priority > 3 && created > 1672531200

Testnet Access

typescriptExample
1Chain ID:  60138453025
2RPC URL:   https://kaolin.hoodi.arkiv.network/rpc
3WebSocket: wss://kaolin.hoodi.arkiv.network/rpc/ws

Faucet: Get Test ETH Explorer: View Transactions

Quick example:

typescriptExample
1import { createClient, createROClient, Annotation } from 'arkiv-sdk'
2
3// Full client (read/write) - requires private key
4const client = await createClient(
5  60138453025,
6  "YOUR_PRIVATE_KEY",
7  "https://kaolin.hoodi.arkiv.network/rpc",
8  "wss://kaolin.hoodi.arkiv.network/rpc/ws"
9)
10
11const receipt = await client.createEntities([{
12  data: new TextEncoder().encode("Hello Arkiv!"),
13  expiresIn: 1800,
14  stringAnnotations: [new Annotation("type", "greeting")],
15  numericAnnotations: []
16}])
17
18console.log("Stored:", receipt[0].entityKey)
19
20// Read-only client (queries only) - no private key needed
21const roClient = await createROClient(
22  60138453025,
23  "https://kaolin.hoodi.arkiv.network/rpc",
24  "wss://kaolin.hoodi.arkiv.network/rpc/ws"
25)
26
27const data = await roClient.queryEntities('type = "greeting"')

Next Steps

1. Getting Started — Set up your dev environment
2. SDK Reference — TypeScript and Python SDKs
3. API Docs — JSON-RPC interface
4. Guides — Build real applications

Resources: Playground — Interactive examples Discord — Community support