antelopeio / reference-contracts

Reference contracts

Reference contracts are a collection of contracts deployable to an Antelope blockchain which implements a lot of critical functionality that goes beyond what is provided by the base Antelope protocol.

The Antelope protocol includes capabilities such as:

• an accounts and permissions system which enables a flexible permission system that allows authorization authority over specific actions in a transaction to be satisfied by the appropriate combination of signatures;
• a consensus algorithm to propose and finalize blocks by a set of active block producers that can be arbitrarily selected by privileged smart contracts running on the blockchain;
• a basic resource management system that tracks usage of CPU/NET and RAM per account and enforces limits based on per-account quotas that can be adjusted by privileged smart contracts.

However, the Antelope protocol itself does not immediately provide:

• a mechanism for multiple accounts to reach consensus on authorization of a proposed transaction on-chain before executing it;
• a consensus mechanism that goes beyond the consensus algorithm to determine how block producers are selected and to align incentives by providing appropriate rewards and punishments to block producers or the entities that get them into that position;
• more sophisticated resource management systems that create markets for users to acquire resource rights;
• or, even something as seemingly basic as the concept of tokens (whether fungible or non-fungible).

The reference contracts in this repository provide all of the above and more by building higher-level features or abstractions on top of the primitive mechanisms provided by the Antelope protocol.

The collection of reference contracts consists of the following individual contracts:

• boot contract: A minimal contract that only serves the purpose of activating protocol features which enables other more sophisticated contracts to be deployed onto the blockchain. (Note: this contract must be deployed to the privileged eosio account.)
• bios contract: A simple alternative to the core contract which is suitable for test chains or perhaps centralized blockchains. (Note: this contract must be deployed to the privileged eosio account.)
• token contract: A contract enabling fungible tokens.
• core contract: A monolithic contract that includes a variety of different functions which enhances a base Antelope blockchain for use as a public, decentralized blockchain in an opinionated way. (Note: This contract must be deployed to the privileged eosio account. Additionally, this contract requires that the token contract is deployed to the eosio.token account and has already been used to setup the core token.) The functions contained within this monolithic contract include (non-exhaustive):
  • Delegated Proof of Stake (DPoS) consensus mechanism for selecting and paying (via core token inflation) a set of block producers that are chosen through delegation of the staked core tokens.
  • Allocation of CPU/NET resources based on core tokens in which the core tokens are either staked for an indefinite allocation of some fraction of available CPU/NET resources, or they are paid as a fee in exchange for a time-limited allocation of CPU/NET resources via REX or via PowerUp.
  • An automated market maker enabling a market for RAM resources which allows users to buy or sell available RAM allocations.
  • An auction for bidding for premium account names.
• multisig contract: A contract that enables proposing Antelope transactions on the blockchain, collecting authorization approvals for many accounts, and then executing the actions within the transaction after authorization requirements of the transaction have been reached. (Note: this contract must be deployed to a privileged account.)
• wrap contract: A contract that wraps around any Antelope transaction and allows for executing its actions without needing to satisfy the authorization requirements of the transaction. If used, the permissions of the account hosting this contract should be configured to only allow highly trusted parties (e.g. the operators of the blockchain) to have the ability to execute its actions. (Note: this contract must be deployed to a privileged account.)

Repository organization

The main branch contains the latest state of development; do not use this for production. Refer to the releases page for current information on releases, pre-releases, and obsolete releases as well as the corresponding tags for those releases.

Supported Operating Systems

CDT is required to build contracts. Any operating systems supported by CDT is sufficient to build the reference contracts.

To build and run the tests as well, Spring is also required as a dependency, which may have its further restrictions on supported operating systems.

Building

The build guide below will assume you are running Ubuntu 20.04. However, as mentioned above, other operating systems may also be supported.

Build or install CDT dependency

The CDT dependency is required with a minimum version of 3.0.

The easiest way to satisfy this dependency is to install CDT on your system through a package. Find the release of a compatible version of CDT from its releases page, download the package file appropriate for your OS from the attached assets, and install the package.

Alternatively, you can build CDT from source. Please refer to the guide in the CDT README for instructions on how to do this. If you choose to go with building CDT from source, please keep the path to the build directory in the shell environment variable CDT_BUILD_PATH for later use when building the reference contracts.

