feat(vindex/mapfn): add WASM guest SDK, wazero sandbox host, examples, and CLI

go.mod

@@ -6,9 +6,11 @@ toolchain go1.27.3
 
 require (
 	github.com/prometheus/client_golang v1.25.0
+	github.com/tetratelabs/wazero v1.12.0
 	github.com/transparency-dev/formats v0.1.2-0.20261027211732-55fe9bf0fa53
 	github.com/transparency-dev/merkle v0.0.2
 	golang.org/x/mod v0.42.0
+	golang.org/x/net v0.62.0
 	k8s.io/klog/v2 v2.140.0
 )
 
@@ -24,5 +26,6 @@ require (
 	github.com/prometheus/procfs v0.22.0 // indirect
 	golang.org/x/crypto v0.58.0 // indirect
 	golang.org/x/sys v0.49.0 // indirect
+	golang.org/x/text v0.43.0 // indirect
 	google.golang.org/protobuf v1.36.12 // indirect
 )

go.sum

@@ -22,6 +22,8 @@ github.com/prometheus/procfs v0.22.0 h1:6q9+/JL9IKAPbCmBrv9n5O5Ty3NKnciV5X7YGw0o
 github.com/prometheus/procfs v0.22.0/go.mod h1:CvmFr/GVhIjIvWJZW3tgkODBQMRIf0EyWMQLHCHab58=
 github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
 github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
+github.com/tetratelabs/wazero v1.12.0 h1:DuWcpNu/FzgEXgGBDp8J1Spc+CWOvvtvVyjKlaZopYU=
+github.com/tetratelabs/wazero v1.12.0/go.mod h1:LvKtzl2RqO4gyF27BiXU+nKAjcV8f38U+kP/q2vgxh0=
 github.com/transparency-dev/formats v0.1.2-0.20261027211732-55fe9bf0fa53 h1:yhYk19lcG42d9r9m957D5HpDIeP+NgpuTKy/S50++y0=
 github.com/transparency-dev/formats v0.1.2-0.20261027211732-55fe9bf0fa53/go.mod h1:AcGPVj62+dtCMlD/pdeG1LeUkYo0D+IHRWg1LmQazGE=
 github.com/transparency-dev/merkle v0.0.2 h1:Q9nBoQcZcgPamMkGn7ghV8XiTZ/kRxn1yCG81+twTK4=
@@ -36,8 +38,12 @@ golang.org/x/crypto v0.58.0 h1:COkYLr4k7nDI4r6QtMML2AfzeIswWHAJthLS6K/M/54=
 golang.org/x/crypto v0.58.0/go.mod h1:Xh+kl5A+M0gMiWDytH2Hhr5Z7WbNCpv/eB/EFgfSk+w=
 golang.org/x/mod v0.42.0 h1:ICeL3t2L30ljSPHHxDnR4fqVcBt/zR2zJAb9juavmQg=
 golang.org/x/mod v0.42.0/go.mod h1:u5fzIrRInkL8MaO1cbRkUHT64v303YIT5KEqpNr7jRs=
+golang.org/x/net v0.62.0 h1:18ELalfM5+XNRwzM2nYqXsZQ9ByS1uhj2O/U7+5jqRY=
+golang.org/x/net v0.62.0/go.mod h1:WgDCOTH8iwtB66T4/GfI94AHo/hhdb7Hah9NDseQfiI=
 golang.org/x/sys v0.49.0 h1:XbzkgYJHdqh/8m2Uu0W/dQv8nktxx4BFHp1M0gROTXA=
 golang.org/x/sys v0.49.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
+golang.org/x/text v0.43.0 h1:1QivrlhwAsnMOcqgOdl9my7s9OyZl8O5/UGUTJVXoWc=
+golang.org/x/text v0.43.0/go.mod h1:hbSIYA/amXcRXTFSZqh8tWHEoqRvvbKPJ2uz/KU+a+s=
 google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
 google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 k8s.io/klog/v2 v2.140.0 h1:Tf+J3AH7xnUzZyVVXhTgGhEKnFqye14aadWv7bzXdzc=

vindex/cmd/vindex-wasm/bench_cmd.go

