x/pools

Abstract

The following document specifies the pools module.

This module contains the logic responsible for managing the restaking pools of our protocol. The pools are used to track the amount of tokens that each user has decided to restaking and use to provide security to multiple services.

Pools are only created by other modules, and cannot be created by outside users. The only operation that users can perform are querying the existing pools and their details.

Contents

• Concepts

  • Pool

• State

  • Next Pool ID

  • Pools

  • Pool addresses

Concepts

Pool

A pool is used to track the amount of tokens that each user has decided to restake. Each pool can only manage a single denomination of tokens (i.e. multi-tokens pools are not allowed). At the same time, for each token denomination, a single pool can exist at any given moment.

For easier reference throughout the codebase, each pool is uniquely identified by an ID that is automatically assigned when the pool is created.

A pool also has a unique address that is derived from the pool ID itself. The address is used to store the tokens that are delegated to the pool, while inside the pool object itself shares are tracked.

// Pool defines the structure of a restaking pool
message Pool {
  // ID is the auto-generated unique identifier for the pool
  uint32 id = 1 [(gogoproto.customname) = "ID"];

  // Denom represents the denomination of the tokens that are staked in the pool
  string denom = 2;

  // Address represents the address of the account that is associated with this
  // pool. This will be used to store tokens that users delegate to this pool.
  string address = 3 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // Tokens define the delegated tokens.
  string tokens = 4 [
    (cosmos_proto.scalar) = "cosmos.Int",
    (gogoproto.customtype) = "cosmossdk.io/math.Int",
    (gogoproto.nullable) = false
  ];

  // DelegatorShares defines total shares issued to a pool's delegators.
  string delegator_shares = 5 [
    (cosmos_proto.scalar) = "cosmos.Dec",
    (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec",
    (gogoproto.nullable) = false
  ];
}

State

Next Pool ID

The pools module stores the next pool ID in state with the key 0xa1.

• Next pool ID: 0xa1 -> uint32

Pools

The pools module stores the pools in state with the prefix of 0xa2.

• Pool: 0xa2 | PoolID -> ProtocolBuffer(Pool)

Pool addresses

In order to know more easily and faster if a particular address represents a pool, we store the set of pool addresses using the 0xa3 prefix.

• Pool address: 0xa3 | PoolAddress -> []byte{}