ipc-actors.md

Ipc Actors

The IPC actors are implemented using the Diamond pattern. The Diamond pattern is defined by EIP 2535 and the reference implementation of the Diamond library that IPC imports is here. The mechanics of the diamond pattern that is used by IPC is such that for each actor there is a diamond with storage, constructor params, constructor, and a list of facet addresses and function signatures. Facets contain functions that can be called as part of the diamond.

Table of Contents

• Ipc Actors
• Gateway
  • Gateway Diamond
    • ConstructorParams
    • GatewayActorStorage
    • Gateway Diamond Facets
    • GatewayGetterFacet
      • Function Descriptions
    • GatewayManagerFacet
      • Function Descriptions
    • GatewayMessengerFacet
      • Function Descriptions
    • CheckpointingFacet
      • Function Descriptions
    • TopDownFinalityFacet
      • Function Descriptions
    • XnetMessagingFacet
      • Function Descriptions
• Subnet Registry
  • Subnet Registry Diamond
    • ConstructorParams
    • Subnet Registry Storage
    • Subnet Registry Diamond Facets
    • RegisterSubnetFacet
      • Function Descriptions
    • SubnetGetterFacet
      • Function Descriptions
• Subnet Actor
  • Subnet Actor Diamond
    • ConstructorParams
    • SubnetActorStorage
    • Subnet Actor Diamond Facets
    • SubnetActorCheckpointingFacet
      • Function Descriptions
    • SubnetActorGetterFacet
      • Function Descriptions
    • SubnetActorManagerFacet
      • Function Descriptions
    • SubnetActorPauseFacet
      • Function Descriptions
    • SubnetActorRewardFacet
      • Function Descriptions

Gateway

Gateway Diamond

ConstructorParams

struct ConstructorParams {
  uint256 bottomUpCheckPeriod;
  uint16 activeValidatorsLimit;
  uint8 majorityPercentage;
  struct SubnetID networkName;
  struct Validator[] genesisValidators;
  bytes32 commitSha;
}

GatewayActorStorage

struct GatewayActorStorage {
  uint256 latestParentHeight;
  uint256 bottomUpCheckPeriod;
  uint256 bottomUpMsgBatchPeriod;
  uint64 bottomUpNonce;
  uint64 appliedTopDownNonce;
  uint64 totalSubnets;
  uint64 maxMsgsPerBottomUpBatch;
  uint8 majorityPercentage;
  bytes32 commitSha;
  uint8 maxTreeDepth;
  bool generalPurposeCrossMsg;
  bool multiLevelCrossMsg;
  struct Membership currentMembership;
  struct Membership lastMembership;
  struct QuorumMap checkpointQuorumMap;
  struct SubnetID networkName;
  struct ParentValidatorsTracker validatorsTracker;
  mapping(bytes32 => struct Subnet) subnets;
  mapping(uint256 => struct ParentFinality) finalitiesMap;
  mapping(bytes32 => struct IpcEnvelope) postbox;
  mapping(uint256 => struct BottomUpCheckpoint) bottomUpCheckpoints;
  mapping(uint256 => struct BottomUpMsgBatch) bottomUpMsgBatches;
  struct EnumerableSet.Bytes32Set subnetKeys;
}

Gateway Diamond Facets

GatewayGetterFacet

getCommitSha

function getCommitSha() external view returns (bytes32)

Returns code commit SHA where this contract is from.

bottomUpNonce

function bottomUpNonce() external view returns (uint64)

Returns the current nonce for bottom-up message processing.

totalSubnets

function totalSubnets() external view returns (uint64)

Returns the total number of the registered subnets.

maxMsgsPerBottomUpBatch

function maxMsgsPerBottomUpBatch() external view returns (uint64)

Returns the maximum number of messages per bottom-up batch.

bottomUpCheckPeriod

function bottomUpCheckPeriod() external view returns (uint256)

Returns the period for bottom-up checkpointing.

getNetworkName

function getNetworkName() external view returns (struct SubnetID)

Returns the subnet identifier of the network.

bottomUpCheckpoint

function bottomUpCheckpoint(uint256 e) external view returns (struct BottomUpCheckpoint)

Returns a specific bottom-up checkpoint based on an epoch number.

Parameters

