Documentation
¶
Overview ¶
Package sources provides Source implementations for the chain/bootstrap quorum:
- ForestSource: any Lotus-compatible JSON-RPC endpoint (e.g. forest-archive.chainsafe.dev). Calls Filecoin.F3GetLatestCertificate.
- GatewaySource: the Lantern project's HTTPS gateway. Same wire protocol as ForestSource but tagged KindLanternGateway so quorum policy can exclude it by default.
- UserPeerSource: a user-supplied --peer URL. Uses the same Lotus-compatible JSON-RPC protocol.
- Libp2pSource: a single libp2p peer queried via the F3 cert-exchange protocol (/f3/certexch/get/1/<nn>).
- LanternBeaconSource: a DHT-discovered Lantern beacon. Lantern beacons today serve Bitswap but do not yet implement cert-exchange; this source is a stub that returns ErrNoBeaconBackend so quorum probes don't panic on it. When V1.2.1 ships beacon cert-exchange, this becomes the real implementation.
Source implementations live here instead of next to bootstrap.go to keep the bootstrap driver dependency-free (no libp2p, no HTTP) so it can be tested with mocks.
Index ¶
- Variables
- func BuildDefaultSources(cfg SourceSetConfig) []bootstrap.Source
- func NewForestSource(name, url, token string, timeout time.Duration) bootstrap.Source
- func NewLanternBeaconSource(h host.Host, info peer.AddrInfo, network gpbft.NetworkName, ...) bootstrap.Source
- func NewLanternGatewaySource(name, url string, timeout time.Duration) bootstrap.Source
- func NewLibp2pSource(h host.Host, p peer.ID, network gpbft.NetworkName, timeout time.Duration) bootstrap.Source
- func NewUserPeerSource(name, url, token string, timeout time.Duration) bootstrap.Source
- func WaitForLibp2pPeers(ctx context.Context, h host.Host, minPeers int, interval time.Duration)
- type LanternBeaconSource
- type Libp2pSource
- type SourceSetConfig
Constants ¶
This section is empty.
Variables ¶
var CalibnetPublicForestURLs = []string{
"https://api.calibration.node.glif.io/rpc/v1",
}
CalibnetPublicForestURLs is the calibration subset of the public JSON-RPC endpoints. Use this when bootstrapping a calibration node.
Calibration has fewer publicly-curated archive endpoints than mainnet. The quorum config for calibration drops to 3-of-N as a result; operators wanting stricter quorum should add --peer URLs.
var DefaultLanternBeacons = []string{}
DefaultLanternBeacons is the curated set of known-good Lantern beacons that run cert-exchange (V1.2.1, B-11-01). Quorum probes dial these over libp2p and count them as independent KindLanternBeacon sources.
These are independent operators — not the Lantern project. The gateway is at gateway.lantern.reiers.io and is run by the project; the beacons in this list are operated separately and count toward the trust quorum by default. New beacons are added here as operators volunteer them. Intentionally empty. Operators add Lantern beacons via the --lantern-beacon multiaddr flag (or via SourceSetConfig.LanternBeacons when embedding the library). Shipping a curated list of named beacons here would (a) leak operational topology of whoever runs the beacons, (b) put the project in a curator role we don't want, and (c) go stale every time a beacon rotates its libp2p peer ID. A future release may publish a community-maintained list at a separate URL.
var DefaultPublicForestURLs = []string{
"https://api.node.glif.io/rpc/v1",
"https://api.calibration.node.glif.io/rpc/v1",
}
DefaultPublicForestURLs is the curated set of public Filecoin JSON-RPC endpoints we know publish F3 finality certs. The bootstrap quorum draws from this list when the user does not supply their own --peer.
These are independent operators; the list is intentionally short to keep the quorum cheap on cold start.
var ErrNoBeaconBackend = errors.New("lantern beacon: source not configured with libp2p host")
ErrNoBeaconBackend is retained for backwards compatibility with V1.2.0 callers that constructed a LanternBeaconSource without a host. In V1.2.1 (B-11-01) Lantern beacons serve cert-exchange over libp2p, so a properly constructed LanternBeaconSource via NewLanternBeaconSource returns real results; only the zero-value source emits this error.
var MainnetPublicForestURLs = []string{
"https://api.node.glif.io/rpc/v1",
"https://api.chain.love/rpc/v1",
}
MainnetPublicForestURLs is the mainnet-only subset of the public JSON-RPC endpoints. Use this when bootstrapping a mainnet node.
Curated to be operationally independent: Glif (Protocol Labs infra), chain.love (Protocol Labs community), and any user-added --peer URLs add to this base set. The quorum tally treats each as one vote regardless of operator, so users who want stronger independence guarantees should add their own --peer flags.
Functions ¶
func BuildDefaultSources ¶
func BuildDefaultSources(cfg SourceSetConfig) []bootstrap.Source
BuildDefaultSources returns the default source set for a quorum probe. The returned list is suitable for direct use with Quorum(). Order: libp2p (preferred for true independence) → public Forest archives → user peers → DHT-discovered Lantern beacons → Lantern gateway.
func NewForestSource ¶
NewForestSource constructs a Source that calls Filecoin.F3GetLatestCertificate on a Forest/Lotus-compatible HTTP RPC endpoint. Empty token is fine for public archives.
func NewLanternBeaconSource ¶
func NewLanternBeaconSource(h host.Host, info peer.AddrInfo, network gpbft.NetworkName, timeout time.Duration) bootstrap.Source
NewLanternBeaconSource returns a Source that asks a Lantern beacon for its latest F3 finality over cert-exchange.
The beacon's full peer.AddrInfo is required so the source can dial even when the host hasn't already met the beacon via DHT. Pass the libp2p host that should perform the dial; nil host returns a source that always fails with ErrNoBeaconBackend (preserved for callers that still construct a placeholder).
func NewLanternGatewaySource ¶
NewLanternGatewaySource constructs a Source for the Lantern project's own gateway. Same wire as ForestSource but tagged so quorum policy excludes it from the count by default.
func NewLibp2pSource ¶
func NewLibp2pSource(h host.Host, p peer.ID, network gpbft.NetworkName, timeout time.Duration) bootstrap.Source
NewLibp2pSource returns a Source for a single libp2p peer.
func NewUserPeerSource ¶
NewUserPeerSource constructs a Source for a user-supplied --peer URL. These count toward the quorum because the user has explicitly opted in by listing them on the command line.
func WaitForLibp2pPeers ¶
WaitForLibp2pPeers blocks until at least minPeers libp2p connections are established or ctx is done. Useful as a precondition to running the quorum so cert-exchange has open streams to query.
Types ¶
type LanternBeaconSource ¶
type LanternBeaconSource struct {
// contains filtered or unexported fields
}
LanternBeaconSource queries a Lantern beacon over the F3 cert-exchange protocol. As of V1.2.1 (B-11-01) beacons run a responder backed by their own verified-cert store, so this is a first-class quorum source.
KindLanternBeacon counts toward the quorum by default. These are independent operators — not the project itself — so the trust model treats them like any other libp2p source. (Contrast with KindLanternGateway which is opt-in via --count-gateway because the project itself runs the gateway.)
func (*LanternBeaconSource) Kind ¶
func (s *LanternBeaconSource) Kind() bootstrap.Kind
func (*LanternBeaconSource) LatestFinality ¶
func (*LanternBeaconSource) Name ¶
func (s *LanternBeaconSource) Name() string
type Libp2pSource ¶
type Libp2pSource struct {
// contains filtered or unexported fields
}
Libp2pSource queries a single libp2p peer via the F3 cert-exchange protocol (/f3/certexch/get/1/<networkName>). Use one per peer; the quorum driver fans out across all libp2p sources in parallel.
func (*Libp2pSource) Kind ¶
func (s *Libp2pSource) Kind() bootstrap.Kind
func (*Libp2pSource) LatestFinality ¶
func (*Libp2pSource) Name ¶
func (s *Libp2pSource) Name() string
type SourceSetConfig ¶
type SourceSetConfig struct {
// Host is the libp2p host used for the cert-exchange protocol. If
// nil, no libp2p sources are added.
Host host.Host
// MainnetBootstrapPeers is the multiaddr list to query via
// cert-exchange (typically build.MainnetBootstrapPeers). Each
// successful dial becomes a Libp2pSource.
MainnetBootstrapPeers []string
// MaxLibp2pPeers caps the number of libp2p sources added. Default 8.
MaxLibp2pPeers int
// PublicForestURLs is the list of public JSON-RPC archive URLs. If
// empty, defaults to MainnetPublicForestURLs.
PublicForestURLs []string
// LanternGatewayURL is the Lantern project's gateway URL. Empty
// disables the gateway source. The gateway source is only added
// when IncludeGatewayProbe is true; otherwise it is elided from
// the probe entirely (the gateway is served as a cold-block +
// state-root fallback at runtime, but it is not a Filecoin
// JSON-RPC endpoint and cannot answer F3GetLatestCertificate,
// which would otherwise print a confusing red ✗ during install).
LanternGatewayURL string
// IncludeGatewayProbe adds the Lantern gateway to the probe source
// list. Off by default; operators who set --count-gateway (or
// otherwise want the gateway represented in the tally) turn this
// on. Requires a gateway URL.
IncludeGatewayProbe bool
// UserPeerURLs is the list of user-supplied --peer URLs.
UserPeerURLs []string
// LanternBeacons is the multiaddr list of known Lantern beacons that
// speak cert-exchange. If nil, DefaultLanternBeacons is used. Set to
// a non-nil empty slice to disable.
LanternBeacons []string
// NetworkName is the F3 manifest network name (e.g. "filecoin").
NetworkName gpbft.NetworkName
// SourceTimeout is the per-source RPC/protocol deadline. Default 20s.
SourceTimeout time.Duration
}
SourceSetConfig configures the default source-set builder.