chain

Documentation

Overview

Package chain defines chain identifiers, contract addresses, and epoch utilities for supported Filecoin networks (Mainnet and Calibration).

This is a leaf package with no dependencies on other synapse-go packages. All chain-specific constants (chain IDs, contract addresses, genesis timestamps) are defined here to keep them in a single source of truth.

Stability

0.x phase: public API may change between minor releases. Contract addresses track the canonical FOC deployments and may be updated when upstream contracts redeploy.

Index

• Constants
• Variables
• func CurrentEpoch(c Chain) *big.Int
• func EpochToTime(c Chain, epoch *big.Int) time.Time
• func TimeToEpoch(c Chain, t time.Time) *big.Int
• type Chain
  • func FromID(id int64) (Chain, error)
  • func (c Chain) Addresses() ContractAddresses
  • func (c Chain) BigChainID() *big.Int
  • func (c Chain) ChainID() int64
  • func (c Chain) DefaultRPCURL() string
  • func (c Chain) GenesisTimestamp() int64
  • func (c Chain) String() string
• type ContractAddresses

Constants

const (
	// EpochDuration is the time between Filecoin epochs.
	EpochDuration = 30 * time.Second

	// EpochDurationSeconds is the epoch duration in seconds.
	EpochDurationSeconds int64 = int64(EpochDuration / time.Second)

	// EpochsPerDay is the number of epochs in a 24-hour day.
	EpochsPerDay int64 = int64((24 * time.Hour) / EpochDuration)

	// EpochsPerMonth is the approximate number of epochs in a 30-day month.
	EpochsPerMonth int64 = 30 * EpochsPerDay
)

const (
	KiB = 1024
	MiB = 1 << 20
	GiB = 1 << 30
	TiB = 1 << 40
	PiB = 1 << 50
)

Binary size constants.

const (
	// MaxUploadSize is the maximum data size for a single upload,
	// accounting for fr32 padding (127 usable bytes per 128 bytes).
	MaxUploadSize = GiB * 127 / 128

	// MinUploadSize is the minimum data size for a single upload.
	MinUploadSize = 127

	// BytesPerLeaf is the number of bytes per leaf in a Merkle tree.
	BytesPerLeaf = 32
)

Upload size limits and leaf geometry.

const (
	// FILDecimals is the number of decimal places for native FIL (attoFIL = 1e-18 FIL).
	FILDecimals = 18
	// USDFCDecimals is the number of decimal places for USDFC on Filecoin.
	// Note: unlike USDC on Ethereum (6 decimals), USDFC uses 18 decimals.
	USDFCDecimals = 18
)

Token decimal constants. Both FIL and USDFC use 18 decimal places on Filecoin.

Variables

var ErrUnknownChain = errors.New("chain: unknown chain")

ErrUnknownChain is returned when an unrecognized chain or chain ID is used.

Functions

func CurrentEpoch

func CurrentEpoch(c Chain) *big.Int

CurrentEpoch returns the current Filecoin epoch for the given chain. Returns zero for chains without a known genesis timestamp.

func EpochToTime

func EpochToTime(c Chain, epoch *big.Int) time.Time

EpochToTime converts a Filecoin epoch number to a wall-clock time. Returns the zero time for chains without a known genesis, if epoch is nil, or if the resulting Unix timestamp does not fit in int64.

func TimeToEpoch

func TimeToEpoch(c Chain, t time.Time) *big.Int

TimeToEpoch converts a wall-clock time to a Filecoin epoch number. Returns zero for chains without a known genesis.

Types

type Chain

type Chain uint8

Chain identifies a Filecoin network.

const (
	// Mainnet is the Filecoin production network (chain ID 314).
	Mainnet Chain = iota
	// Calibration is the Filecoin test network (chain ID 314159).
	Calibration
)

func FromID

func FromID(id int64) (Chain, error)

FromID returns the Chain for the given EIP-155 chain ID.

func (Chain) Addresses

func (c Chain) Addresses() ContractAddresses

Addresses returns the well-known contract addresses for this chain. Returns a zero-value struct for chains without known addresses.

func (Chain) BigChainID

func (c Chain) BigChainID() *big.Int

BigChainID returns the chain ID as a *big.Int, convenient for go-ethereum calls.

func (Chain) ChainID

func (c Chain) ChainID() int64

ChainID returns the EIP-155 chain ID for this chain.

func (Chain) DefaultRPCURL

func (c Chain) DefaultRPCURL() string

DefaultRPCURL returns the default public RPC endpoint for this chain. Returns an empty string for chains without a known RPC URL.

func (Chain) GenesisTimestamp

func (c Chain) GenesisTimestamp() int64

GenesisTimestamp returns the genesis Unix timestamp for this chain. Returns 0 for chains without a known genesis.

func (Chain) String

func (c Chain) String() string

String returns the human-readable network name.

type ContractAddresses

type ContractAddresses struct {
	FWSS               common.Address // Filecoin Warm Storage Service (root of trust)
	Payments           common.Address
	StateView          common.Address // warm storage state view
	PDPVerifier        common.Address
	SPRegistry         common.Address
	USDFC              common.Address
	Multicall3         common.Address
	SessionKeyRegistry common.Address
}

ContractAddresses holds the well-known contract addresses for a chain.