Name	Type	Description
e	uint256	The epoch number of the checkpoint.

bottomUpMsgBatch

function bottomUpMsgBatch(uint256 e) external view returns (struct BottomUpMsgBatch)

Returns a specific bottom-up message batch based on an index.

Parameters

Name	Type	Description
e	uint256	The epoch number of the batch.

getParentFinality

function getParentFinality(uint256 blockNumber) external view returns (struct ParentFinality)

Returns the parent chain finality information for a given block number.

Parameters

Name	Type	Description
blockNumber	uint256	The block number for which to retrieve parent-finality information.

getLatestParentFinality

function getLatestParentFinality() external view returns (struct ParentFinality)

Gets the most recent parent-finality information from the parent.

getSubnet

function getSubnet(struct SubnetID subnetId) external view returns (bool, struct Subnet)

Returns the subnet with the given id.

Parameters

Name	Type	Description
subnetId	struct SubnetID	the id of the subnet.

Return Values

Name	Type	Description
[0]	bool	found whether the subnet exists.
[1]	struct Subnet	subnet - the subnet struct.

subnets

function subnets(bytes32 h) external view returns (struct Subnet subnet)

Returns information about a specific subnet using its hash identifier.

Parameters

Name	Type	Description
h	bytes32	The hash identifier of the subnet to be queried.

Return Values

Name	Type	Description
subnet	struct Subnet	The subnet information corresponding to the given hash.

getSubnetTopDownMsgsLength

function getSubnetTopDownMsgsLength(struct SubnetID subnetId) external view returns (uint256)

Returns the length of the top-down message queue for a specified subnet.

Parameters

Name	Type	Description
subnetId	struct SubnetID	The identifier of the subnet for which the message queue length is queried.

Return Values

Name	Type	Description
[0]	uint256	The current length of the top-down message queue, indicated by the subnet's top-down nonce.

getTopDownNonce

function getTopDownNonce(struct SubnetID subnetId) external view returns (bool, uint64)

Returns the current applied top-down nonce for a specified subnet, indicating whether it's registered.

Parameters

Name	Type	Description
subnetId	struct SubnetID	The identifier of the subnet for which the top-down nonce is queried.

Return Values

Name	Type	Description
[0]	bool	A tuple containing a boolean indicating if the subnet is registered and the current top-down nonce.
[1]	uint64

getAppliedBottomUpNonce

function getAppliedBottomUpNonce(struct SubnetID subnetId) external view returns (bool, uint64)

Returns the current applied bottom-up nonce for a specified subnet, indicating whether it's registered.

Parameters

Name	Type	Description
subnetId	struct SubnetID	The identifier of the subnet for which the bottom-up nonce is queried.

Return Values

Name	Type	Description
[0]	bool	A tuple containing a boolean indicating if the subnet is registered and the current applied bottom-up nonce.
[1]	uint64

appliedTopDownNonce

function appliedTopDownNonce() external view returns (uint64)

Returns the current applied top-down nonce of the gateway.

postbox

function postbox(bytes32 id) external view returns (struct IpcEnvelope storableMsg)

Returns the storable message and its wrapped status from the postbox by a given identifier.

Parameters

Name	Type	Description
id	bytes32	The unique identifier of the message in the postbox.

majorityPercentage

function majorityPercentage() external view returns (uint64)

Returns the majority percentage required for certain consensus or decision-making processes.

listSubnets

function listSubnets() external view returns (struct Subnet[])

Returns the list of registered subnets.

Return Values

Name	Type	Description
[0]	struct Subnet[]	The list of the registered subnets.

getSubnetKeys

function getSubnetKeys() external view returns (bytes32[])

Returns the subnet keys.

getLastMembership

function getLastMembership() external view returns (struct Membership)

Returns the last membership received from the parent.

getLastConfigurationNumber

function getLastConfigurationNumber() external view returns (uint64)

Returns the last configuration number received from the parent.

getCurrentMembership

function getCurrentMembership() external view returns (struct Membership)

Returns the current membership.

getCurrentConfigurationNumber

function getCurrentConfigurationNumber() external view returns (uint64)

Returns the current configuration number.

getCheckpointInfo

function getCheckpointInfo(uint256 h) external view returns (struct QuorumInfo)