Optionally build Spring dependency

The Spring dependency is optional. It is only needed if you wish to also build the tests using the BUILD_TESTS CMake flag.

Unfortunately, it is not currently possible to satisfy the contract testing dependencies through the Spring packages made available from the Spring releases page. So if you want to build the contract tests, you will first need to build Spring from source.

Please refer to the guide in the Spring README for instructions on how to do this. If you choose to go with building Spring from source, please keep the path to the build directory in the shell environment variable SPRING_BUILD_PATH for later use when building the reference contracts.

Build reference contracts

Beyond CDT and optionally Spring (if also building the tests), no additional dependencies are required to build the reference contracts.

The instructions below assume you are building the reference contracts with tests, have already built Spring from source, and have the CDT dependency installed on your system. For some other configurations, expand the hidden panels placed lower within this section.

For all configurations, you should first cd into the directory containing cloned reference contracts repository.

Build reference contracts with tests using Spring built from source and with installed CDT package:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON -Dspring_DIR="${SPRING_BUILD_PATH}/lib/cmake/spring" ..
make -j $(nproc)

Note: CMAKE_BUILD_TYPE has no impact on the WASM files generated for the contracts. It only impacts how the test binaries are built. Use -DCMAKE_BUILD_TYPE=Debug if you want to create test binaries that you can debug.

Build reference contracts with tests using Spring and CDT both built from source

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON -Dcdt_DIR="${CDT_BUILD_PATH}/lib/cmake/cdt" -Dspring_DIR="${SPRING_BUILD_PATH}/lib/cmake/spring" ..
make -j $(nproc)

Build reference contracts without tests and with CDT build from source

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF -Dcdt_DIR="${CDT_BUILD_PATH}/lib/cmake/cdt" ..
make -j $(nproc)

Supported CMake options

The following is a list of custom CMake options supported in building the reference contracts (default values are shown below):

-DBUILD_TESTS=OFF                       Do not build the tests

-DSYSTEM_CONFIGURABLE_WASM_LIMITS=ON    Enable use of the CONFIGURABLE_WASM_LIMITS
                                        protocol feature

-DSYSTEM_BLOCKCHAIN_PARAMETERS=ON       Enable use of the BLOCKCHAIN_PARAMETERS
                                        protocol feature

Running tests

Assuming you built with BUILD_TESTS=ON, you can run the tests.

cd build/tests
ctest -j $(nproc)

License

MIT

reference-contracts's Issues

IF: Enforce finalizer policy can be satisfied

Assert that the sum of the weights is greater than or equal to the threshold.

IF: unifying set_finalizers interface with Leap and BIOS Contract

Currently CDT and Leap use abi_finalizer_policy while BIOS contract uses finalizer_policy. Some field names and types are also different. Unify them to reduce future confusion.

Error messages in BIOS contract in Leap libtester are not consistent with BIOS contract in Reference-Contracts. Should be kept consistent.

CDT AntelopeIO/cdt#257
Leap AntelopeIO/leap#1992

Move bootseq_tests/bootseq_test from Spring into here