@@ -0,0 +1,176 @@
+// Copyright 2026 The Transparency Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"os"
+	"slices"
+	"sync"
+	"time"
+
+	"github.com/transparency-dev/incubator/vindex/internal/wasmhost"
+)
+
+func runBenchCmd(ctx context.Context, args []string) error {
+	fs := flag.NewFlagSet("bench", flag.ContinueOnError)
+	wasmPath := fs.String("wasm", "", "Path to compiled WASM plugin file (required).")
+	inputStr := fs.String("input", "github.com/example/benchmodule v1.2.3 h1:benchHash123456789=\n", "Benchmark input leaf payload.")
+	inputFile := fs.String("input_file", "", "Path to file containing input leaf payload.")
+	bundleSize := fs.Int("bundle_size", int(wasmhost.DefaultBundleSize), "Number of leaves per bundle (defaults to 256).")
+	iterations := fs.Int("iterations", 1000, "Total number of bundle executions.")
+	workers := fs.Int("workers", 4, "Number of concurrent worker goroutines and pool size.")
+
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+
+	if *wasmPath == "" {
+		return errors.New("--wasm flag is required")
+	}
+	if *iterations <= 0 {
+		return errors.New("--iterations must be greater than 0")
+	}
+	if *bundleSize <= 0 {
+		*bundleSize = int(wasmhost.DefaultBundleSize)
+	}
+	if *workers <= 0 {
+		*workers = 1
+	}
+
+	wasmBytes, err := os.ReadFile(*wasmPath)
+	if err != nil {
+		return fmt.Errorf("failed to read WASM file %q: %w", *wasmPath, err)
+	}
+
+	var inputBytes []byte
+	if *inputFile != "" {
+		b, err := os.ReadFile(*inputFile)
+		if err != nil {
+			return fmt.Errorf("failed to read input file %q: %w", *inputFile, err)
+		}
+		inputBytes = b
+	} else {
+		inputBytes = []byte(*inputStr)
+	}
+
+	bundle := make([][]byte, *bundleSize)
+	for i := range bundle {
+		bundle[i] = inputBytes
+	}
+
+	wasmHost, err := wasmhost.NewWASMHost(ctx, wasmBytes, *workers)
+	if err != nil {
+		return fmt.Errorf("failed to initialize WASM host: %w", err)
+	}
+	defer func() { _ = wasmHost.Close(ctx) }()
+
+	// Warmup
+	for i := 0; i < 10; i++ {
+		if _, err := wasmHost.MapBundle(ctx, bundle); err != nil {
+			return fmt.Errorf("warmup MapBundle failed: %w", err)
+		}
+	}
+
+	latencies := make([]time.Duration, *iterations)
+	taskChan := make(chan int, *iterations)
+	for i := 0; i < *iterations; i++ {
+		taskChan <- i
+	}
+	close(taskChan)
+
+	start := time.Now()
+	var wg sync.WaitGroup
+	var execErr error
+	var errMu sync.Mutex
+
+	for w := 0; w < *workers; w++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			runner, err := wasmHost.NewRunner(ctx)
+			if err != nil {
+				errMu.Lock()
+				if execErr == nil {
+					execErr = err
+				}
+				errMu.Unlock()
+				return
+			}
+			defer func() { _ = runner.Close(ctx) }()
+
+			for idx := range taskChan {
+				t0 := time.Now()
+				_, err := runner.MapBundle(ctx, bundle)
+				d := time.Since(t0)
+				if err != nil {
+					errMu.Lock()
+					if execErr == nil {
+						execErr = err
+					}
+					errMu.Unlock()
+					return
+				}
+				latencies[idx] = d
+			}
+		}()
+	}
+
+	wg.Wait()
+	totalElapsed := time.Since(start)
+
+	if execErr != nil {
+		return fmt.Errorf("benchmark execution failed: %w", execErr)
+	}
+
+	// Calculate stats
+	slices.Sort(latencies)
+	n := len(latencies)
+	var sum time.Duration
+	for _, l := range latencies {
+		sum += l
+	}
+
+	minLat := latencies[0]
+	p50Lat := latencies[n*50/100]
+	p90Lat := latencies[n*90/100]
+	p99Lat := latencies[n*99/100]
+	maxLat := latencies[n-1]
+	meanLat := sum / time.Duration(n)
+
+	totalLeaves := (*iterations) * (*bundleSize)
+	bundlesPerSec := float64(*iterations) / totalElapsed.Seconds()
+	leavesPerSec := float64(totalLeaves) / totalElapsed.Seconds()
+	mbPerSec := (float64(len(inputBytes)*totalLeaves) / (1024 * 1024)) / totalElapsed.Seconds()
+
+	fmt.Printf("--- WASM MapFn Benchmark Results ---\n")
+	fmt.Printf("Bundle Iterations:%d (%d leaves/bundle, %d total leaves)\n", *iterations, *bundleSize, totalLeaves)
+	fmt.Printf("Workers (pool):   %d\n", *workers)
+	fmt.Printf("Input payload:    %d bytes/leaf\n", len(inputBytes))
+	fmt.Printf("Total Elapsed:    %v\n", totalElapsed)
+	fmt.Printf("Throughput:       %.2f leaves/sec (%.2f bundles/sec, %.2f MB/s)\n", leavesPerSec, bundlesPerSec, mbPerSec)
+	fmt.Printf("Latencies:\n")
+	fmt.Printf("  Min:  %v\n", minLat)
+	fmt.Printf("  Mean: %v\n", meanLat)
+	fmt.Printf("  p50:  %v\n", p50Lat)
+	fmt.Printf("  p90:  %v\n", p90Lat)
+	fmt.Printf("  p99:  %v\n", p99Lat)
+	fmt.Printf("  Max:  %v\n", maxLat)
+
+	return nil
+}