Returns quorum information for a specific checkpoint based on its height.

Parameters

Name	Type	Description
h	uint256	The block height of the checkpoint.

Return Values

Name	Type	Description
[0]	struct QuorumInfo	Quorum information associated with the given checkpoint height.

getCheckpointCurrentWeight

function getCheckpointCurrentWeight(uint256 h) external view returns (uint256)

Returns the checkpoint current weight corresponding to the block height.

getIncompleteCheckpointHeights

function getIncompleteCheckpointHeights() external view returns (uint256[])

Returns the incomplete checkpoint heights.

getIncompleteCheckpoints

function getIncompleteCheckpoints() external view returns (struct BottomUpCheckpoint[])

Returns the incomplete checkpoints.

getCheckpointRetentionHeight

function getCheckpointRetentionHeight() external view returns (uint256)

Returns the bottom-up checkpoint retention index.

getQuorumThreshold

function getQuorumThreshold(uint256 totalWeight) external view returns (uint256)

Returns the threshold required for quorum in this subnet, based on the configured majority percentage and the total weight of the validators.

Parameters

Name	Type	Description
totalWeight	uint256	The total weight to consider for calculating the quorum threshold.

Return Values

Name	Type	Description
[0]	uint256	The quorum threshold derived from the total weight and majority percentage.

getCheckpointSignatureBundle

function getCheckpointSignatureBundle(uint256 h) external view returns (struct BottomUpCheckpoint ch, struct QuorumInfo info, address[] signatories, bytes[] signatures)

Retrieves a bundle of information and signatures for a specified bottom-up checkpoint.

Parameters

Name	Type	Description
h	uint256	The height of the checkpoint for which information is requested.

Return Values

Name	Type	Description
ch	struct BottomUpCheckpoint	The checkpoint information at the specified height.
info	struct QuorumInfo	Quorum information related to the checkpoint.
signatories	address[]	An array of addresses of signatories who have signed the checkpoint.
signatures	bytes[]

getCurrentBottomUpCheckpoint

function getCurrentBottomUpCheckpoint() external view returns (bool exists, uint256 epoch, struct BottomUpCheckpoint checkpoint)

Returns the current bottom-up checkpoint.

Return Values

Name	Type	Description
exists	bool	- whether the checkpoint exists
epoch	uint256	- the epoch of the checkpoint
checkpoint	struct BottomUpCheckpoint	- the checkpoint struct

GatewayManagerFacet

register

function register(uint256 genesisCircSupply) external payable

register a subnet in the gateway. It is called by a subnet when it reaches the threshold stake

The subnet can optionally pass a genesis circulating supply that would be pre-allocated in the subnet from genesis (without having to wait for the subnet to be spawned to propagate the funds).

addStake

function addStake() external payable

addStake - add collateral for an existing subnet

releaseStake

function releaseStake(uint256 amount) external

release collateral for an existing subnet.

it can be used to release the stake or reward of the validator.

Parameters

Name	Type	Description
amount	uint256	The amount of stake to be released.

kill

function kill() external

kill an existing subnet.

The subnet's balance must be empty.

fund

function fund(struct SubnetID subnetId, struct FvmAddress to) external payable

credits the received value to the specified address in the specified child subnet.

There may be an associated fee that gets distributed to validators in the subnet. Currently this fee is zero, i.e. funding a subnet is free.

Parameters

Name	Type	Description
subnetId	struct SubnetID
to	struct FvmAddress

fundWithToken

function fundWithToken(struct SubnetID subnetId, struct FvmAddress to, uint256 amount) external

Sends funds to a specified subnet receiver using ERC20 tokens.

This function locks the amount of ERC20 tokens into custody and then mints the supply in the specified subnet. It checks if the subnet's supply strategy is ERC20 and if not, the operation is reverted. It allows for free injection of funds into a subnet and is protected against reentrancy.

Parameters

Name	Type	Description
subnetId	struct SubnetID	The ID of the subnet where the funds will be sent to.
to	struct FvmAddress	The funded address.
amount	uint256	The amount of ERC20 tokens to be sent.

release

function release(struct FvmAddress to) external payable

release() burns the received value locally in subnet and commits a bottom-up message to release the assets in the parent. The local supply of a subnet is always the native coin, so this method doesn't have to deal with tokens.

