Documentation
¶
Overview ¶
Package beacon verifies DRAND beacon entries referenced from Filecoin block headers. Filecoin uses a chained-DRAND setup: blocks reference one or more beacon entries from the configured drand networks (mainnet uses the original league-of-entropy chain plus the newer quicknet chain after a coordinated upgrade).
Lantern's verifier is pure Go: it uses github.com/drand/drand/v2/crypto and github.com/drand/kyber-bls12381 for BLS verification on the drand chain.
The verifier is intentionally narrow: it answers "does this BeaconEntry sit in the configured DRAND chain at the declared round, and is its signature valid?" Higher-level rules (e.g. "block at epoch E references the correct drand round given the network schedule") live in chain/header.
Index ¶
- func BeaconDigest(entry ltypes.BeaconEntry) [32]byte
- func DrawBeaconRandomness(entry ltypes.BeaconEntry, pers gscrypto.DomainSeparationTag, ...) ([]byte, error)
- func DrawChainRandomness(ts *ltypes.TipSet, pers gscrypto.DomainSeparationTag, round abi.ChainEpoch, ...) ([]byte, error)
- func DrawRandomnessFromBase(rbase []byte, pers gscrypto.DomainSeparationTag, round abi.ChainEpoch, ...) ([]byte, error)
- func DrawRandomnessFromDigest(digest [32]byte, pers gscrypto.DomainSeparationTag, round abi.ChainEpoch, ...) ([]byte, error)
- func TicketDigest(ts *ltypes.TipSet) ([32]byte, error)
- type Config
- type QuicknetParams
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BeaconDigest ¶
func BeaconDigest(entry ltypes.BeaconEntry) [32]byte
BeaconDigest returns blake2b-256 of the beacon entry's Data bytes.
func DrawBeaconRandomness ¶
func DrawBeaconRandomness(entry ltypes.BeaconEntry, pers gscrypto.DomainSeparationTag, round abi.ChainEpoch, entropy []byte) ([]byte, error)
DrawBeaconRandomness composes BeaconDigest + DrawRandomnessFromDigest.
func DrawChainRandomness ¶
func DrawChainRandomness(ts *ltypes.TipSet, pers gscrypto.DomainSeparationTag, round abi.ChainEpoch, entropy []byte) ([]byte, error)
DrawChainRandomness composes TicketDigest + DrawRandomnessFromDigest.
func DrawRandomnessFromBase ¶
func DrawRandomnessFromBase(rbase []byte, pers gscrypto.DomainSeparationTag, round abi.ChainEpoch, entropy []byte) ([]byte, error)
DrawRandomnessFromBase produces randomness from a "base" byte slice by hashing the base with blake2b-256 first. Matches Lotus rand.go.
func DrawRandomnessFromDigest ¶
func DrawRandomnessFromDigest(digest [32]byte, pers gscrypto.DomainSeparationTag, round abi.ChainEpoch, entropy []byte) ([]byte, error)
DrawRandomnessFromDigest mirrors lotus/chain/rand.go's same-named function. Matches byte-for-byte.
Types ¶
type Config ¶
type Config struct {
// PublicKey is the DRAND group public key.
PublicKey kyber.Point
// Scheme is the DRAND signature scheme.
Scheme *dcrypto.Scheme
// IsChained reports whether beacons in this network chain to their
// predecessor (pre-quicknet) or stand alone (post-quicknet, FIP-0063).
IsChained bool
// Hash is the network chain hash, for diagnostics.
Hash []byte
}
Config is the trust anchor for a single DRAND chain: the chain hash, the signature scheme ID (e.g. "pedersen-bls-chained" or "bls-unchained-g1-rfc9380"), the group public key, and timing parameters.
func LoadConfigFromChainInfoJSON ¶
LoadConfigFromChainInfoJSON parses a drand chain-info JSON blob and an "is chained" flag, producing a verifier configuration. The JSON shape is the one Lotus stores in build/buildconstants.DrandConfigs[<network>].ChainInfoJSON.
If schemeID is absent (older Lotus mainnet chain info), we default to "pedersen-bls-chained", the original league-of-entropy mainnet scheme.
func (*Config) EqualHash ¶
EqualHash returns true iff the provided chain hash matches this config. Useful as a sanity check when wiring multiple Configs into a schedule.
func (*Config) VerifyEntries ¶
func (c *Config) VerifyEntries(entries []ltypes.BeaconEntry, prevSig []byte) error
VerifyEntries verifies a sequence of beacon entries. prevSig is the signature data at the round preceding the first entry (typically the last beacon of the parent block); pass nil for unchained schemes.
The function does NOT enforce contiguous rounds: that's a header-level concern. It only verifies signatures and (for chained schemes) the previous-signature linkage between successive entries.
func (*Config) VerifyEntry ¶
func (c *Config) VerifyEntry(entry ltypes.BeaconEntry, prevSig []byte) error
VerifyEntry verifies a single beacon entry against the configured chain. For chained schemes, prevSig must be the signature data of the round preceding entry.Round. For unchained schemes (e.g. quicknet), prevSig is ignored (and may be nil).
type QuicknetParams ¶
type QuicknetParams struct {
DrandGenesisTime int64 // 1692803367
DrandPeriodSecs int64 // 3
// FilecoinGenesisTime is the unix timestamp of Filecoin block 0.
// Source: mainnet build params (1598306400 for mainnet).
FilecoinGenesisTime int64
// BlockDelaySecs is the Filecoin block delay (30s for mainnet).
BlockDelaySecs int64
}
QuicknetParams are the mainnet drand-quicknet timing parameters used to map a Filecoin epoch to a drand round. Source: build/buildconstants drand.go (chain hash 52db9ba7...quicknet).
func CalibnetQuicknetParams ¶
func CalibnetQuicknetParams() QuicknetParams
CalibnetQuicknetParams returns the parameters for Filecoin calibration using drand-quicknet. Drand chain is identical to mainnet quicknet (hash 52db9ba7...); calibration only differs in FilecoinGenesisTime (2026-11-01 15:33:00 UTC). Lotus keeps this in build/buildconstants/params_calibnet.go; we mirror it directly so a misconfigured import doesn't silently produce wrong beacon rounds.
Verified against a live calibration tipset (2026-07-15): fil-epoch 3893385 -> drand round 30441512 with FilecoinGenesisTime=1667326380, which is the value observed on-chain via lotus StateGetBeaconEntry.
func MainnetQuicknetParams ¶
func MainnetQuicknetParams() QuicknetParams
MainnetQuicknetParams returns the parameters for Filecoin mainnet using drand-quicknet. Values match Lotus build/buildconstants/* @ commit a0ecb8687f1c60d5e66040b6de364dbc9cc4d253.
func (QuicknetParams) MaxBeaconRoundForEpoch ¶
func (p QuicknetParams) MaxBeaconRoundForEpoch(filecoinEpoch abi.ChainEpoch) uint64
MaxBeaconRoundForEpoch returns the highest drand round whose seal time happens no later than the start of the given Filecoin epoch.
Lotus implementation (chain/beacon/drand/drand.go @ master 2026-05):
latestTs := (uint64(filEpoch) * filRoundTime) + filGenTime - filRoundTime
maxBeaconRoundV2 (nv >= 16 / current mainnet):
if latestTs < drandGenTime { return 1 }
return (latestTs - drandGenTime) / period + 1
We match maxBeaconRoundV2 byte-for-byte; mainnet has been past nv16 for years, so we don't bother with the V1 branch.
Source Files