Fundamentals

Arkiv is a universal data layer that brings queryable, time-scoped storage to Ethereum. Store, query, and manage data with built-in expiration and attribute systems.

Why Arkiv?

Instant Queries

SQL-like queries with attributes, indexed data retrieval, no external indexing required.

Cost-Efficient

Pay only for storage duration. Automatic data pruning — no permanent storage fees.

Ethereum-Native

Built on Ethereum infrastructure. Fully transparent, tamper-proof, and compatible with existing Web3 tools.

Developer-Friendly

Simple CRUD operations and a TypeScript SDK with full type safety.

Architecture

Arkiv uses a three-layer architecture:

┌─────────────────────────────────────────────────────┐
│  YOUR APP                                           │
│  TypeScript SDK  ·  JSON-RPC                        │
└────────────────────────┬────────────────────────────┘
                         │  read / write
                         ▼
┌─────────────────────────────────────────────────────┐
│  LAYER 3 — DB-CHAINS                                │
│  High-performance CRUD, indexed queries,            │
│  programmable expiration                            │
└────────────────────────┬────────────────────────────┘
                         │  coordination
                         ▼
┌─────────────────────────────────────────────────────┐
│  LAYER 2 — ARKIV COORDINATION LAYER                 │
│  DB-chain registry,                                 │
│  deterministic query resolution                     │
└────────────────────────┬────────────────────────────┘
                         │  settlement
                         ▼
┌─────────────────────────────────────────────────────┐
│  LAYER 1 — ETHEREUM MAINNET                         │
│  Proof verification, commitments,                   │
│  ultimate source of truth                           │
└─────────────────────────────────────────────────────┘

Core Concepts

Entities

An entity is a data record on Arkiv. Every entity contains:

• Payload — The actual data (JSON, text, binary)
• Attributes — Key-value pairs for querying (string or numeric)
• ExpiresIn — Automatic expiration measured in seconds
• Content Type — MIME type of the payload

Attributes

Attributes are the backbone of querying. The type you choose determines what query operators are available:

// String attributes — support eq(), glob matching (~)
{ key: 'type', value: 'note' }
{ key: 'status', value: 'active' }

// Numeric attributes — support eq(), gt(), lt(), gte(), lte() range queries
{ key: 'priority', value: 5 }
{ key: 'created', value: Date.now() }

Caution

If you store a number as a string ({ key: 'priority', value: '5' }), you lose the ability to do range queries with gt(), lt(), etc. Always use numeric values for attributes you plan to filter by range.

ExpiresIn

Every entity has a lifespan expressed in seconds. Use the ExpirationTime helper to convert human-readable durations:

import { ExpirationTime } from "@arkiv-network/sdk/utils";

ExpirationTime.fromMinutes(30)  // 1800 seconds
ExpirationTime.fromHours(1)     // 3600 seconds
ExpirationTime.fromHours(12)    // 43200 seconds
ExpirationTime.fromDays(7)      // 604800 seconds

Note

Entities can be extended before they expire using extendEntity(). Over-allocating expiration wastes storage fees — start short and extend if needed.

Query Language

SQL-like syntax for filtering entities:

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

Supported operators: && (AND), || (OR), ! (NOT), =, !=, <, >, <=, >=, ~ (glob match).

Clients

Two client types exist:

1. WalletClient (read/write) — Requires a private key or wallet connection. Use for creating, updating, deleting entities.
2. PublicClient (read-only) — No private key needed. Use for queries. Safe for frontend use.

What You Can Query

The SDK’s query builder supports more than basic filtering. Before you reach for client-side sorting or manual pagination, check what’s built in:

• Ordering — sort results by any numeric attribute with orderBy(desc('field', 'number'))
• Pagination — cursor-based, up to 200 results per page with hasNextPage() / next()
• Entity count — get a count without fetching entities via getEntityCount()
• Owner & creator filters — .ownedBy() and .createdBy() for wallet-level filtering

Full reference: Querying Data

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.
• Full-Stack Applications — Dashboards, collaborative tools, browser-based dApps with wallet signing.