Update as necessary to make it work with Savanna enabled libtester and any further changes needed to reflect changes made to the core contract since this test was written (e.g. changes to how the b1 account is handled.

See original test here: https://github.com/AntelopeIO/spring/blob/2e6bebc4e10ea4f8ecba2a5c021d808262b5661e/unittests/bootseq_tests.cpp

eosio_system_tests/producer_wtmsig and eosio_system_tests/producer_wtmsig_transition fail under default Savanna libtester

1. tests/eosio.system_tests.cpp(847): fatal error: in "eosio_system_tests/producer_wtmsig": critical check control->active_producers().version == 1u has failed [0 != 1]
2. tests/eosio.system_tests.cpp(937): fatal error: in "eosio_system_tests/producer_wtmsig_transition": critical check control->active_producers().version == 1u has failed [0 != 1]

Those two failures are caused by the new way to process proposer schedule in Savanna. 2 rounds of blocks (24) should be produced, instead of 2:

reference-contracts/tests/eosio.system_tests.cpp

Line 846 in cd645b5

produce_blocks(2);

is there a reason for unregprod to leave the entry

unregprod marks an entry in producer_info as inactive and erases the key, instead of deleting it.

As a result, the table only grows and consumes the memory without a need.

is anything preventing us from deleting the entry on unreg?

Postpone decision on delay_sec to assume for authorization checking within eosio.msig until transaction execution

Limitation of the current eosio.msig contract

Currently, within the eosio.msig contract, a particular value of delay_sec must be committed to when a user proposes a transaction. That value is used to determine which of the wait_weights should be considered satisfied with the permission authorities traversed when checking the authorizations on the transaction.

But this comes with a limitation. If there are multiple paths to satisfying the authorizations which assume different values of delay_sec, then the path to take must be committed to during proposal time. If approvers decide to take a different path, they are forced to replace the proposal with another one with a different value of delay_sec. Or alternatively, they could put competing (and naturally conflicting) proposals for the various paths that can be exercised, and then see which one gets the necessary approvals first.

The limitation is more clear with a concrete example. Consider a transaction requiring an authority that can be satisfied by one of two paths: 1. two accounts approve and the transaction can be executed with no delay; 2. one account approves and the transaction can be executed with a delay of 48 hours. The transaction proposal expects both approvers to be ready to review the msig and approve within 24 hours. So the proposer proposes a transaction with a delay_sec of 0. The first approver approves the proposal within 24 hours. But the second approver is not available and 48 hours passes since the time the first approval was made. At this point the proposer may wish that they had proposed with a delay_sec of 172800 (48 hours). If they had done so, they would be able to execute the proposed transaction without requiring the second approver. But to change it now, they would have to replace the proposal with a new one that sets the delay_sec of 172800 and wait again for the first approver to approve this second proposal as well.

Proposed enhancement to eosio.msig contract

The proposer should not need to commit to a particular value of delay_sec. Instead, a value for delay_sec can optionally be provided at execution time. And in fact, the propose action can assert that the delay_sec value within a proposed transaction is always zero.

The earliest_execution_time field in a proposal is no longer used. Instead, the time aspects of authorization checking are postponed until the exec call. The approve and unapprove action no longer need to make calls to check transaction authorizations.

The logic of authorization checking for the transaction becomes more sophisticated during the exec call. First, a new argument is needed to provide the assumed delay_sec to use when doing authorization checking; though it can default to 0. The assumed delay_sec filters out any approvals that are too recent when it comes to transaction authorization checking.

Details

propose action

Because the proposer no longer needs to commit to a particular value of delay_sec, the action should simply assert that the value of delay_sec in the transaction header of the proposed transaction is zero.

There is no more need for the earliest_execution_time field in the proposal table going forward. However, the field should not be removed because existing tables have a serialization expecting that field to exist. So the field will need to forever remain in its current place in the struct for the table named proposal to avoid a mistake in the future where a new binary extension is added to the struct for some future feature.

The propose action can continue to create the proposal table entry with the earliest_execution_time initialize to the empty optional. Going forward, new proposals will always have the earliest_execution_time remain as an empty optional.

approve action

Consider the following code:

reference-contracts/contracts/eosio.msig/src/eosio.msig.cpp

Lines 129 to 137 in 76197b4

	if( prop.earliest_exec_time.has_value() ) {
	if( !prop.earliest_exec_time->has_value() ) {
	auto table_op = [](auto&&, auto&&){};
	if( trx_is_authorized(get_approvals_and_adjust_table(get_self(), proposer, proposal_name, table_op), prop.packed_transaction) ) {
	proptable.modify( prop, proposer, [&]( auto& p ) {
	p.earliest_exec_time.emplace(time_point{ current_time_point() + eosio::seconds(trx_header.delay_sec.value)});
	});
	}
	}

Both the existing code and the code with the proposed changes in this issue would enter the if( prop.earliest_exec_time.has_value() ) if statement. However, the code within the if( !prop.earliest_exec_time->has_value() ) { if statement is no longer necessary with the proposed changes in this issue. The earliest_exec_time is only needed for the exec action, and with the changes discussed here, the exec action would have an alternative way of handling the time aspect of authorization checking. The exec action could still do the time check if earliest_exec_time->has_value() is true; but that condition would not relevant for any new proposals.

It may me desirable for the approve action to always ensure earliest_exec_time of the proposal is the empty optional, but this is not necessary.

unapprove action

Consider the following code:

reference-contracts/contracts/eosio.msig/src/eosio.msig.cpp

Lines 169 to 177 in 76197b4

	if( prop.earliest_exec_time.has_value() ) {
	if( prop.earliest_exec_time->has_value() ) {
	auto table_op = [](auto&&, auto&&){};
	if( !trx_is_authorized(get_approvals_and_adjust_table(get_self(), proposer, proposal_name, table_op), prop.packed_transaction) ) {
	proptable.modify( prop, proposer, [&]( auto& p ) {
	p.earliest_exec_time.emplace();
	});
	}
	}

Both the existing code and the code with the proposed changes in this issue would enter the if( prop.earliest_exec_time.has_value() ) if statement. However, the code within the if( prop.earliest_exec_time->has_value() ) { if statement is no longer necessary with the proposed changes in this issue for the same reasons discussed above for the approve action.

It may me desirable for the unapprove action to always ensure earliest_exec_time of the proposal is the empty optional, but this is not necessary.

exec action

An argument eosio::binary_extension<uint32_t> delay_sec (or alternatively eosio::binary_extension<std::optional<uint32_t>> delay_sec) should be added to the end of the existing exec action. The default value for delay_sec is 0. This value provided via delay_sec is used to subtract that number of seconds from the current time_point of the block and get the approval_threshold_time.

Then that time is used to filter the set of approvals on the proposal to only select for those approvals that have not been invalidated and have a time of approval less than or equal to the approval_threshold_time. Those filtered approvals are used to check if the proposed transaction is authorized, however the transaction authorization is done on a variation of the transaction in which the delay_sec field of the transaction header is replaced by the value provided in the delay_sec argument of the action. If that authorization check passes, then the exec action will execute the transaction by sending inline actions.

Note: For old proposals that use the old approval structure which does not have time, the action will assert if a non-zero value is provided in the delay_sec argument of the action. This is not a meaningful limitation since the existing contract already asserts if an old proposal has a proposed transaction with a non-zero value for delay_sec within its transaction header and asks the user to cancel the proposal and retry.

CICD build fails to find hotstuff_integration CDT

CICD builds are failing, as the CDT hotstuff_integration branch no longer exists.

Add bios contract action to support Instant Finality

Depends on AntelopeIO/cdt#215 and AntelopeIO/cdt#210.

Add setfinalizer action to bios contract to set a new finalizer set.

Each key should have a proof of possession which must be validated.

IF: Update reference contract tests to work with changes to CDT and Leap

Update tests to new way of accessing proposer schedule (related to changes in AntelopeIO/leap#1941), setting finalizers (related to changes in AntelopeIO/cdt#257), and verifying that the new finalizers have been set (related to changes in AntelopeIO/leap#1911).

eosio_bios_if_tests/set_1_finalizer fails under default Savanna libtester

tests/eosio.bios_inst_fin_tests.cpp(60): error: in "eosio_bios_if_tests/set_1_finalizer": check output_json.find("\"generation\": 1") != std::string::npos has failed [18446744073709551615 == 18446744073709551615]
tests/eosio.bios_inst_fin_tests.cpp(91): error: in "eosio_bios_if_tests/set_2_finalizers": check output_json.find("\"generation\": 1") != std::string::npos has failed [18446744073709551615 == 18446744073709551615]

We need to start with legacy_tester as the test transitions to Savanna explicitly by calling setfinalizers host function:

reference-contracts/tests/eosio.bios_inst_fin_tests.cpp

Line 19 in cd645b5

class eosio_bios_if_tester : public tester {

Avoid usage of std::deque (and maybe std::map) in contract actions or tables

When using a sequence of objects, ideally we would stick to just using an std::vector rather than more sophisticated types like std::deque or std::map.

It does not really make sense to use a std::deque in a table given how there should be few items in the sequence anyway given that it must be serialized to a table record.

There is one usage of std::deque in a table record within the REX sub-component of the core contract. This should be replaced with std::vector. Be careful that this does not change the ABI in incompatible ways. It may be necessary to create a custom struct to use as the element type of the std::vector rather than using an std::pair directly.

Also the invariant of unique keys in std::map are not maintained as part of the Antelope database API or even the eosio::multi_index abstraction over it. Only a sequence of items are stored in the serialization. Using a map ensures there are no key duplicates in the data structure prior to it being serialized which can be helpful. In addition, deserialization from the table data ensures the constructed map instance does not have duplicate keys either but at the cost of hiding any duplicate keys that may have existed in the serialization. This loss of information could possibly lead to errors in the contract and it may be safer to be explicit in converting an std::vector in the table record into an std::map if desired with validation of the data to check for any duplicate keys.

There is one usage of std::map in a table record within the REX sub-component of the core contract. Consider whether this should be replaced with std::vector or not. If so, then be careful that the change does not change the ABI in incompatible ways. It may be necessary to create a custom struct to use as the element type of the std::vector rather than using an std::pair directly.

Add project and label to all new reference-contracts issues

For all newly created issues in the reference-contracts repo, we'd like to

• Assign the "Team Backlog" project
• Assign the "triage" label

Example implemented for leap: https://github.com/AntelopeIO/leap/blob/main/.github/workflows/label_new_issues.yaml

Cannot compile reference-contracts with newest cdt 4.0.0

#0 25.00 -- Build files have been written to: /app/reference-contracts/build
#0 25.02 Scanning dependencies of target contracts_project
#0 25.03 [ 11%] Creating directories for 'contracts_project'
#0 25.09 [ 22%] No download step for 'contracts_project'
#0 25.11 [ 33%] No update step for 'contracts_project'
#0 25.11 [ 44%] No patch step for 'contracts_project'
#0 25.13 [ 55%] Performing configure step for 'contracts_project'
#0 25.14 -- Setting up CDT Wasm Toolchain 4.0.0 at /usr
#0 25.14 -- Setting up CDT Wasm Toolchain 4.0.0 at /usr
#0 25.19 -- The C compiler identification is Clang 9.0.1
#0 25.25 -- The CXX compiler identification is Clang 9.0.1
#0 25.26 -- Detecting C compiler ABI info
#0 25.30 -- Detecting C compiler ABI info - failed
#0 25.30 -- Detecting C compile features
#0 25.30 -- Detecting C compile features - done
#0 25.31 -- Detecting CXX compiler ABI info
#0 25.35 -- Detecting CXX compiler ABI info - failed
#0 25.35 -- Detecting CXX compile features
#0 25.36 -- Detecting CXX compile features - done
#0 25.36 CMake Error at CMakeLists.txt:29 (message):
#0 25.36   Found CDT version 4.0.0 but it does not satisfy version requirements:
#0 25.36   version '4.0.0' must have the same major version as the soft maximum
#0 25.36   version (3)
#0 25.36 
#0 25.36   Please use CDT version 3.0.x
#0 25.36 
#0 25.36 
#0 25.36 -- Configuring incomplete, errors occurred!
#0 25.36 See also "/app/reference-contracts/build/contracts/CMakeFiles/CMakeOutput.log".
#0 25.36 See also "/app/reference-contracts/build/contracts/CMakeFiles/CMakeError.log".

eosio_system_powerup_tests/rent_tests is flaky

#101 fixes eosio_system_powerup_tests/weight_tests under Savanna; it works in any initial block.

eosio_system_powerup_tests/rent_tests works only when head block time is on the second. This requires further investigation.

Port inline multisig changes from eosio.contracts

These changes (EOSIO/eosio.contracts@v1.8.3...9895b08) were lost in the transition from eosio.contracts to mandel-contracts, which then was carried forward into eos-system-contracts and reference-contracts.

We want to capture that functionality in the main branch of reference-contracts.

Some of the changes may only be there to workaround CDT issues that are already fixed. If there are simplifications in the code possible while maintaining the same behavior in the modified eosio.msig contract by assuming CDT v3.0.0 or later can be used, then go ahead and make those simplifications.

In addition, make sure that the eosio.wrap contract also uses inline actions instead of deferred transactions.

Remove dependence on deferred transactions in reference contracts

After #7 is complete, only the core contract should have deferred transactions used in a couple of places (unstaking refund and name bid refund). But already have ways to claim the refunds in case the deferred transactions fail. So removing the deferred transaction dependency in the core contract can be as simple as removing the lines that schedule the redundant deferred transaction.

Note however this will have the impact of always requires users to take another explicit action (which requires signing a new transaction) to actually claim the refund whereas now the process does usually happen automatically. To make this process less burdensome, we may wish to explore changes to make it possible for anyone to automate the refund claiming on behalf of the user. This may simply involving adjusting the authorization required for the refund action so that anyone can claim a refund on behalf of a user rather than only the user who is owed the refund. However, due to the user impact of this change, we may still wish to further consider the approach we take here before removing the deferred transaction support in the core contract.

Add IBC contract

This is the IBC contract that supports IBC with the new Savanna consensus. It should still be able to do action proofs for blocks prior to the Savanna transition.

Actually create new repo for this in eos-system-contracts.

eosio_system_powerup_tests/weight_tests and eosio_system_powerup_tests/rent_tests fail under default Savanna libtester

error 2024-05-28T13:13:17.288 unit_test eosio.powerup_tests.cp:250    near   ] near: 
99999988425913 100000000000000 
tests/eosio.powerup_tests.cpp(408): fatal error: in "eosio_system_powerup_tests/weight_tests":
 critical check near(get_state().net.weight_ratio, net, 1) has failed

tests/eosio.powerup_tests.cpp(237): fatal error: in "eosio_system_powerup_tests/rent_tests": critical check before_payer.liquid - after_payer.liquid == expected_fee has failed [40000.0000 TST != 40000.0001 TST]

Troubleshoot potential REX fix bug

There are reports in telegram and internally that the REX fix bug we believed to have resolved with the 3.1 release has an issue.

Original report of issue: https://t.me/Mandel_LaunchGroup/1346

Context from release notes:
"This release includes a backport of EOSIO/eosio.system#54 (originally authored by @deckb) which works around the REX rounding bug that stopped accounts from selling REX.

Accounts may now use the voteupdate action to restore their account.

In addition, the bug has been fixed so it does not impact more accounts in the future."

We need to:

• Verify whether we can unlock funds from REX with voteupdate
• Recommend whether we need DevRel to incorporate more thorough documentation for this process

Split system_tests suite

eosio.system_tests suite contains a large number of tests. They cause Spring CICD libtester test to fail from time to time: AntelopeIO/spring#254. Split the suite into smaller suites such that CICD can finish in time.

Fix reference contracts CICD

See eosnetworkfoundation/eos-system-contracts#25

Removed Deferred Transaction Support from System Contract

Remove need_deferred_trx from system contract contracts/eosio.system/src. Along with updates to delegate_bandwidth.cpp and name_bidding.cpp. Update comments in contracts/eosio.bios/include/eosio.bios.hpp header file clarifying deferred are not always used.

Bump version to v3.3.0-dev

update main to next version

Update action return value struct for `sellram` & `buyram`

Update action return value struct:

• action_return_sellram: bytes => bytes_sold
• action_return_buyram: bytes => bytes_purchased

sellram

struct action_return_sellram {
      name account;
      asset quantity;
      int64_t bytes_sold;
      int64_t ram_bytes;
}

buyram

struct action_return_buyram {
      name payer;
      name receiver;
      asset quantity;
      int64_t bytes_purchased;
      int64_t ram_bytes;
};

Add core contract actions to support Instant Finality

Depends on AntelopeIO/cdt#215, AntelopeIO/cdt#210, and AntelopeIO/leap#1525.

Contract Actions

Switchover: Action to permanently transition to HotStuff consensus.

• Require the authority of the contract itself
• Set a flag altering the behavior of the update_elected_producers function
• Establish a new finalizer set (introduced by the Instant Finality protocol feature)
• Abort if an insufficient number of the top 21 block producers have registered a BLS finalizer key

Register Finalizer Key: Action to register a finalizer key.

• Registered BPs Only: must be a registered block producer
• Multiple Registered Finalizer Keys: A registered block producer can have multiple registered finalizer keys.
• Proof of Possession: The finalizer key to register must be accompanied by a valid Proof of Possession signature.
• Activate on First Key: If this is the first registered finalizer key of the block producer, it will also implicitly be marked active.
• Reject Duplicate Finalizer Keys: If this finalizer key was registered before (and still exists) even by other block producers, reject the registration.

Activate Finalizer Key: Action to mark a finalizer key as active.

• Registered Finalizer Keys Only: must be a registered finalizer key.
• Registered BPs Only: account must be a registered block producer.
• Only One Active Finalizer Key: A block producer may only have one active finalizer key.
• Deactivates Previously Active Finalizer Key: Activating a finalizer key of a block producer implicitly deactivates the previously active finalizer key of that block producer.
• Immediately Change Finalizer Policy: If the block producer is currently active (in top 21), then immediately call set_finalizers with the new policy after activating the finalizer key. Otherwise, wait until the periodic check that sets the proposers and finalizers.

Delete Finalizer Key: A registered block producer can delete a registered finalizer key that is not marked as active.

• Prevent Deletion of Active Key: A registered block producer should not be able to delete a registered finalizer key that is marked as active unless it was the last registered finalizer key of that block producer.

Other Requirements:

Equivalence of Proposers and Finalizers: The contract must ensure that the set of proposers selected is always the same as the set of finalizers selected.

BLS Public Key Handling: Contract actions handle BLS public keys as text-encoded strings.

• Proof of Possession: To guard against rogue key attacks, the contract must validate possession of BLS private keys corresponding to asserted BLS public keys by verifying a signature on the asserted BLS public key.
• Actions to register, activate, or delete finalizer keys must take strings of the text-encoded (base64url) BLS public keys.
• The text-encoding of the BLS public key should also be captured in the table entry (alongside the decoded binary) so that they can be conveniently displayed in block explorers.

Selective Key Aggregation: To prevent duplicate keys and maintain integrity of BLS Key Aggregation, the contract must only include keys associated with top-ranked block producers by testing the following criteria:

• The BP must have an active BLS finalizer key registered.
• The active BLS finalizer key associated with the BP must not have already been included by another higher-ranking BP in the set.

Establish first finalizer policy: During the switchover process, the contract should utilize a host function introduced by the Instant Finality protocol feature in Leap to establish a new finalizer policy.

Ongoing Consensus: After the switchover to the new Savanna consensus algorithm, the contract must:

• ensure uninterrupted creation of new blocks using the existing set_proposed_producers mechanism to establish the block proposer schedule.
• guarantee that finalizer keys are correctly handled and maintained under the new consensus algorithm by relying on the newly introduced Instant Finality (IF) host function to manage the finalizer policy in the update_elected_producers function: a finalizer policy should only be proposed if it is different than the last proposed one which should be tracked in the contract.

Original Issue

The core contract needs changes to allow block producers to register block finalizer keys. New action(s) should allow the BP to modify the set of candidate block finalizer keys associated to their BP from which they can mark one as active using another new action. The separate action to mark one from the set as active allows the BP to configure permissions so that they can have a dedicated key that can also change which one is active and include that as part of their failover scripts; this key would be able to only choose between the pre-approved finalizer keys rather than setting new ones or changing other parameters related to the BP. The BLS public keys are specified as string of the text encoded version of the BLS public key.

When adding new BLS public keys, the new public keys must be accompanied by a "proof that the corresponding private key is known by someone" (aka "proof of possession") which must be validated (can simply be a signature on the hash of some message we agree on, e.g. the public key itself). This is the protect against rogue key attacks. There is no need for replay protections of the proof.

When aggregrating the active finalizer keys from the top ranked BPs, the contract should skip over any BP that doesn't meet the conditions until it gets a sufficient number of them (21 on EOS). These conditions include: must have an active BLS finalizer key registered; and, that key must not have already been included by another higher ranking BP that was included into the set.

The core contract should also have a mechanism that allows the active authority of the core contract to permanently switchover to using the new HotStuff consensus algorithm, e.g. an action require authority of get_self() which sets a flag that changes the behavior of the logic in the update_elected_producers. The switchover occurs by calling the host function (introduced by the Instant Finality protocol feature in Leap) which sets a new finalizer set. The action could check that enough of the top 21 producers have registered a BLS finalizer key and abort otherwise.

After switchover has occurred, the update_elected_producers function will continue to use set_proposed_producers to set the block proposer schedule as well as using the new IF host function to set the finalizer set.

Invalid Signature Unable to Download Spring

Run AntelopeIO/asset-artifact-download-action@v3
with:
owner: AntelopeIO
repo: spring
file: spring-dev.*ubuntu22.04_amd64.deb
target: main
prereleases: false
artifact-name: spring-dev-ubuntu22-amd64
container-package: experimental-binaries
token: ***
fail-on-missing-target: true
wait-for-exact-target: false
Downloaded spring-dev_1.0.0-dev-ubuntu22.04_amd64.deb from e3da612c0c5efcc2e213c3501fdd08d6110324da artifact spring-dev-ubuntu22-amd64
Error: invalid signature: 0x1da06171

Split eosio.system_tests.cpp so tests can run in parallel in CICD to reduce overall CICD time

Currently eosio.system_tests.cpp is 5,921 lines long and takes 5 minutes to run in CICD libtester (https://github.com/AntelopeIO/spring/actions/runs/9468157289/job/26085190747#step:16:984). The next longest test is eosio_system_finalizer_key_unit_test which is about 1 minute. We can split eosio.system_tests.cpp into multiple files (tests) and make each of them run around 1 minute; those tests can run in parallel with other tests. This will reduce libtester running time to about 1 minute, a huge saving without risks, plus smaller files to reduce compilation time if changes are in one small file.

`eosio_system_tests/producer_onblock_check` fails under default `Savanna` libtester

tests/eosio.system_tests.cpp(2943): fatal error: in "eosio_system_tests/producer_onblock_check": critical check true == all_21_produced has failed [true != false]

The test is flaky? If producing 21 more blocks, the test passed:

reference-contracts/tests/eosio.system_tests.cpp

Lines 2889 to 2891 in cd645b5

	// give a chance for everyone to produce blocks
	{
	produce_blocks(21 * 12);

Version Bump for Reference Contracts

Bump Version to 3.4.0-dev to match system contracts.

Order of install contracts

trouble with install eosio.system

cleos     main.cpp:700                  print_result         ] soft_except->to_detail_string(): 3070003 
wasm_serialization_error: Serialization Error Processing WASM
env.set_parameters_packed unresolveable
    {"module":"env","fn":"set_parameters_packed"}
    nodeos  eos-vm.cpp:77 validate
pending console output:
    {"console":""}
    nodeos  apply_context.cpp:124 exec_one

notning exactly docs with it.

Update bios contract setfinalizer action to take proof of possessions

Building upon #26, the setfinalizer action should be modified (or alternatively a new one added?) that takes the BLS finalizer keys each with a proof of possession. For details of proof of possession (and an implementation to validate these), see: #24.

Update Leap Check Versions

Update the CMake File with expect versions of Leap. Soft max should be 6.0 for next release.

reference-contracts/tests/CMakeLists.txt

Lines 3 to 4 in 732fa98

	set(EOSIO_VERSION_MIN "3.1")
	set(EOSIO_VERSION_SOFT_MAX "5.0")

Able to Delete All Finalizer Keys From Tables

Able to delete all finalizer keys. The finkeys and finalizers tables are empty

• Finalizer Policy doesn't change.
• LIB continues to advance.
• Able to stop / restart

delete_all_keys_command_line.txt

Test: Too high of tolerance

Many tests have too high of a tolerance:

reference-contracts/tests/eosio.system_tests.cpp

Line 1013 in cd645b5

BOOST_FIXTURE_TEST_CASE( vote_for_producer, eosio_system_tester, * boost::unit_test::tolerance(1e+5) ) try {

I'm assuming the test author meant 1e-5 not 1e+5.
All the tests that use a tolerance should be inspected and fixed.

IF Prototype Implementation in Reference Contracts

Tasks

Beta Give feedback

No tasks being tracked yet.

Test coverage for `ram_action` return values

Write an example unit test for ramtransfer find the return data and passes back the expected data structure. This is used for testing the returned values in unit testing.