00 · Getting started

This guide takes you from a fresh clone to a working vault on Arkiv's Rabdi testnet in about ten minutes. It covers running everything locally, a tour of the app, using the SDK from your own code, and fixes for the errors you are most likely to hit.

What Kalypso is, in one line: a TypeScript library that encrypts your data on your device, stores only ciphertext and commitments on Arkiv, lets you prove facts about it in zero knowledge, and erases it for good by destroying the keys.

What you need#

You do not need Noir or Barretenberg installed. The compiled circuits ship inside @arkivzk/zk. Run pnpm circuits only if you change a circuit.

1. Install and build#

git clone <this repo> arkivzk && cd arkivzk
pnpm install
pnpm build          # crypto, zk, core, vault, shred, sdk
pnpm test           # unit tests: crypto, zk proof round-trip, range cover, vault

2. Configure#

Create apps/web/.env.local. This file is gitignored. Never commit it.

ARKIV_ACCESS_KEY=<your Hub access key>        # server-side only, used by /api/rpc
RELAYER_PRIVATE_KEY=<funded Rabdi key>        # optional: enables one-time signers
GUARDIAN_URLS=http://127.0.0.1:7101,http://127.0.0.1:7102   # default, can be omitted
ARCHIVE_URL=http://127.0.0.1:7301             # default, can be omitted
BEE_URL=http://127.0.0.1:1633                 # optional: Swarm attachments
SWARM_POSTAGE_BATCH_ID=<batch id>             # optional: Swarm attachments

The browser never sees the access key or the relayer key. Reads go through the app's /api/rpc proxy, and writes are signed by your wallet.

3. Start the services#

Use one terminal per service.

# two guardians: each holds one of the three key shares
cd guardian && pnpm build && pnpm start:g1
cd guardian && pnpm start:g2

# archive node: records raw calldata so you can try to break a shred later
cd archive && pnpm build && set -a && . ../apps/web/.env.local && set +a && pnpm start

# the web app
cd apps/web && pnpm build && pnpm start      # http://localhost:3000

Optional: Swarm attachments. This needs Docker.

npx @fairdatasociety/fdp-play start --fresh --detach   # local Bee cluster on :1633
curl -s -X POST localhost:1633/stamps/100000000/20    # copy the batchID into .env.local

4. A five-minute tour of the app#

5. Use the SDK in your own code#

import { ArkivZK, Vault, MemoryKV, rawKeySealer, GuardianClient, verifyProofEntity } from "@arkivzk/sdk";

const zk = new ArkivZK({
  publicClient,                                     // createPublicClient({ chain: rabdi({ accessKey }), transport: http() })
  vault: await Vault.open(new MemoryKV(), rawKeySealer(deviceKey)),
  guardians: [new GuardianClient("http://127.0.0.1:7101"), new GuardianClient("http://127.0.0.1:7102")],
  write: { chain, rpc, publicClient, provider, account },
});

// store: encrypted on device, searchable by range, kept for 7 days
const { entityKey } = await zk.put({
  schemaId: "medical.v1",
  values: { age: 25, country: "IN" },
  rangeField: "age",
  retentionSeconds: 7 * 24 * 3600,
});

// prove: publish a zero-knowledge claim for one verifier
const { proofEntityKey } = await zk.prove(entityKey, { field: "age", min: 18 }, "pharmacy-42");

// verify: anyone, no keys
const result = await verifyProofEntity(publicClient, proofEntityKey);

// query: Arkiv evaluates tags, never values
const adults = await zk.searchRange("medical.v1", "age", 18, 40);
const total  = await zk.count("medical.v1", "age", { min: 18, max: 40 });   // or { eq: "IN" } on a searchable field

// shred: destroy keys for the record and its children, publish a receipt
await zk.shred([entityKey], () => {}, { cascade: true });

Every method, with options and return types, is in 06 · SDK reference. Relational features (multi-insert, parents, JOIN, cascade) are in §8f.

6. Check it against the live chain#

Each script writes real transactions on Rabdi and fails loudly if a result doesn't match. They need DEV_PRIVATE_KEY (a funded Rabdi key) and ARKIV_ACCESS_KEY in the repo-root .env.

7. Troubleshooting#

Where to go next#

• 01 · Idea, threat model, promises: what we protect against and what we don't
• 04 · Crypto-shredding: the deletion design and key hierarchy
• 07 · Performance: complexity and live measurements
• 08 · Design FAQ: why this is built on top of Arkiv, and the questions judges ask