Parameters

Name	Type	Description
to	struct FvmAddress

GatewayMessengerFacet

sendContractXnetMessage

function sendContractXnetMessage(struct IpcEnvelope envelope) external payable returns (struct IpcEnvelope committed)

_Sends a general-purpose cross-message from the local subnet to the destination subnet. Any value in msg.value will be forwarded in the call.

IMPORTANT: Only smart contracts are allowed to trigger these cross-net messages. User wallets can send funds from their address to the destination subnet and then run the transaction in the destination normally._

Parameters

Name	Type	Description
envelope	struct IpcEnvelope	- the original envelope, which will be validated, stamped and committed during the send.

Return Values

Name	Type	Description
committed	struct IpcEnvelope	envelope.

propagate

function propagate(bytes32 msgCid) external payable

propagates the populated cross net message for the given cid

Parameters

Name	Type	Description
msgCid	bytes32	- the cid of the cross-net message

CheckpointingFacet

commitCheckpoint

function commitCheckpoint(struct BottomUpCheckpoint checkpoint) external

submit a verified checkpoint in the gateway to trigger side-effects.

this method is called by the corresponding subnet actor. Called from a subnet actor if the checkpoint is cryptographically valid.

Parameters

Name	Type	Description
checkpoint	struct BottomUpCheckpoint	The bottom-up checkpoint to be committed.

createBottomUpCheckpoint

function createBottomUpCheckpoint(struct BottomUpCheckpoint checkpoint, bytes32 membershipRootHash, uint256 membershipWeight) external

creates a new bottom-up checkpoint

Parameters

Name	Type	Description
checkpoint	struct BottomUpCheckpoint	- a bottom-up checkpoint
membershipRootHash	bytes32	- a root hash of the Merkle tree built from the validator public keys and their weight
membershipWeight	uint256	- the total weight of the membership

pruneBottomUpCheckpoints

function pruneBottomUpCheckpoints(uint256 newRetentionHeight) external

Set a new checkpoint retention height and garbage collect all checkpoints in range [retentionHeight, newRetentionHeight)

retentionHeight is the height of the first incomplete checkpointswe must keep to implement checkpointing. All checkpoints with a height less than retentionHeight are removed from the history, assuming they are committed to the parent.

Parameters

Name	Type	Description
newRetentionHeight	uint256	- the height of the oldest checkpoint to keep

addCheckpointSignature

function addCheckpointSignature(uint256 height, bytes32[] membershipProof, uint256 weight, bytes signature) external

checks whether the provided checkpoint signature for the block at height height is valid and accumulates that it

If adding the signature leads to reaching the threshold, then the checkpoint is removed from incompleteCheckpoints

Parameters

Name	Type	Description
height	uint256	- the height of the block in the checkpoint
membershipProof	bytes32[]	- a Merkle proof that the validator was in the membership at height height with weight weight
weight	uint256	- the weight of the validator
signature	bytes	- the signature of the checkpoint

execBottomUpMsgs

function execBottomUpMsgs(struct IpcEnvelope[] msgs, struct Subnet subnet) internal

submit a batch of cross-net messages for execution.

Parameters

Name	Type	Description
msgs	struct IpcEnvelope[]	The batch of bottom-up cross-network messages to be executed.
subnet	struct Subnet

TopDownFinalityFacet

commitParentFinality

function commitParentFinality(struct ParentFinality finality) external returns (bool hasCommittedBefore, struct ParentFinality previousFinality)

commit the ipc parent finality into storage and returns the previous committed finality This is useful to understand if the finalities are consistent or if there have been reorgs. If there are no previous committed fainality, it will be default to zero values, i.e. zero height and block hash.

Parameters

Name	Type	Description
finality	struct ParentFinality	- the parent finality

Return Values

Name	Type	Description
hasCommittedBefore	bool	A flag that indicates if a finality record has been committed before.
previousFinality	struct ParentFinality	The previous finality information.

storeValidatorChanges

function storeValidatorChanges(struct StakingChangeRequest[] changeRequests) external

Store the validator change requests from parent.

Parameters

Name	Type	Description
changeRequests	struct StakingChangeRequest[]	- the validator changes

