-9945FF?style=flat-square){kind=icon}
-orange?style=flat-square){kind=icon}
π¦ nullifier β proof β compressed state β provable AI π¦
> **A zero-knowledge primitive layer for Solana-native AI models.** > Built on [Light Protocol](https://www.zkcompression.com). > Powers the on-chain identity, attestation, and encrypted-state > layer for the Clawd agent fleet β and yes, its mascot is a > shark. π¦ More on that below. --- ## πΏ The 30-second version Your model did some work. How does anyone *else* β another agent, a smart contract, a curious human β know that's true, that it only happened once, and that nobody's cheating the reward pool? That's what this repo answers, in three moves: ``` βββββββββββββββ βββββββββββββββββββββ ββββββββββββββββββββββ β 1. PROVE β ββββΆ β 2. STAMP ONCE β ββββΆ β 3. STORE FOR FREE β β Groth16 SNARKβ β Nullifier registryβ β Light-compressed β β "I did the β β "this exact actionβ β state (rent-free, β β work, here'sβ β happened exactly β β ~26β32 deep tree) β β the proof" β β once, ever" β β β βββββββββββββββ βββββββββββββββββββββ ββββββββββββββββββββββ π π«π πΎ ``` No re-used proofs. No double-claimed rewards. No 890,880-lamport rent bill per record. Just a receipt, a stamp, and a cheap place to keep it β all verifiable by anyone with an RPC endpoint. ## 𧩠The three primitives | # | Primitive | What it buys you | Cost | |---|---|---|---| | 1 | **Nullifier registry** π«π | A 32-byte, deterministic, per-action hash proving an action happened *exactly once*. Anti-double-publish, anti-double-claim, anti-double-inference-reward. | 15,000 lamports/nullifier (compressed PDA) vs. 890,880 for a regular PDA | | 2 | **Groth16 proof verification** π | On-chain bn128/alt-bn128 zk-SNARK verifier. Proves model inference correctness, encrypted-state commitment, license-bound authorization, ZK identity. | ~200k CU | | 3 | **Compressed state (Light Protocol)** πΎ | Model metadata, attestations, and encrypted params live in rent-free compressed accounts. Reads via Helius Photon, writes via CPI to the Light System Program. | 26-deep (V1) / 32-deep (V2) trees | π The deep dive β design, cost math, security model β lives in [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md). π The edge install/metadata surface is in [`docs/EDGE_DISTRIBUTION.md`](./docs/EDGE_DISTRIBUTION.md). ## ποΈ Repo layout ``` zk-primitives/ βββ README.md β you are here βββ package.json β pnpm workspace root (jayson>uuid override) βββ pnpm-workspace.yaml β workspace: agent, client βββ docs/ β βββ ARCHITECTURE.md β deep dive: design, costs, security β βββ INTEGRATION.md β runtime catalog and trust gates β βββ EDGE_DISTRIBUTION.md β Cloudflare metadata surface β βββ PIEDPIPER_ADAPTATION.md β classicalβZK algorithm map βββ programs/ β βββ clawd-zk/ β Anchor program (Rust, on-chain) β βββ Cargo.toml β βββ Xargo.toml β βββ src/ β βββ lib.rs β program entry, instruction dispatch β βββ nullifier.rs β compressed-PDA nullifier logic β βββ proof.rs β Groth16 verifier wrapper β βββ state.rs β compressed state writes / consumes βββ client/ β π§° TypeScript SDK (@clawd/zk-client) β βββ package.json β βββ tsconfig.json β βββ src/ β βββ index.ts β public exports β βββ types.ts β shared types β βββ nullifier.ts β nullifier computation β βββ proof.ts β public-input packing + proof serialization β βββ state.ts β Light Protocol helpers β βββ client.ts β high-level ClawdZkClient βββ agent/ β π¦ ZK Shark agent (@clawd/zk-shark-agent) β βββ package.json β βββ tsconfig.json β βββ README.md Β· SKILL.md Β· agent.json β βββ src/ β βββ index.ts β public exports β βββ agent.ts β ZkSharkAgent / ClawdZkAgent β βββ config.ts β env-driven config loader β βββ intents.ts β natural-language intent router β βββ cli.ts β zk-shark-agent CLI βββ tests/ β integration tests β βββ nullifier.test.ts β vitest, off-chain pieces β βββ nullifier.rs β cargo test-sbf, on-chain pieces βββ configs/ βββ light-trees.yaml β canonical V2 tree pubkeys ``` Two ways to use this stack: - **`client/`** β the raw SDK. You drive nullifiers, proofs, and instructions yourself. Maximum control. - **`agent/`** β π¦ **ZK Shark**, *the Shark of All Streets*. A typed wrapper + CLI + natural-language intent router built on top of `client/`, so an agent can just say *"attest this model"* instead of hand-assembling instructions. Named in honor of zk Shark, the legend of ordinals. See [`agent/README.md`](./agent/README.md). ## βοΈ The three instructions ```text publish_attestation(model_hash, payload_commitment, proof, nullifiers) βββ Verifies Groth16(attester, model_hash, payload_commitment, nullifiers) βββ CPI β Light System Program β βββ Create nullifier compressed PDA at derived address β βββ Write AttestationAccount (compressed state) βββ Emits: tx log, ~25,000 lamports, ~618k CU consume_attestation(attestation_address, consume_nonce, proof) βββ Verifies Groth16(consumer, attestation_address, consume_nonce) βββ CPI β Light System Program β βββ Read+modify AttestationAccount (status 0β1) βββ Emits: tx log, ~5,000 lamports, ~310k CU commit_encrypted_state(model_hash, ciphertext_commitment, version, proof) βββ Verifies Groth16(committer, model_hash, ciphertext_commitment, version) βββ CPI β Light System Program β βββ Write EncryptedStateAccount (compressed state) βββ Emits: tx log, ~5,300 lamports, ~410k CU ``` ## π Quick start ### Install ```bash # On-chain program deps cd programs/clawd-zk cargo build-sbf # TypeScript workspace (client + agent, from the repo root) cd ../.. pnpm install ``` ### Use the raw SDK (`@clawd/zk-client`) ```ts import { ClawdZkClient, computeNullifier } from "@clawd/zk-client"; import { createSolanaRpc, createKeyPairSignerFromBytes } from "@solana/kit"; const rpc = createSolanaRpc("https://mainnet.helius-rpc.com?api-key=..."); const signer = await createKeyPairSignerFromBytes(secretKey); const client = new ClawdZkClient({ rpc, programId: PROGRAM_ID }); // 1. Compute the nullifier. const nullifier = await computeNullifier({ secret: signer.secretKey, context: "model-attestation:abc123", }); // 2. Build the publish-attestation instruction. // (The Groth16 proof is generated off-chain and supplied by the caller.) const ix = await client.publishAttestation({ signer: signer.address, modelHash: hexToBytes("ab12..."), payloadCommitment: hexToBytes("cd34..."), nullifier, proof: { a: proofA, b: proofB, c: proofC, verifyingKey }, }); // 3. Send. const sig = await sendAndConfirm([ix], signer); console.log("attestation published:", sig); ``` ### Or let π¦ ZK Shark do the wiring for you ```ts import { ZkSharkAgent } from "@clawd/zk-shark-agent"; const agent = await ZkSharkAgent.fromEnv(); const { nullifierHex, signature } = await agent.attestModel({ modelHash, payloadCommitment, proof, context: "model-attest:v1:my-model", }); ``` ...or from the command line: ```bash zk-shark-agent inspect zk-shark-agent attest