wickra

README

Wickra ZK — Go

---

Zero-knowledge proofs of backtest performance for Go, over the Wickra C ABI hub via cgo.

Wickra ZK runs the deterministic wickra-backtest engine inside a RISC Zero zkVM guest and turns the receipt into a proof of the report's hash and headline metrics that reveals neither the candles nor the strategy. This package is the Go binding: it consumes the C ABI hub through cgo and exposes the Prover handle with the same JSON command envelope as every other binding.

Install

Use the published wickra-zk-go module, which bundles the prebuilt C ABI library for every platform, so go get + go build works with no extra steps (a C compiler is still required, as the binding uses cgo):

go get github.com/wickra-lib/wickra-zk-go

Quick start

package main

import (
	"fmt"

	wickra "github.com/wickra-lib/wickra-zk-go"
)

func main() {
	p := wickra.New()
	defer p.Close()

	cmd := `{"cmd":"prove","spec":{"strategy":{...}},` +
		`"candles":[{"time":1,"open":100,"high":101,"low":99,"close":100,"volume":1000}]}`

	proof, err := p.Command(cmd)
	if err != nil {
		panic(err)
	}
	fmt.Println(proof) // {"receipt":…,"journal":{"report_hash":"…","dataset_commitment":"…","guest_id":"…",…},"version":"…"}
	fmt.Println(wickra.Version())
}

Commands

Command	Payload	Response
prove	{spec: {strategy, dataset_commitment?}, candles}	{receipt, journal, version}
commit	{candles}	{dataset_commitment}
verify	{proof}	{report_hash, dataset_commitment, guest_id, sharpe, pnl, n_trades}
version	—	{version, guest_id}

The envelope is documented once, in docs/ZK.md. dataset_commitment may be omitted from a prove spec; the host computes it from the candles. Proving runs a zkVM: seconds to minutes.

Domain errors are reported in-band as {"ok":false,"error":"…"}; the Go error is reserved for ABI-level failures (a null argument, a caught panic).

wickra-zk-go is generated from this directory by the release pipeline: it mirrors the Go sources, the vendored C ABI header (include/wickra_zk.h) and the prebuilt libraries under lib/<goos>_<goarch>/ for Linux and macOS (risc0 has no Windows host, so there is no Windows library to mirror).

Building from this repository (contributors)

This bindings/go directory is the development source. To build it directly, compile the C ABI hub and stage the library into the per-platform directory cgo links against:

cargo build -p wickra-zk-c --release
mkdir -p bindings/go/lib/linux_amd64                 # match your GOOS_GOARCH
cp target/release/libwickra_zk.so    bindings/go/lib/linux_amd64/   # Linux
cp target/release/libwickra_zk.dylib bindings/go/lib/darwin_arm64/  # macOS (arm64)
cp target/release/wickra_zk.dll      bindings/go/lib/windows_amd64/ # Windows

Then, with the library on the loader path, run go test ./... from this directory.

License

Dual-licensed under MIT or Apache-2.0, at your option.

Documentation

Overview

Package wickra provides idiomatic Go bindings for wickra-zk over its C ABI hub: create a stateless Prover, drive it with command JSON (prove, verify, version) and read back the response JSON — the same protocol as the CLI and every other binding.

The binding links the prebuilt C ABI library, staged per platform under ./lib/<goos>_<goarch>/, with the header vendored under ./include.

Index

• func Version() string
• type Prover
  • func New() *Prover
  • func (p *Prover) Close()
  • func (p *Prover) Command(cmdJSON string) (string, error)

Functions

func Version

func Version() string

Version returns the library version.

Types

type Prover

type Prover struct {
	// contains filtered or unexported fields
}

Prover is a stateless prover driven by JSON commands.

func New

func New() *Prover

New creates a stateless prover. Call Close when done (a finalizer also frees it, but explicit Close is preferred).

func (*Prover) Close

func (p *Prover) Close()

Close frees the prover handle. Safe to call more than once.

func (*Prover) Command

func (p *Prover) Command(cmdJSON string) (string, error)

Command applies a command JSON and returns the response JSON. It uses the C ABI's length-out protocol: a first call learns the length, then the response is read into a caller-owned buffer.