applyFinalityChanges

function applyFinalityChanges() external returns (uint64)

Apply all changes committed through the commitment of parent finality.

Return Values

Name	Type	Description
[0]	uint64	configurationNumber The configuration number of the changes set that has been confirmed.

XnetMessagingFacet

applyCrossMessages

function applyCrossMessages(struct IpcEnvelope[] crossMsgs) external

Applies top-down cross-net messages locally. This is invoked by IPC nodes when drawing messages from their parent subnet for local execution. That's why the sender is restricted to the system sender, because this method is implicitly invoked by the node during block production.

It requires the caller to be the system actor.

Parameters

Name	Type	Description
crossMsgs	struct IpcEnvelope[]	The array of cross-network messages to be applied.

Subnet Registry

Subnet Registry Diamond

ConstructorParams

struct ConstructorParams {
 address gateway;
 address getterFacet;
 address managerFacet;
 address rewarderFacet;
 address checkpointerFacet;
 address pauserFacet;
 address diamondCutFacet;
 address diamondLoupeFacet;
 address ownershipFacet;
 bytes4[] subnetActorGetterSelectors;
 bytes4[] subnetActorManagerSelectors;
 bytes4[] subnetActorRewarderSelectors;
 bytes4[] subnetActorCheckpointerSelectors;
 bytes4[] subnetActorPauserSelectors;
 bytes4[] subnetActorDiamondCutSelectors;
 bytes4[] subnetActorDiamondLoupeSelectors;
 bytes4[] subnetActorOwnershipSelectors;
 enum SubnetCreationPrivileges creationPrivileges;
}

Subnet Registry Storage

struct SubnetRegistryActorStorage {
 address GATEWAY;
 address SUBNET_ACTOR_GETTER_FACET;
 address SUBNET_ACTOR_MANAGER_FACET;
 address SUBNET_ACTOR_REWARD_FACET;
 address SUBNET_ACTOR_CHECKPOINTING_FACET;
 address SUBNET_ACTOR_PAUSE_FACET;
 address SUBNET_ACTOR_DIAMOND_CUT_FACET;
 address SUBNET_ACTOR_LOUPE_FACET;
 address SUBNET_ACTOR_OWNERSHIP_FACET;
 bytes4[] subnetActorGetterSelectors;
 bytes4[] subnetActorManagerSelectors;
 bytes4[] subnetActorRewarderSelectors;
 bytes4[] subnetActorCheckpointerSelectors;
 bytes4[] subnetActorPauserSelectors;
 bytes4[] subnetActorDiamondCutSelectors;
 bytes4[] subnetActorDiamondLoupeSelectors;
 bytes4[] subnetActorOwnershipSelectors;
 mapping(address => mapping(uint64 => address)) subnets;
 mapping(address => uint64) userNonces;
 enum SubnetCreationPrivileges creationPrivileges;
}

Subnet Registry Diamond Facets

RegisterSubnetFacet

SubnetDeployed

event SubnetDeployed(address subnetAddr)

Event emitted when a new subnet is deployed.

newSubnetActor

function newSubnetActor(struct SubnetActorDiamond.ConstructorParams _params) external returns (address subnetAddr)

Deploys a new subnet actor.

Parameters

Name	Type	Description
_params	struct SubnetActorDiamond.ConstructorParams	The constructor params for Subnet Actor Diamond.

ensurePrivileges

function ensurePrivileges() internal view

SubnetGetterFacet

latestSubnetDeployed

function latestSubnetDeployed(address owner) external view returns (address subnet)

Returns the address of the latest subnet actor deployed by a user.

Parameters

Name	Type	Description
owner	address	The address of the user whose latest subnet deployment is queried.

getSubnetDeployedByNonce

function getSubnetDeployedByNonce(address owner, uint64 nonce) external view returns (address subnet)

Returns the address of a subnet actor deployed for a specific nonce by a user.

Parameters

Name	Type	Description
owner	address	The address of the user whose subnet deployment is queried.
nonce	uint64	The specific nonce associated with the subnet deployment.

getUserLastNonce

function getUserLastNonce(address user) external view returns (uint64 nonce)

Returns the last nonce used by the owner.

Parameters

Name	Type	Description
user	address	The address of the user whose last nonce is being queried.

