stacks-k8s provisions disposable Stacks regtest networks for development,
reliability, liveness, resilience, performance and defensive security investigations.
Trusted agents can introduce adversarial conditions and verify reported behavior;
operators expose capabilities and evidence rather than plan experiments.
Apply a StacksNetwork to resolve selected reusable definitions, freeze genesis,
and run its participants. The network reconciles Bitcoin production, Stacks nodes
and consensus signers, transaction demand, PoX enrollment/renewal and sBTC contract
initialization. Genesis funding does not require managed participation: additional
funded accounts can be used by later experiment actors.
Three independently installed products provide:
- Network operation: reusable accounts and definitions, network-owned actors and scoped Go management workers.
- Bounded Bitcoin actions: finite block generation and reorganization through the network's shared execution authority.
- Read-only observation: verified runtime identity and observations, without control of network behavior.
The network operates without actions, observability or Chaos Mesh. With the optional upstream installation, agents can use native Chaos Mesh faults directly and observe their effects independently.
The development target is Kubernetes 1.37.0. Create a three-node kind cluster with Headlamp and Metrics Server:
make cluster-create
export KUBECONFIG="$PWD/tools/local-cluster/kubeconfig"Build and load the operator and compatible Stacks actor images, then install the network chart. Images built from local revisions are supported; see actor images.
The 30-actor example includes accounts, definitions and a paused root. Set its image references and placement for your cluster before applying it. It requires no external bootstrap command:
kubectl --context kind-stacks-k8s apply -f docs/design/public-api/examples/30-actors.yaml
kubectl --context kind-stacks-k8s -n lab-30 patch stacksnetwork network \
--type=merge -p '{"spec":{"operation":"Running"}}'
kubectl --context kind-stacks-k8s -n lab-30 get stacksnetwork,stacksnetworkparticipantInitialization waits for native protocol evidence, not merely Ready Pods or Bitcoin heights. At a five-second Bitcoin cadence, reaching height 300 takes at least 25 minutes, plus initialization holds. Follow operations for pause, terminal stop, destructive removal and cleanup.
| Path | Purpose |
|---|---|
| apis/ | Independently versioned Kubernetes types and schemas |
| libs/ | Portable Go protocol libraries without Kubernetes dependencies |
| operators/ | Independent controller and worker Go modules |
| charts/ | Helm products and generated CRDs |
| contracts/ | Versioned wire-contract fixtures |
| docs/ | Public API, operation, design and qualification evidence |
| tools/ | Repository checks and local cluster lifecycle helpers |
Go owns runtime configuration, signing, RPC, reconciliation and execution.
Stacks.js is a pinned, offline test oracle only; runtime images contain no Node.js.
Run make verify before handoff, and make vuln / make docker-check when
changing dependencies or containers. See development.