umbra-zk

Modular Zero-Knowledge Toolkit for the Agentic RWA Economy

---

Overview

umbra-zk is a Go-based Zero-Knowledge proof toolkit that enables AI Agents to trade Real World Assets (RWA) on behalf of human owners — without ever revealing the owner's identity on-chain.

Built for compliance under the Digital Asset Market Clarity Act of 2025 (CLARITY Act).

Architecture

graph TB
    subgraph Sovereign Owner
        SO[Human / Institution<br/>Cold Keys / HSM]
    end

    subgraph Delegation
        DG[DelegationGrant<br/>Signed by Root Key]
    end

    subgraph AI Agent TEE
        AG[Autonomous Agent<br/>Ephemeral Session Keys]
        WB[Witness Bridge<br/>Protobuf → gnark]
    end

    subgraph umbra-zk Prover
        direction TB
        ENG[Prover Engine<br/>Groth16 / BN254]
        ID[Identity Gadget<br/>EdDSA Verify]
        CO[Compliance Gadget<br/>SMT Non-Membership]
        SC[Scope Gadget<br/>Limits + Whitelist]
    end

    subgraph On-Chain
        VER[Verifier Contract<br/>transferWithProof]
    end

    SO -->|signs| DG
    DG -->|authorizes| AG
    AG -->|gRPC ProofRequest| WB
    WB -->|witness| ENG
    ENG --> ID
    ENG --> CO
    ENG --> SC
    ENG -->|Groth16 π| VER

    style SO fill:#1a1a2e,stroke:#e94560,color:#fff
    style DG fill:#16213e,stroke:#0f3460,color:#fff
    style AG fill:#0f3460,stroke:#533483,color:#fff
    style ENG fill:#533483,stroke:#e94560,color:#fff
    style VER fill:#e94560,stroke:#fff,color:#fff

Loading

Project Structure

umbra-zk/
├── cmd/
│   ├── prover/              # gRPC Prover CLI (--setup, --serve)
│   └── aggregator/          # Phase 3: BW6-761 recursive aggregator
├── pkg/
│   ├── circuit/delegation/  # Core Delegation Proof circuit
│   ├── identity/            # EdDSA verification gadget
│   ├── merkle/              # Sparse Merkle Tree gadget
│   ├── compliance/          # Composable compliance rules
│   └── types/               # Domain types
├── internal/prover/
│   ├── engine.go            # Groth16 engine (sync.Once, slog)
│   ├── server.go            # gRPC ProverService handler
│   └── witness_bridge.go    # Protobuf → gnark witness mapper
├── proto/umbra/v1/          # gRPC + Protobuf definitions
├── Taskfile.yml             # Task automation
├── Dockerfile               # Multi-stage (distroless)
└── Makefile                 # Legacy build system

Quickstart

Prerequisites

• Go 1.23+
• Task (optional, recommended)

Build & Test

# Using Task
task build
task test

# Or using Make
make build
make test

Trusted Setup

task circuit-setup
# → delegation.pk (proving key)
# → delegation.vk (verification key)

Start the Prover Service

# Start gRPC server on :50051
task serve

# Or directly
go run ./cmd/prover --serve --port :50051

# With pre-computed keys
go run ./cmd/prover --serve --pk delegation.pk --vk delegation.vk

Docker

# Build image
task docker-build

# Run (mount pre-computed keys)
docker run -p 50051:50051 -v ./keys:/keys umbra-zk:0.1.0

The ZK Handshake

When an Agent executes a trade, it generates a proof attesting to five statements:

#	Verification	What It Proves
1	Grant Validity	A human authorized this agent key
2	Action Auth	This trade was signed by the authorized agent
3	Binding Check	The grant belongs to this agent (prevents theft)
4	Scope Enforcement	Trade is within limits and asset whitelist
5	Sanctions Compliance	Owner is NOT on the sanctions list

Ex-ante compliance: If any check fails, no proof is generated — the transaction never reaches the network.

Circuit Metrics

Metric	Value
Curve	BN254
Constraints	38,421
Public Inputs	2 (SanctionsRoot, GrantHash)
Secret Inputs	90
Proof System	Groth16

gRPC API

service ProverService {
  rpc GenerateProof(ProofRequest) returns (ProofResponse);
  rpc VerifyProof(VerifyRequest) returns (VerifyResponse);
  rpc StreamProofs(stream ProofRequest) returns (stream ProofResponse);
}

See proto/umbra/v1/delegation.proto for full message definitions.

Technology Stack

Component	Choice	Rationale
Language	Go 1.23+	Cloud-native, zero FFI tax
ZK Engine	gnark v0.11.0	Parallel witness gen, >200M constraints
Curves	BN254 / BW6-761	2-chain cycle for recursion
Transport	gRPC + Protobuf	<25ms latency, HTTP/2 multiplexing
Logging	log/slog	Structured JSON logging
Container	Distroless	Minimal attack surface

Roadmap

Phase	Timeline	Status
Phase 1	Q1 2026	✅ Foundation + gRPC service
Phase 2	Q3 2026	🔲 MVP on Sepolia testnet
Phase 3	Q4 2026	🔲 GPU Aggregation + Audit

License

MIT License — © 2026 Umbra Research. See LICENSE for details.