getGateway

function getGateway() external view returns (address)

Returns the gateway.

getSubnetActorGetterFacet

function getSubnetActorGetterFacet() external view returns (address)

Returns the address of the SUBNET_GETTER_FACET.

getSubnetActorManagerFacet

function getSubnetActorManagerFacet() external view returns (address)

Returns the address of the SUBNET_MANAGER_FACET.

getSubnetActorRewarderFacet

function getSubnetActorRewarderFacet() external view returns (address)

Returns the address of the SUBNET_ACTOR_REWARDER_FACET.

getSubnetActorCheckpointerFacet

function getSubnetActorCheckpointerFacet() external view returns (address)

Returns the address of the SUBNET_ACTOR_CHECKPOINTER_FACET.

getSubnetActorPauserFacet

function getSubnetActorPauserFacet() external view returns (address)

Returns the address of the SUBNET_ACTOR_PAUSER_FACET.

getSubnetActorGetterSelectors

function getSubnetActorGetterSelectors() external view returns (bytes4[])

Returns the subnet actor getter selectors.

getSubnetActorManagerSelectors

function getSubnetActorManagerSelectors() external view returns (bytes4[])

Returns the subnet actor manager selectors.

getSubnetActorRewarderSelectors

function getSubnetActorRewarderSelectors() external view returns (bytes4[])

Returns the subnet actor rewarder selectors.

getSubnetActorCheckpointerSelectors

function getSubnetActorCheckpointerSelectors() external view returns (bytes4[])

Returns the subnet actor checkpointer selectors.

getSubnetActorPauserSelectors

function getSubnetActorPauserSelectors() external view returns (bytes4[])

Returns the subnet actor pauser selectors.

updateReferenceSubnetContract

function updateReferenceSubnetContract(address newGetterFacet, address newManagerFacet, bytes4[] newSubnetGetterSelectors, bytes4[] newSubnetManagerSelectors) external

Updates references to the subnet contract components, including facets and selector sets. Only callable by the contract owner.

Parameters

Name	Type	Description
newGetterFacet	address	The address of the new subnet getter facet.
newManagerFacet	address	The address of the new subnet manager facet.
newSubnetGetterSelectors	bytes4[]	An array of function selectors for the new subnet getter facet.
newSubnetManagerSelectors	bytes4[]	An array of function selectors for the new subnet manager facet.

Subnet Actor

Subnet Actor Diamond

ConstructorParams

struct ConstructorParams {
  uint256 minActivationCollateral;
  uint64 minValidators;
  uint64 bottomUpCheckPeriod;
  address ipcGatewayAddr;
  uint16 activeValidatorsLimit;
  uint8 majorityPercentage;
  enum ConsensusType consensus;
  int8 powerScale;
  enum PermissionMode permissionMode;
  struct SupplySource supplySource;
  struct SubnetID parentId;
}

SubnetActorStorage

struct SubnetActorStorage {
  uint256 genesisCircSupply;
  uint256 lastBottomUpCheckpointHeight;
  uint256 minActivationCollateral;
  uint256 bottomUpCheckPeriod;
  bytes32 currentSubnetHash;
  address ipcGatewayAddr;
  uint64 maxMsgsPerBottomUpBatch;
  uint8 majorityPercentage;
  int8 powerScale;
  enum ConsensusType consensus;
  bool bootstrapped;
  uint64 minValidators;
  bool killed;
  struct SupplySource supplySource;
  struct SubnetID parentId;
  struct ValidatorSet validatorSet;
  struct StakingChangeLog changeSet;
  struct StakingReleaseQueue releaseQueue;
  mapping(address => string) bootstrapNodes;
  struct EnumerableSet.AddressSet bootstrapOwners;
  mapping(uint256 => struct BottomUpCheckpoint) committedCheckpoints;
  struct Validator[] genesisValidators;
  mapping(address => uint256) genesisBalance;
  address[] genesisBalanceKeys;
}

Subnet Actor Diamond Facets

SubnetActorCheckpointingFacet

submitCheckpoint

function submitCheckpoint(struct BottomUpCheckpoint checkpoint, address[] signatories, bytes[] signatures) external

Submits a checkpoint commitment for execution.

