Documentation
¶
Overview ¶
Package feeder is the konareef Pod-Trust-Domain sidecar orchestrator. It ties the individual feeder stages together: reading the relayed witness.json, assembling a PodRecord, calling the PS-1 prover via SpartanCompress, and posting the resulting artifact to reef-core via PostArtifact.
Package feeder is the konareef Pod-Trust-Domain sidecar: it reads the relayed step data, assembles the PS-1 PodRecord, calls the prover, and POSTs the artifact to reef-core. It is the witness-of-record; reef-core never assembles a PodRecord.
Package feeder is the konareef Pod-Trust-Domain sidecar: it reads the relayed step data, assembles the PS-1 PodRecord, calls the prover, and POSTs the artifact to reef-core. It is the witness-of-record; reef-core never assembles a PodRecord.
Package feeder — WitnessWriter (C1 Phase-C, spec §3).
WitnessWriter is the konareef sidecar's step, run before feeder.Run: it combines the reef-core-relayed step-disclosure.json (§2) with the installed, signed pod manifest's fields (never re-derived, never crossing the seam) to assemble a feeder.Witness, and writes it to witness.json for feeder.Run to consume unchanged.
WriteWitness populates Witness.ToolLog from the seam's tool_log (Step 2): each record's tool_id/args_hash/result_hash/ts_us maps into a ToolCallRecord with per-tool sats = 0 (reef-core discloses no per-tool sats; local tools like bash are free). An empty seam tool_log yields an empty (non-nil) ToolLog.
Index ¶
- func PostArtifact(ctx context.Context, ingestURL, token string, scr *SpartanCompressResult, ...) error
- func Run(ctx context.Context, o Opts) error
- func WriteWitness(seamPath string, mp ManifestParams, outPath string) error
- type ManifestParams
- type Opts
- type PodRecord
- type SeamToolRecord
- type SpartanCompressResult
- type StepDisclosure
- type ToolCallRecord
- type Witness
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PostArtifact ¶
func PostArtifact(ctx context.Context, ingestURL, token string, scr *SpartanCompressResult, w Witness) error
PostArtifact POSTs the spec-§2 ingest body to reef-core's internal seam.
func Run ¶
Run executes the full feeder pipeline for one step:
- Read and parse the witness JSON from o.WitnessPath.
- Assemble a PodRecord from the witness (AssemblePodRecord).
- POST the PodRecord to PS-1 to obtain a SpartanCompressResult (SpartanCompress).
- POST the artifact to reef-core ingest (PostArtifact).
Returns the first error encountered, wrapped with feeder-package context.
The four endpoint/credential fields are required (the doc invariant): an empty WitnessPath, PaygateURL, IngestURL, or IngestToken is rejected up front rather than surfacing as a confusing downstream I/O/HTTP error. CircuitID is allowed to be empty (PS-1 may default it server-side).
func WriteWitness ¶
func WriteWitness(seamPath string, mp ManifestParams, outPath string) error
WriteWitness reads step-disclosure.json from seamPath, combines it with mp (the installed manifest's fields), and writes the resulting feeder.Witness as witness.json to outPath (spec §3).
ToolLog is mapped from the seam's tool_log (empty when the pod made no recorded tool calls); each record carries sats = 0 (local tools are free).
WriteWitness fails early — before writing outPath — if AssemblePodRecord would reject the assembled Witness, so a malformed SigManifest or PkPub is caught at witness-write time rather than surfacing later in feeder.Run.
Types ¶
type ManifestParams ¶
type ManifestParams struct {
Manifest []byte
Models []string
Tools []string
CMax uint64
SigManifest []byte
PkPub []byte
}
ManifestParams carries the fields sourced from the installed, signed pod manifest (spec §3.2) rather than the step-disclosure seam. SigManifest and PkPub come from the published, pre-signed manifest — no signing-key custody at the sidecar.
type Opts ¶
type Opts struct {
// WitnessPath is the filesystem path to the witness.json file written
// by the relayer sidecar.
WitnessPath string
// PaygateURL is the base URL of the PS-1 prover (e.g. http://localhost:8080).
PaygateURL string
// IngestURL is the reef-core internal ingest endpoint URL.
IngestURL string
// IngestToken is the per-pod bearer token for the reef-core ingest seam.
IngestToken string
// CircuitID identifies the ZK circuit to use (e.g. konareef-pod-step-v1).
CircuitID string
}
Opts configures one feeder run inside the PTD workspace. All fields are required; the CLI validates them before calling Run.
type PodRecord ¶
type PodRecord struct {
Manifest []byte `json:"manifest"`
P []byte `json:"p"`
R []byte `json:"r"`
Index uint32 `json:"index"`
C uint64 `json:"c"`
CMax uint64 `json:"c_max"`
Model string `json:"model"`
Models []string `json:"models"`
Tools []string `json:"tools"`
ToolLog []ToolCallRecord `json:"tool_log"`
SigManifest []byte `json:"sig_manifest"`
PkPub []byte `json:"pk_pub"`
}
PodRecord mirrors paygate-zk crates/paygate-zk-prove/src/wire.rs, whose byte fields (manifest, p, r, sig_manifest, pk_pub) are declared as Rust `String` holding base64. Wire compatibility relies on Go encoding/json emitting a []byte field as a base64 string: callers MUST set these fields to raw, un-encoded bytes — never to a pre-encoded base64 string — or the JSON would double-encode and the Rust side would fail to decode.
func AssemblePodRecord ¶
AssemblePodRecord builds the fixed PS-1 wire contract from relayed data. sig_manifest/pk_pub come from the published, pre-signed manifest — no signing-key custody at the feeder.
It is the fail-closed producer gate: a malformed sig_manifest lane or a structurally invalid publisher pubkey is rejected HERE, before the witness is written / sent to PS-1, rather than surfacing as an opaque prover or verifier failure downstream.
type SeamToolRecord ¶
type SeamToolRecord struct {
ToolID string `json:"tool_id"`
ArgsHash []byte `json:"args_hash"`
ResultHash []byte `json:"result_hash"`
TsUs uint64 `json:"ts_us"`
}
SeamToolRecord is one tool record as disclosed by reef-core's step-disclosure.json `tool_log` (seam contract §2.2). args_hash/ result_hash are base64-encoded 32-byte SHA-256 digests (encoding/json decodes a base64 string into []byte); ts_us is microseconds since the Unix epoch. reef-core does not disclose per-tool sats (local tools like bash are free), so the witness carries sats = 0.
type SpartanCompressResult ¶
type SpartanCompressResult struct {
SpartanSnark []byte `json:"spartan_snark"`
FirstStepPublicInputs []byte `json:"first_step_public_inputs"`
LastStepPublicInputs []byte `json:"last_step_public_inputs"`
VkeyHash []byte `json:"vkey_hash"`
GenesisFieldsRoot []byte `json:"genesis_fields_root"`
// Z0 and Vkey are the raw genesis fold state (Z_ARITY=23 lanes × 32 = 736
// bytes) and the raw 32-byte verifier key (pp.digest() LE; vkey_hash =
// SHA-256(vkey)). PS-1 emits both on the ProveResponse (paygate-zk !54);
// reef-core ingest persists them for the complete konareef-bundle/v2
// artifact. The feeder forwards them byte-for-byte; it does not derive them.
Z0 []byte `json:"z0"`
Vkey []byte `json:"vkey"`
CircuitID string `json:"circuit_id"`
}
SpartanCompressResult is the PS-1 ProveResponse (paygate-zk wire.rs:55-63). All byte fields are base64-encoded strings in the wire format and decoded to []byte by the JSON unmarshaler.
func SpartanCompress ¶
func SpartanCompress(ctx context.Context, base, circuitID string, pr PodRecord) (*SpartanCompressResult, error)
SpartanCompress issues POST {base}/v1/prove/spartan-compress to the PS-1 prover, submitting a PodRecord and receiving a SpartanCompressResult. PS-1 is unauthenticated/local in the C1 first slice (paygate-zk http.rs); BRC-31 payment is a PaaS-hardening concern, not this slice.
On a 503 ERR_BUSY (PS-1 single-flight), the call is retried up to spartanMaxAttempts times with capped exponential backoff (honouring a Retry-After header when present); after the cap it returns the busy error. Any other non-200 (4xx/5xx) is an immediate terminal error. The passed ctx cancels both the in-flight request and the inter-attempt wait.
type StepDisclosure ¶
type StepDisclosure struct {
Index uint32 `json:"index"`
P []byte `json:"p"`
R []byte `json:"r"`
C uint64 `json:"c"`
Model string `json:"model"`
ToolLog []SeamToolRecord `json:"tool_log"`
}
StepDisclosure is the seam file reef-core writes and the sidecar reads (spec §2.1). Only fields not re-derivable from the published/installed pod manifest cross the seam. Byte fields are raw bytes — encoding/json base64-encodes []byte on the wire, matching the feeder's existing convention (see witness.go's PodRecord doc comment).
type ToolCallRecord ¶
type ToolCallRecord struct {
Tool string `json:"tool"`
InHash []byte `json:"in_hash"`
OutHash []byte `json:"out_hash"`
Ts uint64 `json:"ts"`
Sats uint64 `json:"sats"`
}
ToolCallRecord is one tool invocation in the disclosed T_log. The JSON shape matches paygate-zk's PS-1 wire ToolCallRecord (wire.rs): the tool NAME (PS-1 computes tool_id_digest = SHA-256(name) itself), the two base64 32-byte hashes, ts (u64 microseconds), and sats (0 for unpaid/local tools like bash; the circuit binds Σ sats ≤ c).
type Witness ¶
type Witness struct {
Manifest []byte `json:"manifest"`
P []byte `json:"p"`
R []byte `json:"r"`
Index uint32 `json:"index"`
C uint64 `json:"c"`
CMax uint64 `json:"c_max"`
Model string `json:"model"`
Models []string `json:"models"`
Tools []string `json:"tools"`
ToolLog []ToolCallRecord `json:"tool_log"`
SigManifest []byte `json:"sig_manifest"`
PkPub []byte `json:"pk_pub"`
}
Witness is the disclosed step data reef-core relays into the PTD workspace (spec §2/§4). For Type C every field is publicly re-derivable.
Source Files