vindex/cmd/vindex-wasm/inspect_cmd.go

@@ -0,0 +1,100 @@
+// Copyright 2026 The Transparency Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"errors"
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/transparency-dev/incubator/vindex/internal/wasmhost"
+)
+
+func runInspectCmd(ctx context.Context, args []string) error {
+	fs := flag.NewFlagSet("inspect", flag.ContinueOnError)
+	wasmPath := fs.String("wasm", "", "Path to compiled WASM plugin file (required).")
+
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+
+	if *wasmPath == "" {
+		return errors.New("--wasm flag is required")
+	}
+
+	wasmBytes, err := os.ReadFile(*wasmPath)
+	if err != nil {
+		return fmt.Errorf("failed to read WASM file %q: %w", *wasmPath, err)
+	}
+
+	compiled, err := wasmhost.CompileModule(ctx, wasmBytes)
+	if err != nil {
+		return fmt.Errorf("failed to compile WASM module: %w", err)
+	}
+
+	exports := compiled.ExportedFunctions()
+	imports := compiled.ImportedFunctions()
+	memories := compiled.ExportedMemories()
+
+	hasMemory := memories["memory"] != nil
+	hasInputBuf := exports["input_buffer"] != nil
+	hasMapBundle := exports["map_bundle"] != nil
+
+	digest := sha256.Sum256(wasmBytes)
+	fmt.Printf("=== VIndex WASM MapFn Inspection: %s ===\n", *wasmPath)
+	fmt.Printf("Module Size: %d bytes (%.2f KB)\n", len(wasmBytes), float64(len(wasmBytes))/1024.0)
+	fmt.Printf("MapFn (base64): %s\n", base64.StdEncoding.EncodeToString(digest[:]))
+	fmt.Printf("SHA-256 (hex): %x\n\n", digest)
+
+	fmt.Println("Required ABI Exports:")
+	if hasMemory {
+		fmt.Println("  [✓] memory")
+	} else {
+		fmt.Println("  [✗] memory: MISSING")
+	}
+	if hasInputBuf {
+		fmt.Println("  [✓] input_buffer () -> i32 (static 4 MB input slab)")
+	} else {
+		fmt.Println("  [✗] input_buffer () -> i32: MISSING")
+	}
+	if hasMapBundle {
+		fmt.Println("  [✓] map_bundle (i32, i32) -> i64 (batch tile ABI)")
+	} else {
+		fmt.Println("  [✗] map_bundle (i32, i32) -> i64: MISSING")
+	}
+
+	fmt.Printf("\nImports (%d):\n", len(imports))
+	for _, imp := range imports {
+		mod, name, _ := imp.Import()
+		fmt.Printf("  - %s.%s\n", mod, name)
+	}
+
+	fmt.Println("\nABI Compatibility Status:")
+	if hasMemory && hasInputBuf && hasMapBundle {
+		host, err := wasmhost.NewWASMHost(ctx, wasmBytes, 1)
+		if err != nil {
+			return fmt.Errorf("module failed VIndex host instantiation: %w", err)
+		}
+		_ = host.Close(ctx)
+		fmt.Println("  >>> PASSED: Compatible with VIndex host runtime (vindexd).")
+		return nil
+	}
+
+	return errors.New("module failed VIndex MapFn ABI requirements")
+}

vindex/cmd/vindex-wasm/main.go

@@ -0,0 +1,78 @@
+// Copyright 2026 The Transparency Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// vindex-wasm is a developer tool and test harness for VIndex WASM MapFn plugins.
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+)
+
+func main() {
+	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer cancel()
+
+	if err := run(ctx, os.Args[1:]); err != nil {
+		if !errors.Is(err, context.Canceled) {
+			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		}
+		os.Exit(1)
+	}
+}
+
+func run(ctx context.Context, args []string) error {
+	if len(args) == 0 {
+		printUsage()
+		return errors.New("subcommand required")
+	}
+
+	subcmd := args[0]
+	subArgs := args[1:]
+
+	switch subcmd {
+	case "test":
+		return runTestCmd(ctx, subArgs)
+	case "inspect":
+		return runInspectCmd(ctx, subArgs)
+	case "bench":
+		return runBenchCmd(ctx, subArgs)
+	case "-h", "--help", "help":
+		printUsage()
+		return nil
+	default:
+		printUsage()
+		return fmt.Errorf("unknown subcommand %q", subcmd)
+	}
+}
+
+func printUsage() {
+	fmt.Fprintf(os.Stderr, `vindex-wasm is a utility tool for testing and benchmarking VIndex WASM MapFn plugins.
+
+Usage:
+  vindex-wasm <command> [options]
+
+Commands:
+  inspect              Inspect a WASM binary and verify VIndex MapFn ABI exports and imports.
+  test                 Execute a WASM MapFn against an input leaf and inspect mapped entries.
+  bench                Benchmark execution throughput and latency percentiles of a WASM MapFn.
+  help                 Display this help message.
+
+Use "vindex-wasm <command> -h" for more information about a command.
+`)
+}