It triggers the commitment of the checkpoint and any other side-effects that need to be triggered by the checkpoint such as relayer reward book keeping.

Parameters

Name	Type	Description
checkpoint	struct BottomUpCheckpoint	The executed bottom-up checkpoint.
signatories	address[]	The addresses of validators signing the checkpoint.
signatures	bytes[]	The signatures of validators on the checkpoint.

validateActiveQuorumSignatures

function validateActiveQuorumSignatures(address[] signatories, bytes32 hash, bytes[] signatures) public view

Checks whether the signatures are valid for the provided signatories and hash within the current validator set. Reverts otherwise.

Signatories in signatories and their signatures in signatures must be provided in the same order. Having it public allows external users to perform sanity-check verification if needed.

Parameters

Name	Type	Description
signatories	address[]	The addresses of the signatories.
hash	bytes32	The hash of the checkpoint.
signatures	bytes[]	The packed signatures of the checkpoint.

ensureValidCheckpoint

function ensureValidCheckpoint(struct BottomUpCheckpoint checkpoint) internal view

Ensures the checkpoint is valid.

The checkpoint block height must be equal to the last bottom-up checkpoint height or the next one or the number of bottom up messages exceeds the max batch size.

SubnetActorGetterFacet

getParent

function getParent() external view returns (struct SubnetID)

Returns the parent subnet id.

permissionMode

function permissionMode() external view returns (enum PermissionMode)

Returns the permission mode.

ipcGatewayAddr

function ipcGatewayAddr() external view returns (address)

Returns the gateway address.

minValidators

function minValidators() external view returns (uint64)

Returns the minimum validators number needed to activate the subnet.

majorityPercentage

function majorityPercentage() external view returns (uint8)

Returns the majority percentage required for consensus.

activeValidatorsLimit

function activeValidatorsLimit() external view returns (uint16)

Fetches the limit on the number of active validators.

getConfigurationNumbers

function getConfigurationNumbers() external view returns (uint64, uint64)

Returns the next and start configuration numbers related to the changes.

genesisValidators

function genesisValidators() external view returns (struct Validator[])

Returns the initial set of validators of the genesis block.

genesisCircSupply

function genesisCircSupply() external view returns (uint256)

genesisBalances

function genesisBalances() external view returns (address[], uint256[])

Retrieves initial balances and corresponding addresses of the genesis block.

bottomUpCheckPeriod

function bottomUpCheckPeriod() external view returns (uint256)

Returns the period for bottom-up checkpointing operations.

lastBottomUpCheckpointHeight

function lastBottomUpCheckpointHeight() external view returns (uint256)

Returns the block height of the last bottom-up checkpoint.

consensus

function consensus() external view returns (enum ConsensusType)

Returns the consensus protocol type used in the subnet.

bootstrapped

function bootstrapped() external view returns (bool)

Checks if the subnet has been bootstrapped.

killed

function killed() external view returns (bool)

Checks if the subnet has been terminated or "killed".

minActivationCollateral

function minActivationCollateral() external view returns (uint256)

Returns the minimum collateral required for subnet activation.

getValidator

function getValidator(address validatorAddress) external view returns (struct ValidatorInfo validator)

Returns detailed information about a specific validator.

Parameters

Name	Type	Description
validatorAddress	address	The address of the validator to query information for.

getTotalValidatorsNumber

function getTotalValidatorsNumber() external view returns (uint16)

Returns the total number of validators (active and waiting).

getActiveValidatorsNumber

function getActiveValidatorsNumber() external view returns (uint16)

Returns the number of active validators.

getTotalConfirmedCollateral

function getTotalConfirmedCollateral() external view returns (uint256)

Returns the total amount of confirmed collateral across all validators.

getTotalCollateral

function getTotalCollateral() external view returns (uint256)

Returns the total collateral held by all validators.

getTotalValidatorCollateral

function getTotalValidatorCollateral(address validator) external view returns (uint256)

Returns the total collateral amount for a specific validator.

Parameters

Name	Type	Description
validator	address	The address of the validator for which collateral is queried.

getPower

function getPower(address validator) external view returns (uint256)

Checks if the validator address is in an active state.

Parameters

Name	Type	Description
validator	address	The address of the checked validator

isActiveValidator

