wickra

README

Wickra ZK — Go

---

Wickra ZK — for Go. go get github.com/wickra-lib/wickra-zk-go — over the C ABI via cgo, prebuilt library bundled in the module.

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

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>/. On Linux/macOS the library path is baked in via rpath; on Windows the DLL must be discoverable at run time (next to the executable or on PATH).

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.

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).

Benchmark

Every binding forwards to the same data-driven Rust core, so what this one adds is the call overhead of cgo over the C ABI, not a different result. The core's throughput is measured by the repository's benchmark suite and the nightly bench.yml run; the numbers, the machine and how to reproduce them are in the repository BENCHMARKS.md.

Documentation

The full guide, the spec reference and the API documentation live in the main repository and the documentation site:

• Repository: https://github.com/wickra-lib/wickra-zk
• Docs (guides, spec reference, cookbook): https://zk.wickra.org
• Runnable example: examples/go/

Wickra ZK ships native bindings for Python, Node.js, WASM and Rust, plus a C ABI hub that any C-capable language (C, C++, C#, Go, Java, R) links against — all forwarding to the same data-driven, unsafe-forbidden Rust core.

Security

Found a security issue? Please don't open a public issue. Report it privately via the repository's Security tab ("Report a vulnerability") or email support@wickra.org with a subject line starting [wickra security]. Full policy: https://github.com/wickra-lib/wickra-zk/blob/main/SECURITY.md.

Disclaimer

This software is provided for research and educational purposes. It is not financial advice. A zero-knowledge proof attests only to the honest execution of the pinned guest program over the prover's inputs; it makes no claim about the quality, provenance, or future performance of a trading strategy.

License

Licensed under either of Apache-2.0 or MIT 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.