Gravity Dev Net: Integration Tests Framework
In continuation of the series of announcements about Gravity’s developer network launch, we are presenting an integration test framework that supports a quick and easy integration of a new target chain.
As mentioned in the article about the Gravity demo launch, the protocol’s devnet version is coming out in September, designed for public testing of upcoming Gravity updates and maintaining compatibility for synchronizing with regularly updated integrated networks.
Previously, we presented SuSy, a cross-chain gateway for tokens. Today, we unveil a framework for integration tests to enable quick target chain integration into the Gravity network. The next article in the series will describe images for launching a node on a one-click-deployment cloud platform or on any custom cloud provider.
In this announcement, we will explore the framework for integration tests, the flow for adding new target chains that we offer to open source Gravity developers.
Key terms
The integration framework published today is focused on testing different aspects of the functionality of SuSy, a blockchain-agnostic cross-chain asset transfer gateway protocol based on Gravity. As a reliable foundation for gateways, Gravity allows them to remain trustless and decentralized. A crucial functionality required for cross-chain communication is the most basic procedure: cross-chain asset swaps.
Let us start by introducing key terminology that we will use to explain Gravity, SuSy and their interaction:
ORIGIN-CHAIN: a blockchain network from which a transfer originates. That is, in this network, tokens are locked and unlocked.
DESTINATION-CHAIN: a blockchain to which transfers are made from the ORIGIN-CHAIN. Issuance and burning of wrapped tokens take place on this network.
IB-PORT is a smart contract in DESTINATION-CHAIN that implements the functionality of issuance and burning of the wrapped token.
LU-PORT is a smart contract in ORIGIN-CHAIN that locks and unlocks the original token.
NEBULA-SC is one of the main architectural units of the Gravity protocol, a smart contract that accepts and verifies data from Gravity oracles. It implements checks of data relevance (blockchain height), availability of appropriate cryptographic signatures and threshold signature rules for transmitted data.
USER-SC is one of the main architectural units of the Gravity protocol. It is a smart contract that accepts data verified in NEBULA-SC and produces an action that is part of a custom application. In the case of SuSy, LU-PORT and IB-PORT are examples of USER-SC.
PULSE-TX is a transaction that will transfer hash from data to NEBULA-SC with necessary signatures for verification and registration.
SEND-DATA-TX is a transaction that transfers data verified and registered in NEBULA-SC to USER-SC.
Integration Tests Framework
The integration tests framework is designed for the purpose of writing and testing integrations of new Gravity target chains, where the data is supplied to by the Gravity network. It simplifies making modifications to the logic of USER-SC or the rules in NEBULA-SC without the need to deploy and update a full custom Gravity network. The framework helps to solve the task of initial configuration and functionality of Gravity nodes not directly related to target chains.
The standard development flow for integrating a new target chain consists of four steps:
- Implement SYSTEM-SC and NEBULA-SC contracts on a specific blockchain;
- Create an identical set of integration tests for testing the contracts on the blockchain;
- Run the integration tests to verify that the contracts are implemented properly;
- Add an integration of the target chain into a Gravity Core interface IBlockchainAdaptor.
The framework presented today can greatly facilitate the 2d and the 3d steps of target chain integration. The core underlying principle of any integration test implemented within Gravity is as follows:
In order to test a specific functionality, which may be, for instance, a part of the logic of NEBULA-SC in the Ethereum blockchain that implements data verification, one would need to deploy an Ethereum node, deploy contracts, mock a needed state, and call several verification operations, expecting a definite, well-specified answer at the end of the test.
If the test is successful, then all stages of the implemented integration, starting from the logic that implements reading from the blockchain (extraction) and ending with on-chain data verification, should be deemed successful too. A code that has been debugged using the framework can be reused to integrate a specific target chain and its smart contracts into the main Gravity network.
In this article, we will look at working with the integration testing framework, using SuSy-based cross-chain transfers as an example.
SuSy Gateway Recap
For starters, let’s see how a cross-chain transfer algorithm for a token can work in SuSy, using a transfer from ORIGIN-CHAIN to DESTINATION-CHAIN as an example, where a token (T) will be issued as a wrapped token (swT) and sent to recipient R in DESTINATION-CHAIN.
As shown above, a sender (S) interacts with the LU-PORT (Lock-Unlock) smart contract by transferring an amount (A) of the T token to it and specifying the recipient’s public address in DESTINATION-CHAIN. The gateway smart contract automatically creates a unique SWAP-ID and sets the registered status. The received funds are blocked on the LU-PORT smart contract.
Information about this event is registered by extractors, the Gravity network’s service that processes received data and communicates it to Gravity. From the Gravity framework, the oracle moves hashed data about the new SWAP-ID and directions to the verification contract (NEBULA-SC), in which the signatures of the Gravity network validators and the legitimacy of the transferred context are checked.
Upon verification, the SEND-DATA-TX transaction is called, containing a set of data and instructions for issuing and sending tokens to the recipient (R).
Likewise, data about this event is handled by Gravity network oracles, and, contingent upon successful execution, the “processed” status is set. After reaching a certain number of blocks at which the likelihood of a fork is minimal, it may be necessary to set the finalized status.
In the opposite direction, for transferring the swT token from DESTINATION CHAIN to ORIGIN CHAIN and unlocking T on the LU PORT contract, the procedure is similar. The only difference is in the final transactions, that is, burning the swT token on IB PORT and unlocking the T token on LU PORT, are reversed.
For a deeper overview of key SuSy concepts, refer to the SuSy whitepaper.
Overview of the integration framework
The integration-tests repository contains verifications of various functions of the SuSy gateway described above, in particular covering the functionality of the IB and LU ports, which are examples of USER-SC. The tests for the contracts are written in Golang using a general-purpose library called testing. In the main test code, functions are declared for creating connections to the Ethereum node, reading configs, and deploying contracts. Check out the Readme within the repository to find how to run the tests. Below are some examples of the implemented testing functions:
One of the most important functions for checking the logic of oracles in a target chain that is being implemented is signData:
func signData (dataHash [32]byte, validSignsCount int, isReverse bool) (* big.Int)
It collects signatures and allows for signing a hashed version of the data transmitted into a NEBULA-SC.
As a convention, all further test suites that cover various aspects of the functionality begin with the word Test.
For instance, the TestPulseInCorrect2 function checks that at least ⅔ signatures are present, which is necessary to validate the passed value.
Summing up, this article presented an overview of the integration test framework that allows for implementing and testing Gravity contracts on a new target chain. We believe that this framework can facilitate the development experience for external collaborators, ensuring a faster expansion of the Gravity ecosystem. In the upcoming articles about Gravity Dev Net, we will take a closer look at the practical aspects of working with integration tests when connecting a new target chain, as well as the flow integration into a working Gravity network.
For more information, you can read the Gravity Whitepaper, visit the Gravity website, join the community on Twitter or Telegram or contact press@gravity.tech