function isActiveValidator(address validator) external view returns (bool)

Checks if the validator address is an active validator

isWaitingValidator

function isWaitingValidator(address validator) external view returns (bool)

Checks if the validator is in a waiting state.

Parameters

Name	Type	Description
validator	address	The address of the checked validator.

bottomUpCheckpointAtEpoch

function bottomUpCheckpointAtEpoch(uint256 epoch) public view returns (bool exists, struct BottomUpCheckpoint checkpoint)

returns the committed bottom-up checkpoint at specific epoch.

Parameters

Name	Type	Description
epoch	uint256	- the epoch to check.

Return Values

Name	Type	Description
exists	bool	- whether the checkpoint exists.
checkpoint	struct BottomUpCheckpoint	- the checkpoint struct.

bottomUpCheckpointHashAtEpoch

function bottomUpCheckpointHashAtEpoch(uint256 epoch) external view returns (bool, bytes32)

returns the historical committed bottom-up checkpoint hash.

Parameters

Name	Type	Description
epoch	uint256	- the epoch to check

Return Values

Name	Type	Description
[0]	bool	exists - whether the checkpoint exists
[1]	bytes32	hash - the hash of the checkpoint

powerScale

function powerScale() external view returns (int8)

Returns the power scale in number of decimals from whole FIL.

getBootstrapNodes

function getBootstrapNodes() external view returns (string[])

Returns the bootstrap nodes addresses.

crossMsgsHash

function crossMsgsHash(struct IpcEnvelope[] messages) external pure returns (bytes32)

Computes a hash of an array of IpcEnvelopes.

This exists for testing purposes.

Parameters

Name	Type	Description
messages	struct IpcEnvelope[]	An array of cross-chain envelopes to be hashed.

Return Values

Name	Type	Description
[0]	bytes32	The keccak256 hash of the encoded cross-chain messages.

supplySource

function supplySource() external view returns (struct SupplySource supply)

Returns the supply strategy for the subnet.

SubnetActorManagerFacet

preFund

function preFund() external payable

method to add some initial balance into a subnet that hasn't yet bootstrapped.

This balance is added to user addresses in genesis, and becomes part of the genesis circulating supply.

preRelease

function preRelease(uint256 amount) external

method to remove funds from the initial balance of a subnet.

This method can be used by users looking to recover part of their initial balance before the subnet bootstraps.

Parameters

Name	Type	Description
amount	uint256	The amount to remove.

setFederatedPower

function setFederatedPower(address[] validators, bytes[] publicKeys, uint256[] powers) external

Sets the federated power of validators.

method that allows the contract owner to set the validators' federated power.

Parameters

Name	Type	Description
validators	address[]	The addresses of validators.
publicKeys	bytes[]	The public keys of validators.
powers	uint256[]	The federated powers to be assigned to validators.

join

function join(bytes publicKey) external payable

method that allows a validator to join the subnet. If the total confirmed collateral of the subnet is greater or equal to minimum activation collateral as a result of this operation, then subnet will be registered.

Parameters

Name	Type	Description
publicKey	bytes	The off-chain 65 byte public key that should be associated with the validator

stake

function stake() external payable

method that allows a validator to increase its stake. If the total confirmed collateral of the subnet is greater or equal to minimum activation collateral as a result of this operation, then subnet will be registered.

unstake

function unstake(uint256 amount) external

method that allows a validator to unstake a part of its collateral from a subnet.

leave must be used to unstake the entire stake.

Parameters

Name	Type	Description
amount	uint256	The amount to unstake.

leave

function leave() external

method that allows a validator to leave the subnet.

kill

function kill() external

method that allows to kill the subnet when all validators left.

It is not a privileged operation.

addBootstrapNode

function addBootstrapNode(string netAddress) external

Add a bootstrap node.

Parameters

Name	Type	Description
netAddress	string	The network address of the new bootstrap node.

SubnetActorPauseFacet

pause

function pause() external

Pauses all contract functions with the whenNotPaused modifier.

unpause

function unpause() external

Unpauses all contract functions with the whenNotPaused modifier.

paused

function paused() external view returns (bool)

Returns true if the SubnetActor contract is paused.

SubnetActorRewardFacet

claim

function claim() external

Validator claims their released collateral.