Documentation
¶
Overview ¶
Package proofs implements pure-Go Filecoin proof verification.
Stage B of #87: WinningPoSt verify (remove filecoin-ffi dep #1). The crypto core is Groth16 verification over BLS12-381, using gnark-crypto's pairing engine. This same core is shared with the FVM's proof-verify syscalls (#130 Tier 2).
Hard safety line: one wrong field ordering or public-input layout = every proof fails or, worse, a bad proof passes. This MUST be vector-matched against filecoin-ffi reference vectors before wiring into block validation.
Index ¶
- Constants
- func BuildWinningPoStPublicInputs(info WinningPoStVerifyInfo) ([]*big.Int, error)
- func GenerateWinningPoStSectorChallenge(minerID abi.ActorID, randomness [32]byte, eligibleSectorCount uint64) ([]uint64, error)
- func Groth16Verify(vk *Groth16VerifyingKey, proof *Groth16Proof, publicInputs []*big.Int) error
- func ParseG1Uncompressed(data []byte) (bls12381.G1Affine, error)
- func ParseG2Uncompressed(data []byte) (bls12381.G2Affine, error)
- func SealedCIDToCommR(mhDigest []byte) ([32]byte, error)
- func VerifyWinningPoSt(vk *Groth16VerifyingKey, info WinningPoStVerifyInfo) error
- func VerifyWinningPoStByType(cacheDir string, pt RegisteredPoStProof, randomness [32]byte, proof []byte, ...) error
- func WinningPoStParams(pt RegisteredPoStProof) (winningPoStParams, error)
- type APIVersion
- type Groth16Proof
- type Groth16VerifyingKey
- type RegisteredPoStProof
- type WinningPoStSector
- type WinningPoStVerifyInfo
Constants ¶
const WinningPoStSectorCount = 1
WinningPoStSectorCount is the number of distinct sector indices returned by GenerateWinningPoStSectorChallenge for a WinningPoSt. (rust-fil-proofs: WINNING_POST_SECTOR_COUNT = 1)
Variables ¶
This section is empty.
Functions ¶
func BuildWinningPoStPublicInputs ¶
func BuildWinningPoStPublicInputs(info WinningPoStVerifyInfo) ([]*big.Int, error)
BuildWinningPoStPublicInputs assembles the Groth16 public-input vector for a WinningPoSt, exactly as rust-fil-proofs generate_public_inputs.
param_sector_count = challenge_count / sector_count (= 66 for winning), and the single challenged sector is replicated that many times, each virtual copy i getting leaf challenge for sector_index = i.
func GenerateWinningPoStSectorChallenge ¶
func GenerateWinningPoStSectorChallenge( minerID abi.ActorID, randomness [32]byte, eligibleSectorCount uint64, ) ([]uint64, error)
GenerateWinningPoStSectorChallenge selects the indices, into a miner's eligible-sector set, whose sectors must be challenged for a WinningPoSt at the given randomness. Byte-for-byte compatible with filecoin-ffi's GenerateWinningPoStSectorChallenge (Go binding calls into rust-fil-proofs; this function has no ffi/cgo dependency).
The returned slice has length WinningPoStSectorCount (=1). Any caller that wants byte-for-byte parity with filecoin-ffi must feed this output back into the miner's eligible-sector list (typically ordered by SectorNumber ascending) to resolve the concrete sector.
func Groth16Verify ¶
func Groth16Verify(vk *Groth16VerifyingKey, proof *Groth16Proof, publicInputs []*big.Int) error
Groth16Verify checks a Groth16 proof against a verifying key and public inputs. Returns nil on success, an error on failure.
The verification equation is the pairing check:
e(A, B) == e(AlphaG1, BetaG2) · e(L, GammaG2) · e(C, DeltaG2)
where L = IC[0] + ∑(IC[i+1] * input[i]).
Rearranged as PairingCheck (product == 1):
e(-A, B) · e(AlphaG1, BetaG2) · e(L, GammaG2) · e(C, DeltaG2) == 1
func ParseG1Uncompressed ¶
ParseG1Uncompressed reads a bellperson-serialized G1 point (96 bytes, big-endian X || Y, uncompressed, with the infinity flag in the top bit of the first byte). Returns the point and the number of bytes consumed.
func ParseG2Uncompressed ¶
ParseG2Uncompressed reads a bellperson-serialized G2 point (192 bytes).
func SealedCIDToCommR ¶
SealedCIDToCommR extracts the 32-byte little-endian comm_r field element from a sealed sector CID's multihash digest.
func VerifyWinningPoSt ¶
func VerifyWinningPoSt(vk *Groth16VerifyingKey, info WinningPoStVerifyInfo) error
VerifyWinningPoSt verifies a WinningPoSt proof in pure Go against the given verifying key. Returns nil on success.
func VerifyWinningPoStByType ¶
func VerifyWinningPoStByType(cacheDir string, pt RegisteredPoStProof, randomness [32]byte, proof []byte, sectors []WinningPoStSector) error
VerifyWinningPoStByType is the high-level entry point closest to filecoin-ffi's VerifyWinningPoSt: given the proof type, the param cache dir, and the challenged sector(s), it loads the VK and verifies.
func WinningPoStParams ¶
func WinningPoStParams(pt RegisteredPoStProof) (winningPoStParams, error)
WinningPoStParams returns the circuit parameters for a proof type.
Types ¶
type APIVersion ¶
type APIVersion int
APIVersion selects the challenge-index derivation rule, matching storage_proofs_core::api_version::ApiVersion.
const ( APIVersion1_0_0 APIVersion = iota APIVersion1_1_0 APIVersion1_2_0 )
type Groth16Proof ¶
Groth16Proof holds a parsed BLS12-381 Groth16 proof.
a: G1Affine b: G2Affine c: G1Affine
func ParseGroth16Proof ¶
func ParseGroth16Proof(data []byte) (*Groth16Proof, error)
ParseGroth16Proof parses a bellperson Groth16 proof (A: G1, B: G2, C: G1). Accepts both the compressed encoding (48+96+48 = 192 bytes, which is what Filecoin block-header / PoSt proofs use) and the uncompressed encoding (96+192+96 = 384 bytes). gnark's SetBytes auto-detects compression from the flag bits, but we slice by the fixed field widths per encoding.
type Groth16VerifyingKey ¶
type Groth16VerifyingKey struct {
AlphaG1 bls12381.G1Affine
BetaG1 bls12381.G1Affine // present in VK but not used for verify
BetaG2 bls12381.G2Affine
GammaG2 bls12381.G2Affine
DeltaG1 bls12381.G1Affine // present in VK but not used for verify
DeltaG2 bls12381.G2Affine
IC []bls12381.G1Affine
}
Groth16VerifyingKey holds a parsed BLS12-381 Groth16 verifying key in the format Filecoin uses (bellperson-compatible).
Layout mirrors bellperson::groth16::VerifyingKey<Bls12>:
alpha_g1: G1Affine beta_g1: G1Affine (not used in verification, but present in the serialized VK) beta_g2: G2Affine gamma_g2: G2Affine delta_g1: G1Affine (not used in verification) delta_g2: G2Affine ic: []G1Affine (public-input commitment bases; len = #public_inputs + 1)
func LoadWinningPoStVK ¶
func LoadWinningPoStVK(cacheDir string, pt RegisteredPoStProof) (*Groth16VerifyingKey, error)
LoadWinningPoStVK loads the verifying key for a WinningPoSt proof type from the given Filecoin parameter cache directory (the same directory filecoin-ffi uses, e.g. $FIL_PROOFS_PARAMETER_CACHE).
func ParseGroth16VerifyingKey ¶
func ParseGroth16VerifyingKey(r io.Reader) (*Groth16VerifyingKey, error)
ParseGroth16VerifyingKey reads a bellperson verifying key from a reader. Format: AlphaG1(96) + BetaG1(96) + BetaG2(192) + GammaG2(192) + DeltaG1(96) + DeltaG2(192) + u32le(ic_count) + IC[0..ic_count](96 each).
type RegisteredPoStProof ¶
type RegisteredPoStProof int64
RegisteredPoStProof mirrors abi.RegisteredPoStProof for the WinningPoSt variants (the only ones this package verifies).
const ( StackedDrgWinning2KiBV1 RegisteredPoStProof = 0 StackedDrgWinning8MiBV1 RegisteredPoStProof = 1 StackedDrgWinning512MiBV1 RegisteredPoStProof = 2 StackedDrgWinning32GiBV1 RegisteredPoStProof = 3 StackedDrgWinning64GiBV1 RegisteredPoStProof = 4 )
type WinningPoStSector ¶
type WinningPoStSector struct {
SectorNumber uint64
// CommR is the 32-byte sealed-sector commitment in LITTLE-endian
// field-element representation (as stored in the sealed CID digest).
CommR [32]byte
}
WinningPoStSector is one challenged sector's public data.
type WinningPoStVerifyInfo ¶
type WinningPoStVerifyInfo struct {
Randomness [32]byte
Proof []byte // the Groth16 proof bytes (compressed, 192B)
Sectors []WinningPoStSector
SectorSize uint64
APIVersion APIVersion
}
WinningPoStVerifyInfo is the pure-Go equivalent of proof.WinningPoStVerifyInfo (the inputs to VerifyWinningPoSt).
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package winningpost is the Stage B scaffold for a pure-Go WinningPoSt verifier.
|
Package winningpost is the Stage B scaffold for a pure-Go WinningPoSt verifier. |