README.md

🤝 Alliance

Technical Documentation · Integration Guide · Code Audit

Overview

Alliance is an open-source Cosmos SDK module that leverages interchain staking to form economic alliances among blockchains. By boosting the economic activity across Cosmos chains through creating bilateral, mutually beneficial alliances, Alliance aims to give rise to a new wave of innovation, user adoption, and cross-chain collaboration.

Alliance allows blockchains to trade yield with each other- think of it like yield farming for L1s.

Here’s how it works:

• Two chains integrate the Alliance module and decide through governance which assets can be staked on their chain. These are known as Alliance assets.
• Each Alliance asset is assigned a Take Rate (the percentage of staked Alliance assets the chain redistributes to native chain stakers) and a Reward Weight (the percentage of native staking rewards the chain distributes to Alliance asset stakers).
• Users of each chain can then bridge their assets via IBC to the other chain and stake them to earn the Reward Weight.

Tech Specs

The Alliance Docs contain detailed information about Alliance. Familiarize yourself with the following concepts before integrating the Alliance module.

• About Alliance
  • Overview
  • How Alliance works
  • Alliance staking
  • Reward distribution
  • Validator shares
• Guides
  • Integrate the Alliance module
  • Create, update, or delete an Alliance
  • Interact with an Alliance
• Technical specifications:
  • Module parameters and Alliance asset properties
  • Txs and queries
  • Data structures
  • State transitions
  • Invariants
  • Benchmarks

Integrate the x/alliance module

The Alliance module can be added to any compatible Cosmos chain and does not require any changes to consensus or major changes to common core modules. This module wraps around a chain’s native staking module, allowing whitelisted assets to be staked and earn rewards. Alliance assets can be staked with the Alliance module, and the chain's native staking module is used for native stakers.

Chains that want to add x/alliance must enable the following modules:

• x/auth
• x/bank
• x/ibc
• x/staking
• x/distribution
• x/gov

Compatibility matrix:

Release	Branch	CosmosSDK
v0.4.0	release/v0.4.x	0.50
v0.3.0	release/v0.3.x	0.47
v0.2.0	release/v0.2.x	0.47
v0.1.0	release/v0.1.x	0.46

For an in-depth guide on integrating x/alliance, visit the Alliance Module Integration Guide.

Development environment

The following sections are for developers working on the x/alliance module.

This project uses Go v1.21.

To build a ready-to-use binary, run the following:

make install

Localnet

The Localnet is a development environment that uses a Docker orchestration to create a local network with 3 Docker containers:

• make localnet-start : stop the testnet if running, build the terra-money/localnet-alliance image and start the nodes.
• make localnet-alliance-rmi: remove the previously created terra-money/localnet-alliance image.
• make localnet-build-env: delete and rebuild the terra-money/localnet-alliance
• make localnet-build-nodes: using the terra-money/localnet-alliance starts a 3 docker containers testnet.
• make localnet-stop: stop the testnet if running.

Running the simulation

The simulation app does not run out of the box because the Alliance module owns all the native stake. The x/staking module's operation.go file panics when a delegator does not have a private key.

Use the following command to update the x/staking module directly before compiling the simulation app.

go mod vendor
sed -i '' 's/fmt.Errorf("delegation addr: %s does not exist in simulation accounts", delAddr)/nil/g' vendor/github.com/cosmos/cosmos-sdk/x/staking/simulation/operations.go
go test -benchmem -run=^$ -bench ^BenchmarkSimulation ./app -NumBlocks=200 -BlockSize 50 -Commit=true -Verbose=true -Enabled=true

Warning

Please note that Alliance is still undergoing final testing before its official release. TFL does not give any warranties, whether express or implied, as to the suitability or usability of the software or any of its content.

TFL will not be liable for any loss, whether such loss is direct, indirect, special or consequential, suffered by any party as a result of their use of the software or content.

Should you encounter any bugs, glitches, lack of functionality or other problems on the website, please submit bugs and feature requests through Github Issues.