The contractRegistry manages the PoS contracts list and active managers. The contract is the basis of the system and allows any contract or user to retrieve the up-to-date contract lists.
The contractRegistry pushes contract address updates to the PoS managed contracts. The contract registry is the core component of the PoS contracts upgrade and allows to transition to a new contract for each contract in the system, as well as the registry itself.
The staking contract handler connects the staking contract to the Orbs PoS contracts and to Orbs’ contracts administrative, managed by the contractRegistry.
The stakingContractHandler provides an infrastructure for connecting an additional staking contract or isolating the staking contract actions from the rest of the PoS contracts if needed.
The delegations contract manages the delegation database for each participant in Orbs PoS. The delegation contract holds for participant his selected Guardian and the participant’s self-stake as well as the stake delegated to the participant.
On each change in a participant’s delegation, self stake or delegated stake, the contract notifies the stakingRewards contract that calculates the rewards accordingly. In addition, the delegations contract notifies the elections contract upon any change in a participant’s delegated stake, masking the delegator’s notation from the election contract.
The election contract connects the delegation contract with the committee, Guardians Registration and certification contracts. In addition, the election contract implements the voting logic both for voteUnready and voteOut and manages the node state machine notification readyForCommittee and readyToSynct.
Upon a notification from the delegation contract, the elections contract calculates the participant's new effective stake and updates the committee contract. Upon a Guardian’s readyForCommittee, the committee, the election contract validates that the Guardian is registered and not voted-out and requests that the committee contract add it. If a Guardian was voted-unready or voted-out, the elections contract requests that the committee contract remove it from the committee.
The committee contract manages the current committee state. The committee contract holds the current committee members and their weights. Upon an effective stake change notice from the election contract, the committee contract updates the committee member weight and emits an update event.
On a request to join the committee, the committee member checks that the candidate is qualified to join. If the candidate’s weight is higher than the committee member with the lowest weight, the candidate will join the committee instead of the minimal weight Guardian. Upon a change in the committee members list or their certification, the contact notifies the stakingRewards and FeesAndBootstrap contracts on the leaving and joining members to update their rewards state.
The stakingRewards contract manages the staking rewards state of the participants in the PoS ecosystem. The staking rewards architecture is based on the rewards per share architecture common in framing pools. The contract architecture was designed for the Orbs PoS architecture which is based on 3 levels: global allocation, committee Guardians receiving their share based on their weight, and delegators receiving a portion of their Guardian rewards based on their stake.
The staking rewards contract is updated upon two events: an update to a delegator’s stake and a change in a Guardian’s committee membership. A participant may claim his staking rewards that are staked in the staking contract and the system state is updated accordingly. The staking withdraws funds from the stakingRewardsWallet holds tokens up to the total unclaimed amount for all participants.
The feesAndBootstrapRewards contract manages the fees and bootstrap rewards state of the Guardians. The fees and bootstrap rewards architecture is similar to the architecture of the stakingRewards contract.
In addition the feesAndBootstrapRewards withdraws bootstrap rewards from the bootstrap wallet. It may hold tokens up to the total unclaimed amount for all Guardians.
The stakingRewardsWallet and bootstrapRewardsWallet hold the protocol fund allowing the relevant rewards contract to withdraw funds up to the maximal rate that was set. The protocol wallets provide a simple, and thus secure, mechanism to store the protocol funds.
The contract architecture is based on 2 levels: global allocation, committee Guardians. The feesAndBootstrapRewards collects fees from two instances of fees wallets the certificated and general virtual chains fees. The protocol wallets are disconnected from the PoS contracts governance and management infrastructure and are managed by two types of administrators: a functional administrator that sets the wallet’s client and a migration administrator that controls the withdrawal of funds.
The fees wallets maintain the subscription fees paid by virtual chains. Two separate instances of fees wallets are deployed one for general virtual chains fees and one for certified virtual chains fees. The fees wallets store the subscription fees in 30 days buckets, to provide an accurate division of the fees for each time period.
The two fees wallets client, the feesAndBootstrapRewards, collect the paid fees for the time period since the last collect.
The GuardiansRegistration contract stores the Guardians registration data. And allow Guardians to register, modify their data and unregister. In addition the contact stores a metadata map allowing each Guardian to store general purpose keys to be queried by the Orbs platform. For example, a link to the Guardian identification data may be stored at the "ID_FORM_URL" metadata key.
The guardiansRegistration provides mapping functions, such as from Orbs addresses to Ethereum addresses, used by other contracts to allow function calls using the Orbs address. The guardiansRegistration contract notifies the election contract on changes in Guardians registration status.
The certification contract stores the certification status for each Guardian. The certification data is managed by the certificationManager that may set and clear a Guardian’s certification.
The certification contract notifies the election contract on any change in a guardian certification.
The subscription contract manages the virtual chains’ subscription status. The contract allows developers to create a virtual chain, modify its properties, including metadata properties used by the Orbs platform, and extend a virtual chain subscription.
Virtual chain creation and subscription extension are not done by directly interacting with the subscriptions contract but rather by calling the subscription plan contract that updates the subscriptions contract. The subscriptions contact holds a list of valid subscription plan contracts.
The subscription plan contract is a stateless contract, responsible for the plan and fee structure of a virtual chain subscription. Virtual chain owners call the subscription plan contract to create a virtual chain and extend its subscription.
The subscription plan contracts assigns a tier (plan) and the monthly fee rate based on the contract plan. Multiple subscription contracts may be deployed in the system.
The protocol contact is responsible to set and synchronize the Orbs platform’s protocol version upgrades. The protocol contact supports multiple deployment subsets, such as: production and canary, each may operate on the different protocol version.
Upon protocol version upgrade, a future time is set as the cutoff date for the protocol upgrade.
Orbs’ PoS contacts architecture is designed for future migration, including migration of individual contracts. Contracts in the PoS system that interact with other contracts store their current address in the contact storage. Upon a migration of a contract, the registry sends a push notification to all its managed contacts to update their contract list accordingly.
In addition to the system contracts, the contract registry stores the up-to-date managers list. To ensure synchronization, the contacts query the registry on the current relevant manager before every administrative operation. Managers are appointed by the registryAdmin, which can appoint or revoke the role of a manager.
The contract registry emits an update event for any contact address update as well as upon registry migration. By knowing the initial contract registry address, an application may track the up to date contracts list as well as construct an integrated event list from all the contract versions.
An exception to contacts management by the contract registry are the protocol wallet contracts. The protocol wallet contracts have separate admins that manage their functionality and migration.
The registryAdmin manages the contract registry and is the most privileged administrative entity. The registryAdmin can update the registry properties and contacts and assign managers. The registryAdmin admin is stored on each of the contracts managed by the registry allowing to modify an individual contact appointed registry.
The initializationAdmin is responsible to initialize the contracts state, from administrative parameters to network migrated state such as delegations, or Guardians list. The initializationAdmin is set to the contract deployer and his actions may be considered as an extension to the contact constructor. The initializationAdmin is a highly privileged role, targeting migration periods, it can not be transferred and the role is revoked once initialization is completed.
The migrationManager is appointed by the contract registry, and controls all the migration actions. The migration manager can set contacts in the registry and migrate state and balances of contacts. The migrationManager has high privileges therefore it is recommended to appoint a migrationManager for a specific mission, such as a migration to a new contracts version and then revoke its privileges.
The functionalManager is appointed by the contract registry, and controls contracts administrative parameters and functionality.
The certificationManager manages the Guardians’ certification. The certificationManager can set and clear a Guardian certification status. The Guardian certification is determined according to the Guardian’s identification data as advertised in the registration contract using the ID url metadata.
Back to Orbs Overview