DOCSEARCHbyAlgolia
Submit Docs

Alliance Documentation

website·Indexed 32 days ago

https://docs.alliance.money

An open-source Cosmos SDK module that leverages interchain staking to form economic alliances among blockchains. The documentation covers integration guides, staking mechanisms, reward distribution, and technical specifications including state transitions, data structures, and module parameters.

Tokens
9.1K
Snippets
29
Records
70
Agent score
53%

What's inside Alliance

  1. Overview of the Alliance module for Cosmos SDK

    Alliance is an open-source Cosmos SDK module that enables multiple assets (not just the native staking asset) to be staked on a blockchain. It wraps around a chain's native staking module, allowing whitelisted assets—including IBC assets and Liquid Staking Derivatives (LSTs)—to be staked, unstaked, or redelegated to validators. This creates economic alliances where assets from one chain can provide security and stability to another, diversifying yield opportunities for users.

  2. Overview of the Alliance Cosmos SDK module

    Alliance is an open-source Cosmos SDK module designed to form economic alliances between blockchains using interchain staking. It allows chains to create bilateral, mutually beneficial relationships by allowing users to stake specific assets (Alliance assets) on a chain to earn rewards, while a portion of those assets can be redistributed to the chain's native token stakers.

  3. Understand the Alliance Cosmos SDK module

    Alliance is an open-source Cosmos SDK module that enables interchain staking to form economic alliances between blockchains. Its goal is to increase economic activity across Cosmos chains through bilateral, mutually beneficial alliances, fostering cross-chain collaboration and user adoption.

  4. Understand the Alliance module EndBlocker tasks

    The Alliance module utilizes an EndBlocker that executes specific maintenance tasks at the end of every block to ensure state consistency and reward distribution. These tasks include:

    • Completing redelegations by processing the redelegations queue.
    • Completing undelegations by processing the undelegations queue.
    • Redistributing rewards based on the current block time.
    • Rebalancing bonded tokens if an AssetRebalanceQueueKey event was produced during the block.

  5. Query Alliance module state and delegations

    Use the following CLI queries to retrieve information about Alliances, delegations, and rewards.
    # Query a specific Alliance by denom
alliance denom <denom>

# Query paginated Alliances
alliances

# Query a specific delegation
delegation <delegator-addr> <validator-addr> <denom>

# Query all paginated delegations for a delegator
delegations-by-delegator <delegator-addr>

# Query all paginated delegations for a delegator and validator
delegations-by-delegator-and-validator <delegator-addr> <validator-addr>

# Query rewards for a specific Alliance
rewards <delegator-addr> <validator-addr> <denom>

# Query module parameters
params

  6. Understand how delegation shares calculate coin balances

    To avoid the high cost of updating every individual account balance during slashing or take-rate deductions, the system uses 'shares' to track assets as proportions of a whole. Instead of tracking individual coin balances, the system tracks shares. When coins are deducted (e.g., via a take rate), only the Asset.TotalTokens is updated, and all shares proportionally claim a smaller pool of coins.

    When a validator is slashed, their shares are reduced, which proportionally distributes the slashed coins to other non-offending validators.

  7. Staking Alliance assets via the x/alliance module

    Staking Alliance assets is designed to be seamless for users (supporting stake, unstake, and redelegate), but it operates differently under the hood to maintain compatibility with Cosmos-SDK chains:

    1. Alliance assets are not staked directly to validators.
    2. The x/alliance module tracks Alliance staking accounts and mints/burns a proportional amount of native tokens.
    3. These native tokens are then staked to validators on behalf of the delegator.
    4. The Alliance module account remains the technical owner of these minted native tokens.

  8. Create an Alliance via governance proposal

    Alliances are created through governance proposals using the /alliance.alliance.MsgCreateAllianceProposal type. An Alliance allows specific native tokens (recognized by the bank module and whitelisted) to be staked. This includes native tokens and CW-20 tokens sent via IBC that have been minted as native tokens.

    Key parameters for an Alliance include:

    • denom: The address of the Alliance asset to be whitelisted.
    • rewards-weight: The ratio of reward power given to the asset (native assets default to 1).
    • rewards-weight-min: The minimum possible RewardWeight.
    • rewards-weight-max: The maximum possible RewardWeight.
    • take-rate: The rate at which the asset is redistributed to all stakers as rewards (used for liquid staking derivatives).
    • reward-change-rate: The rate at which reward weight is scaled every interval.
    • reward-change-interval: The interval at which the reward-change-rate is applied.
    allianced tx gov submit-legacy-proposal create-alliance denom rewards-weight rewards-weight-min rewards-weight-max take-rate reward-change-rate reward-change-interval \
  --from <name_or_address> \
  --deposit <amount> \
  --description "<description>" \
  --title "<title>"

  9. Perform a redelegation in the Alliance module

    Redelegations transfer stake from a source validator to a destination validator. The process involves:

    1. Verifying the asset and the existing delegation.
    2. Claiming rewards from both the source and destination validators to update values.
    3. Calculating the number of delegation shares to be redelegated.
    4. Iterating over redelegations to prevent transitive redelegations.
    5. Removing coins and shares from the source validator and adding them to the destination validator.
    6. Queuing the redelegation for execution based on the unbonding time.
    7. Queuing the rebalance assets event.

  10. Add Alliance assets via governance

    To add a new asset as a stakable Alliance asset, the module must first be integrated via a software upgrade proposal. Once integrated, an Alliance proposal must be submitted to governance containing the following parameters:

    • Denomination: The specific identifier of the asset to be added.
    • Reward Weight: The proportion of total chain staking rewards directed to stakers of this asset.
    • Take Rate: An optional annualized tax that redistributes a percentage of the Alliance asset to all stakers.

  11. Install and start Alliance testnet core

    Download and execute the join-testnet.sh script to set up the core service. Use the -c flag to specify the target Chain ID (e.g., ordos-1).
    # Download and set permissions
curl -sSL https://raw.githubusercontent.com/terra-money/alliance/feat/wasm-testnets/scripts/join-testnet.sh -O
chmod 755 ./join-testnet.sh

# Start the service in a tmux session
tmux a
./join-testnet.sh -c ordos-1

  12. Bootstrap Alliance-enabled chains via genesis file

    To bootstrap an Alliance-enabled chain, add Alliance assets to the assets list within the Alliance property of the genesis file. The Alliance module supports any native token recognized by the bank module (provided it is whitelisted) and CW-20 tokens sent via IBC that have been minted as native tokens.