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:
However, the Antelope protocol itself does not immediately provide:
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:
eosio
account.)eosio
account.)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):
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.
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.
The build guide below will assume you are running Ubuntu 20.04. However, as mentioned above, other operating systems may also be supported.
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.
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.
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.
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
Assuming you built with BUILD_TESTS=ON
, you can run the tests.
cd build/tests
ctest -j $(nproc)