cfeclaim

package
v1.4.0-rc1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 12, 2024 License: Apache-2.0 Imports: 20 Imported by: 0

README

Chain4Energy claiming module - cfeclaim

Abstract

Chain4Energy claiming module provides the functionality of creating campaigns, adding missions, and claiming tokens based on pre-set conditions. It emphasizes the importance of transparency and accountability in the token distribution process, aligning with mission-driven campaigns.

Contents

  1. Concept
  2. Messages
  3. Events
  4. Queries
  5. Invariants
  6. Genesis validations

Concepts

Campaign

Each campaign is a structured initiative with a specific goal or target. A campaign can house multiple missions and will have tokens allotted, which can be claimed upon the completion of those missions. Each campaign has a specific timeline, a beginning and an end, within which missions can be added and tokens can be claimed.

Campaigns have the following parameters:

  • owner - Address of the campaign creator.
  • name - Name of the campaign.
  • description - A brief overview of the campaign.
  • campaign_type - Type or category of the campaign.
    • VESTING_POOL - Campaign that is created from a vesting pool.
    • DEFAULT - Campaign that is created from an account balance.
  • removable_claim_records - Indicates if claim records can be removed after start time of a campaign.
  • feegrant_amount - Amount designated for fee grants.
  • initial_claim_free_amount - The number of tokens to be released immediately (regardless of the lockup and vesting period) in the case of an initial claim.
  • free - Percentage of tokens to be released during mission claim (regardless of lockup and vesting period).
  • start_time - Timestamp for the start time of the campaign.
  • end_time - Timestamp for the end time of the campaign.
  • lockup_period - Duration of time during which tokens cannot be withdrawn.
  • vesting_period - Duration of vesting period for tokens.
  • vesting_pool_name - Name of the vesting pool associated with the campaign (only when campaign is of VESTING_POOL type).
Mission

A mission is a specific task or objective within a campaign. Upon completion of a mission, users can claim tokens. Each mission also has a percentage weight field that indicates how many tokens out of the total amount of tokens assigned to a given user the user will get for this mission. Example - the user is assigned 100 tokens, the weight of the mission is 0.4, so the user for completing and claiming this mission will get 40 tokens.

Missions have the following parameters:

  • id - Identifier of the mission.
  • campaign_id - ID of the campaign under which the mission resides.
  • name - Name of the mission.
  • description - Brief about the mission.
  • mission_type - Type or category of the mission.
  • weight - Mission weight percentage. This is the percentage of tokens that will be sent to the user at the time of claiming the mission.
  • claim_start_date - Timestamp for the date from which claims can be initiated for this mission.

Currently, we distinguish following types of missions:

  • INITIAL_CLAIM - required mission added at the beginning of the campaign along with adding the campaign.
  • DELEGATE - require the user to delegate tokens before claiming these missions
  • VOTE - require the user to vote on the proposal before claiming these missions
  • CLAIM - the user can immediately redeem it without any additional actions
User Entry

Every user in the ecosystem is identified by an entry. This entry holds information related to the user's claims and the records associated with those claims.

User Entries have the following parameters:

  • address - User blockchain address.
  • claim_records - List of all claim records associated with the user. Each record holds information about a specific campaign assigned to user.
Claim Record

Claim record stores information about the user assigned to a given campaign (including the number of tokens assigned to him, ids of completed and claimed missions)

Claim Records have the following parameters:

  • campaign_id - Identifier for the campaign related to this claim record.
  • address - User address to which the claimed tokens will be sent.
  • amount - The amount of tokens assigned to the user for the entire campaign
  • completed_missions - List of mission IDs that the user has completed.
  • claimed_missions - List of mission IDs for which the user has made a claim.
Claim Record Entry

While similar to a Claim Record, a Claim Record Entry contains more granular information about the claim related to a specific campaign. It is used while adding a new claim record.

Claim Record Entries have the following parameters:

  • campaign_id - Identifier for the campaign related to this claim entry.
  • user_entry_address - The address of the user associated with this claim entry.
  • amount - The amount of tokens assigned to the user for the entire campaign
Fee granting

Feegrant is a special option in a campaign that allows for the first use of an initial claim for each user of that campaign. This option was created so that users who did not have a blockchain account and therefore, did not have tokens to cover transaction fees, could perform the first mission (initial claim) of the campaign. Feegrant takes on a specific value. If feegrant is set to a value greater than zero in a given campaign, when adding each user entry, it is checked whether the user who adds the user entries is also able to cover this feegrant. To prevent situations in which the founder of a campaign does not have enough tokens in their account to pay for feegrant for another user, an additional, special module account is created, which stores tokens to pay for feegrant. If a user correctly uses initial claim (transaction is successful), feegrant is revoked. Tokens that were not used by users are treated in the same way as campaign’s leftovers during the closure of the campaign.

Vesting pool reservation mechanism

Function of the mechanism is to allow vesting pool owners to reserve vesting pool tokens for other module functionality. In case of a claim module, tokens are reserved for claiming purposes. The mechanism will not expose blockchain messages API, it is an internal mechanism only.

Each reservation has its unique id within one vesting pool. Reservation can be increased and decreased by the owner:

  • increased by adding reservation with the same id
  • decreased by dedicated method

In the case of the claim module, when user entry of vesting pool campaign is added reservation is increased, when removed decreased.

Messages

Create Campaign

Create a new campaign with a set of specified parameters.

The MsgCreateCampaign can be submitted by any valid account to initiate the creation of a new campaign using the given parameters.

Structure
type MsgCreateCampaign struct {
Owner                  string
Name                   string
Description            string
CampaignType           types.CampaignType
RemovableClaimRecords  bool
FeegrantAmount         math.Int
InitialClaimFreeAmount math.Int
Free                   sdk.Dec
StartTime              time.Time
EndTime                time.Time
LockupPeriod           time.Duration
VestingPeriod          time.Duration
VestingPoolName        string
}
Parameters
Param Description
Owner Address of the campaign owner
Name Name of the campaign
Description Description of the campaign
CampaignType Type of the campaign (e.g., VestingPoolCampaign)
RemovableClaimRecords Indicates if claim records can be removed
FeegrantAmount Amount set for fee grant
InitialClaimFreeAmount Initial free amount to claim
Free Decrement value to make claims free
StartTime Starting time of the campaign
EndTime Ending time of the campaign
LockupPeriod Duration for which the amount remains locked
VestingPeriod Duration of the vesting
VestingPoolName Name associated with the vesting pool
State Modifications
  • Validates various campaign parameters including the start and end times, fee grant amount, among others.
  • Confirms that the end time is post the current block time.
  • Establishes a new Campaign structure using the given parameters.
  • Validates the vesting pool if the campaign type happens to be VestingPoolCampaign.
  • Incorporates the new campaign into the store and allots it a unique ID.
  • An initialClaim mission is automatically added to the campaign.
  • Triggers the EventNewCampaign event, signaling the establishment of a new campaign.

Enable Campaign

Enable an existing campaign with specified start and end times.

The MsgEnableCampaign can be used to modify the start and end times of a campaign and to activate it.

Structure
type MsgEnableCampaign struct {
Owner       string
CampaignId  uint64
StartTime   *time.Time (optional)
EndTime     *time.Time (optional)
}
Parameters
Param Description
Owner Address of the campaign owner
CampaignId ID of the campaign to be enabled
StartTime New starting time of the campaign (optional)
EndTime New ending time of the campaign (optional)
State Modifications
  • Retrieves the specified campaign by the CampaignId.
  • Validates the ownership of the campaign.
  • Checks and updates the start and end times if provided, ensuring:
    • The start time is before the end time.
    • The start time isn't the same as the end time.
  • Validates that the campaign isn't already enabled.
  • Sets the campaign's status to enabled.
  • Updates the campaign in the state with the new details.
  • Emits the EventEnableCampaign event, signaling the enabling of the specified campaign.

Close Campaign

Closes an existing campaign based on the specified parameters.

The MsgCloseCampaign can be submitted by the campaign owner to signal the end of a campaign, ensuring all assets and values are properly reconciled.

Structure
type MsgCloseCampaign struct {
Owner      string
CampaignId uint64
}
Parameters
Param Description
Owner Address of the campaign owner
CampaignId ID of the campaign to be closed
State Modifications
  • Retrieves the specified campaign from the store.
  • Validates the parameters for closing the campaign, ensuring the owner is the one who initiated the closure and the campaign has not yet ended.
  • Returns all remaining assets to the campaign owner.
  • Sets the campaign's current amount to zero and disables the campaign.
  • Emits an EventCloseCampaign event, signaling the closure of a campaign.

Remove Campaign

Remove an existing campaign based on the specified parameters.

The MsgRemoveCampaign can be submitted by the campaign owner to initiate the removal of a campaign. All the assets within the campaign are returned to the owner before removal. This message can be only used if the campaign is not enabled.

Structure
type MsgRemoveCampaign struct {
Owner      string
CampaignId uint64
}
Parameters
Param Description
Owner Address of the campaign owner
CampaignId ID of the campaign to be removed
State Modifications
  • Retrieves the specified campaign from the store using its ID.
  • Validates the removal parameters to ensure that the owner is the one initiating the removal and that the campaign is not enabled.
  • Returns all current assets and fee grants of the campaign to the owner.
  • Removes the campaign and all associated missions from the store.
  • Emits an EventRemoveCampaign event, signaling the removal of a campaign.

Add Mission

The MsgAddMission message type facilitates the addition of a mission to an existing campaign on the blockchain. A mission, in the context of this chain, represents a specific task or objective within a campaign, and has parameters like weight, claim start date, and type, dictating its behavior. By submitting this message, the campaign owner can diversify the range of activities within a campaign, giving participants more avenues to engage with the campaign.

Structure
type MsgAddMission struct {
Owner          string
CampaignId     uint64
Name           string
Description    string
MissionType    types.MissionType
Weight         sdk.Dec
ClaimStartDate *time.Time
}
Parameters
Param Description
Owner Address of the individual or entity responsible for this mission and the campaign it belongs to.
CampaignId A unique identifier for the campaign to which this mission will be added.
Name A concise title for the mission, allowing participants to quickly identify its nature.
Description An elaborate description providing in-depth details about what the mission entails.
MissionType Classifies the mission, e.g., InitialClaim might indicate a task that can only be done at the campaign's start.
Weight Represents the mission's importance or significance within the campaign.
ClaimStartDate Specifies the date from which claims related to this mission can begin, ensuring phased or timed participation.
State Modifications
  • Before any modifications, the system checks mission parameters such as name, mission type, and weight for validity. Incorrect or malicious inputs are rejected.
  • The specified campaign's existence and the authenticity of the campaign owner are verified.
  • All existing missions within the campaign are summed up with the new mission's weight to ensure the total doesn't exceed a weight of 1. This ensures no single mission or a combination overshadows the rest in significance.
  • The state checks if the campaign is still active and not ended. Missions can't be added to an expired or inactive campaign.
  • Upon successful validation, the new mission is appended to the campaign's list of missions and a unique ID is assigned to it.
  • An EventAddMission event is emitted to signal the blockchain about the addition of a new mission. This can be used by listeners for various purposes like notifications.

Initial Claim

Allows a user to claim a specified amount from a campaign using its unique ID.

The MsgInitialClaim message can be sent by any valid account eligible to claim rewards from the specified campaign.

Structure
type MsgInitialClaim struct {
Claimer           string
CampaignId        uint64
DestinationAddress string
}
Parameters
Param Description
Claimer Address of the user attempting to claim the reward.
CampaignId Unique identifier for the campaign from which the user is claiming.
DestinationAddress The address where the claimed amount should be deposited.
State Modifications
  • The method fetches necessary data such as the campaign details, associated mission, the user's entry, and the claim record using the provided CampaignId.
  • The method validates the given DestinationAddress ensuring it's not a blocked or invalid address.
  • The destination address is assigned to the claim record, and the mission status is updated to reflect completion.
  • The claimable amount for the user's initial claim is computed. This amount depends on the user's interactions and the campaign's configuration.
  • For all campaign types, the claimable amount is sent to a periodic continuous vesting account. This ensures that the claimed rewards are vested according to the campaign's rules.
  • After the claim, the campaign's current balance is decremented by the claimable amount.
  • Once the initial claim is processed successfully, an EventInitialClaim event is emitted to indicate the completion of the claim.

Claim

Allows a user to claim rewards based on the completion of a specific mission within a campaign.

The MsgClaim can be submitted by any valid account, which has completed the required mission, to claim the associated rewards.

Structure
type MsgClaim struct {
Claimer    string
CampaignId uint64
MissionId  uint64
}
Parameters
Param Description
Claimer Address of the user attempting to claim the reward.
CampaignId Unique identifier for the campaign from which the user is claiming.
MissionId Unique identifier for the mission within the campaign that the user has completed and is attempting to claim.
State Modifications
  • Retrieves data related to the campaign, the specific mission, user entry, and the claim record using the provided CampaignId and MissionId.
  • Confirms if the initial mission associated with the campaign has been claimed.
  • If the mission type is specifically a "claim" mission, it's marked as completed.
  • Determines the amount eligible to be claimed based on the provided mission.
  • For all campaign types, the claimable amount is sent to a periodic continuous vesting account. This ensures that the claimed rewards are vested according to the campaign's rules.
  • Decreases the current balance of the campaign by the claimed amount.
  • Emits the EventClaim event, indicating a successful claim.

Add Claim Records

This message is responsible for adding claim records to an existing campaign. When adding claim records, the module takes into consideration the type of the campaign, the provided claim records, the owner of the campaign, and the associated fees. If the campaign type is a VestingPoolCampaign, special validation and adjustments are made based on the vesting denomination. If fee grants are associated with the campaign, the module ensures that the necessary fee grants are given to the appropriate addresses.

The MsgAddClaimRecords can be submitted by the campaign owner to add claim records to a given campaign.

Structure
type MsgAddClaimRecords struct {
Owner              string
CampaignId         uint64
ClaimRecordEntries []*types.ClaimRecordEntry
}
Parameters
Param Description
Owner Address of the campaign owner.
CampaignId ID of the campaign to which the claim records are being added.
ClaimRecordEntries A list of claim record entries that specify the users and amounts for claims.
State Modifications

  • Validation of Input:

    • Ensures that the campaign associated with CampaignId exists.
    • Validates that the Owner address matches the owner of the campaign.
    • Ensures the campaign has not yet ended.
    • If the campaign is of type VestingPoolCampaign, validates the claim record entries against the vesting denomination.
    • Otherwise, validates the claim record entries in general.

  • Calculation of Fee Grants:

    • Calculates the total fees required for granting fees based on the fee grant amount and the number of claim record entries.
    • Checks if the campaign owner has sufficient balance to cover these fees.

  • Adjustment for Vesting Pool Campaigns:

    • If the campaign is of type VestingPoolCampaign, it adds a new reservation to the associated vesting pool.
    • Verifies the owner's balance is sufficient to cover the fees.
    • Verifies the vesting pool balance is sufficient to cover the claim records' amounts.

  • Adjustment for Default Campaigns:

    • If the campaign is of a default type, the module calculates the sum of fees and the amounts from the claim records.
    • Ensures that the owner has sufficient balance to cover this combined amount.

  • Setting Up Fee Grants:

    • If a positive fee grant amount is specified, the module sets up a new fee grant account.
    • Transfers the necessary coins from the owner to this fee grant account.
    • Grants the fee allowance to all claim record users.

  • User Entry Creation:

    • For each claim record entry, the module creates or updates the user entry associated with the claim.
    • If a user does not have an account in the system, a new account is created for them.

  • An EventAddClaimRecords event is emitted, which details the owner, campaign ID, total amount across all claim records, and the number of claim records.

Delete Claim Record

Allows a campaign owner to remove an existing claim record for a specific user within a given campaign. The MsgDeleteClaimRecord action encompasses several validations, balance calculations, and state modifications, ensuring that the claim record deletion is properly recorded and the associated funds are correctly handled. If the campaign has the removableClaimRecords flag set to true, you can delete claim records at any time during the campaign. Otherwise, claim records can only be deleted until the campaign is enabled.

The MsgDeleteClaimRecord can be submitted by the campaign owner to delete a claim record for a given user associated with a campaign.

Structure
type MsgDeleteClaimRecord struct {
Owner       string
CampaignId  uint64
UserAddress string
}
Parameters
Param Description
Owner Address of the campaign owner; responsible for initiating the deletion
CampaignId Unique identifier of the campaign from which the claim record is deleted
UserAddress Address of the user whose claim record is to be deleted
State Modifications
  • It ensures that the caller, identified by the Owner address, is indeed the owner of the campaign
  • It checks the campaign's data to confirm the presence of a claim record associated with the provided UserAddress.
  • Calculates the total amount linked with the claim record to be deleted. The amount is derived from the claim record and any associated missions the user may have claimed.
  • If the campaign is of type VestingPoolCampaign, the associated vesting pool reservations are adjusted, and necessary funds are released.
  • For other types of campaigns, the calculated amount is sent back to the campaign owner's account. This ensures that the campaign's balance remains accurate after the claim record deletion.
  • If the campaign has set up a FeegrantAmount, any associated fee grant with the user is revoked. Any remaining funds from the fee grant are transferred back to the campaign owner.
  • The claim record associated with the UserAddress is removed. This step ensures that the user no longer has a claim on the campaign after deletion.
  • The campaign's current and total amounts are decremented based on the amount associated with the deleted claim record. This ensures the campaign's financial data remains accurate.
  • At the end of the process, an EventDeleteClaimRecord event is emitted. This event logs the details of the deletion, including the involved addresses and the amount associated with the deleted claim record.

Events

Handlers for MsgCreateCampaign
Type Attribute Key Attribute Value
NewCampaign id {campaign_id}
NewCampaign owner {owner_address}
NewCampaign name {campaign_name}
NewCampaign description {campaign_description}
NewCampaign campaign_type {campaign_type_name}
NewCampaign feegrant_amount {feegrant_amount}
NewCampaign initial_claim_free_amt {initial_claim_free_amount}
NewCampaign start_time {start_time}
NewCampaign end_time {end_time}
NewCampaign lockup_period {lockup_duration}
NewCampaign vesting_period {vesting_duration}
NewCampaign vesting_pool_name {vesting_pool_name}
message action /chain4energy.c4echain.cfeclaim.MsgCreateCampaign
message sender {sender_address}
Handlers for MsgCloseCampaign
Type Attribute Key Attribute Value
CloseCampaign owner {owner_address}
CloseCampaign campaign_id {campaign_id}
message action /chain4energy.c4echain.cfeclaim.MsgCloseCampaign
message sender {sender_address}
Handlers for MsgRemoveCampaign
Type Attribute Key Attribute Value
RemoveCampaign owner {owner_address}
RemoveCampaign campaign_id {campaign_id}
message action /chain4energy.c4echain.cfeclaim.MsgRemoveCampaign
message sender {sender_address}
Handlers for MsgAddMission
Type Attribute Key Attribute Value
AddMission id {mission_id}
AddMission owner {owner_address}
AddMission campaign_id {campaign_id}
AddMission name {mission_name}
AddMission description {mission_description}
AddMission mission_type {mission_type_name}
AddMission weight {mission_weight}
AddMission claim_start_date {claim_start_date}
message action /chain4energy.c4echain.cfeclaim.MsgAddMission
message sender {sender_address}
Handlers for MsgInitialClaim
Type Attribute Key Attribute Value
InitialClaim claimer {claimer_address}
InitialClaim campaign_id {campaign_id}
InitialClaim destination_address {destination_address}
InitialClaim amount {claimed_amount}
message action /chain4energy.c4echain.cfeclaim.MsgInitialClaim
message sender {sender_address}
Handlers for MsgClaim
Type Attribute Key Attribute Value
Claim claimer {claimer_address}
Claim campaign_id {campaign_id}
Claim mission_id {mission_id}
Claim amount {claimed_amount}
message action /chain4energy.c4echain.cfeclaim.MsgClaim
message sender {sender_address}
Handlers for MsgAddClaimRecords
Type Attribute Key Attribute Value
AddClaimRecords owner {owner_address}
AddClaimRecords campaign_id {campaign_id}
AddClaimRecords total_amount {total_amount_added}
AddClaimRecords number_of_claim_records {number_of_claim_records}
message action /chain4energy.c4echain.cfeclaim.MsgAddClaimRecords
message sender {sender_address}
Handlers for MsgDeleteClaimRecord
Type Attribute Key Attribute Value
DeleteClaimRecord owner {owner_address}
DeleteClaimRecord campaign_id {campaign_id}
DeleteClaimRecord user_address {user_address}
DeleteClaimRecord claim_record_amount {claim_record_amount}
message action /chain4energy.c4echain.cfeclaim.MsgDeleteClaimRecord
message sender {sender_address}

Queries

User Entry Query

Queries a specific user entry by the address.

Endpoint: /c4e/claim/v1beta1/user_entry/{address}

{
  "user_entry":{
    "address":"example_address",
    "claim_records":[
      {
        "campaign_id":1,
        "address":"example_address",
        "amount":[
          {
            "denom":"uc4e",
            "amount":"1000"
          }
        ],
        "completedMissions":[
          1,
          2
        ],
        "claimedMissions":[
          2
        ]
      }
    ]
  }
}
Users Entries Query

Queries a list of all user entries.

Endpoint: /c4e/claim/v1beta1/users_entries

{
  "users_entries":[
    {
      "address":"example_address_1",
      "claim_records":[
        {
          "campaign_id":1,
          "address":"example_address",
          "amount":[
            {
              "denom":"uc4e",
              "amount":"1000"
            }
          ],
          "completedMissions":[
            1,
            2
          ],
          "claimedMissions":[
            2
          ]
        }
      ]
    },
    {
      "address":"example_address_2",
      "claim_records":[
        {
          "campaign_id":1,
          "address":"example_address",
          "amount":[
            {
              "denom":"uc4e",
              "amount":"1000"
            }
          ],
          "completedMissions":[
            1,
            2
          ],
          "claimedMissions":[
            2
          ]
        }
      ]
    }
  ],
  "pagination":{
    "next_key": null,
    "total": "2"
  }
}
Mission Query

Queries a specific mission based on campaign ID and mission ID.

Endpoint: /c4e/claim/v1beta1/mission/{campaign_id}/{mission_id}

{
  "mission":{
    "id":1,
    "campaign_id":1,
    "name":"Example Mission",
    "description":"Description for example mission",
    "missionType":"INITIAL_CLAIM",
    "weight":"0.3",
    "claim_start_date":"2023-01-01T00:00:00Z"
  }
}
Missions Query

Queries a list of all mission items.

Endpoint: /c4e/claim/v1beta1/missions

{
  "missions":[
    {
      "id":1,
      "campaign_id":1,
      "name":"Example Mission 1",
      "description":"Description for example mission 1",
      "missionType":"INITIAL_CLAIM",
      "weight":"0.3",
      "claim_start_date":"2023-01-01T00:00:00Z"
    },
    {
      "id":2,
      "campaign_id":1,
      "name":"Example Mission 2",
      "description":"Description for example mission 2",
      "missionType":"CLAIM",
      "weight":"0.3",
      "claim_start_date":"2023-01-01T00:00:00Z"
    }
  ],
  "pagination":{
    "next_key": null,
    "total": "2"
  }
}
Campaign Missions Query

Queries a list of mission items for a given campaign.

Endpoint: /c4e/claim/v1beta1/missions/{campaign_id}

{
  "missions":[
    {
      "id":1,
      "campaign_id":1,
      "name":"Example Mission 1",
      "description":"Description for example mission 1",
      "missionType":"INITIAL_CLAIM",
      "weight":"0.3",
      "claim_start_date":"2023-01-01T00:00:00Z"
    },
    {
      "id":2,
      "campaign_id":1,
      "name":"Example Mission 2",
      "description":"Description for example mission 2",
      "missionType":"CLAIM",
      "weight":"0.3",
      "claim_start_date":"2023-01-01T00:00:00Z"
    }
  ],
  "pagination":{
    "next_key": null,
    "total": "2"
  }
}
Campaign Query

Queries a specific campaign by its ID.

Endpoint: /c4e/claim/v1beta1/campaign/{campaign_id}

{
  "campaign": {
    "id": "1",
    "owner": "c4e1p0smw03cwhqn05fkalfpcr0ngqv5jrpnx2cp54",
    "name": "Example campaign",
    "description": "Description for example campaign",
    "campaignType": "VESTING_POOL",
    "removable_claim_records": false,
    "feegrant_amount": "0",
    "initial_claim_free_amount": "0",
    "free": "0.010000000000000000",
    "enabled": false,
    "start_time": "2030-01-01T00:00:00Z",
    "end_time": "2031-01-01T00:00:00Z",
    "lockup_period": "15811200s",
    "vesting_period": "7862400s",
    "vestingPoolName": "Fairdrop",
    "campaign_total_amount": [
      {
        "denom": "uc4e",
        "amount": "10000000000"
      }
    ],
    "campaign_current_amount": [
      {
        "denom": "uc4e",
        "amount": "10000000000"
      }
    ]
  }
}
Campaigns Query

Queries a list of all campaign items.

Endpoint: /c4e/claim/v1beta1/campaigns

{
  "campaigns": [
    {
      "id": "0",
      "owner": "c4e1dsm96gwcv35m4rqd93pzcsztpkrqe0ev7getj8",
      "name": "Example Campaign",
      "description": "Example campaign description",
      "campaignType": "VESTING_POOL",
      "removable_claim_records": true,
      "feegrant_amount": "0",
      "initial_claim_free_amount": "0",
      "free": "0.000000000000000000",
      "enabled": false,
      "start_time": "2030-01-01T00:00:00Z",
      "end_time": "2031-01-01T00:00:00Z",
      "lockup_period": "63072000s",
      "vesting_period": "63072000s",
      "vestingPoolName": "Moondrop",
      "campaign_total_amount": [
        {
          "denom": "uc4e",
          "amount": "7280002000000"
        }
      ],
      "campaign_current_amount": [
        {
          "denom": "uc4e",
          "amount": "7280002000000"
        }
      ]
    },
    {
      "id": "1",
      "owner": "c4e1p0smw03cwhqn05fkalfpcr0ngqv5jrpnx2cp54",
      "name": "Example campaign",
      "description": "Example campaign description",
      "campaignType": "VESTING_POOL",
      "removable_claim_records": false,
      "feegrant_amount": "0",
      "initial_claim_free_amount": "0",
      "free": "0.010000000000000000",
      "enabled": false,
      "start_time": "2030-01-01T00:00:00Z",
      "end_time": "2031-01-01T00:00:00Z",
      "lockup_period": "15811200s",
      "vesting_period": "7862400s",
      "vestingPoolName": "Fairdrop",
      "campaign_total_amount": [
        {
          "denom": "uc4e",
          "amount": "8999999989680"
        }
      ],
      "campaign_current_amount": [
        {
          "denom": "uc4e",
          "amount": "8999999989680"
        }
      ]
    }
  ],
  "pagination": {
    "next_key": null,
    "total": "2"
  }
}

Invariants

Campaign Current Amount Sum Invariant

Invariant validates the campaign's current amount state. This checks if the sum of campaign claims left is consistent with the cfeclaim module account balance.

Definition
  • Name: campaignCurrentAmountSumInvariant
  • Route: "campaigns-current-amount"
  • Module: cfeclaim
Logic
  1. Retrieve All Campaigns: The function fetches all campaigns within the context.
  2. Empty Check: If there are no campaigns, an invariant message indicates that the campaigns list is empty, and the check returns false.
  3. Vesting vs. Default Campaigns: The function segregates campaigns based on their type (VestingPoolCampaign vs. DefaultCampaign) and performs different calculations for each.
  • For VestingPoolCampaign:
    • The function adds up the current amount of each vesting campaign.
    • It also fetches and sums up the amount locked in reservations for the vesting campaign using the vestingKeeper.MustGetVestingPoolReservation method.
  • For DefaultCampaign:
    • The function adds up the current amount of each default campaign.
  1. Module Account Balance Check:
  • Retrieves the coins associated with the cfeclaim module account.
  • Checks if this balance is equal to the total current amount of default campaigns. If not, an invariant error message is returned, and the check returns true.
  1. Vesting Campaign Amount Check:
  • Compares the total current amount of vesting campaigns with the sum of tokens locked in vesting pool reservations.
  • If they aren't equal, an invariant error message is returned, and the check returns true.
  1. Successful Invariant Check:
  • If both checks are successful, an invariant message indicates that the claims left sum is equal to the cfeclaim module account balance, and the check returns false.

Genesis Initialization and Validation

The genesis initialization and validation process ensures a consistent and predefined initial state. This documentation breaks down the purpose and workings of various functions involved.

InitGenesis initializes the module's state from a provided genesis state, encompassing campaigns, missions, and user entries.

func InitGenesis(ctx sdk.Context, k keeper.Keeper, genState types.GenesisState) {
setCampaigns(ctx, k, genState.Campaigns, genState.CampaignCount)
setMissions(ctx, k, genState.Missions, genState.MissionCounts)
setUsersEntries(ctx, k, genState.UsersEntries)
}
Set campaigns

It validates each campaign's parameters using ValidateCampaignParams. Invalid parameters cause a panic. Once validated, the campaign data is set.

Set missions

It ensures the associated campaign exists for each mission and validates the mission using ValidateAddMission. Any issues lead to a panic. Valid missions are set.

Set users entries

Each user entry undergoes validation with Validate. Subsequently, claim records are verified using validateClaimRecords. Successful validation results in setting the user entry.

Helper functions
  • validateClaimRecords: Validates claim records, ensuring associated campaigns and missions are correct.
  • ValidateAddMission: Validates the mission parameters and ensures its association with a valid campaign.
  • ValidateCampaignParams: Validates the campaign parameters based on campaign type.
  • UserEntry.Validate: Validates a user's entry structure, ensuring a valid address format and non-duplicacy of campaign and mission IDs.
  • The genesis validation functions ensure the integrity and consistency of initial data. Any inconsistencies or violations lead to a panic, preventing the initialization of an invalid state.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExportGenesis 

func ExportGenesis(ctx sdk.Context, k keeper.Keeper) *types.GenesisState

ExportGenesis returns the capability module's exported genesis.

func InitGenesis 

func InitGenesis(ctx sdk.Context, k keeper.Keeper, genState types.GenesisState)

InitGenesis initializes the capability module's state from a provided genesis state.

Types

type AppModule 

type AppModule struct {
	AppModuleBasic
	// contains filtered or unexported fields
}

AppModule implements the AppModule interface for the capability module.

func NewAppModule 

func NewAppModule(
	cdc codec.Codec,
	keeper keeper.Keeper,
	cfevestingKeeper cfevestingkeeper.Keeper,
	accountKeeper types.AccountKeeper,
	bankKeeper types.BankKeeper,
) AppModule

func (AppModule) BeginBlock 

func (am AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock)

BeginBlock executes all ABCI BeginBlock logic respective to the capability module.

func (AppModule) ConsensusVersion 

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements ConsensusVersion.

func (AppModule) EndBlock 

func (am AppModule) EndBlock(_ sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate

EndBlock executes all ABCI EndBlock logic respective to the capability module. It returns no validator updates.

func (AppModule) ExportGenesis 

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

ExportGenesis returns the capability module's exported genesis state as raw JSON bytes.

func (AppModule) GenerateGenesisState 

func (AppModule) GenerateGenesisState(simState *module.SimulationState)

GenerateGenesisState creates a randomized GenState of the module

func (AppModule) InitGenesis 

func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, gs json.RawMessage) []abci.ValidatorUpdate

InitGenesis performs the capability module's genesis initialization It returns no validator updates.

func (AppModule) Name 

func (am AppModule) Name() string

Name returns the capability module's name.

func (AppModule) ProposalContents 

func (AppModule) ProposalContents(_ module.SimulationState) []simtypes.WeightedProposalContent

ProposalContents doesn't return any content functions for governance proposals

func (AppModule) ProposalMsgs added in v1.4.0 

func (am AppModule) ProposalMsgs(simState module.SimulationState) []simtypes.WeightedProposalMsg

ProposalMsgs returns msgs used for governance proposals for simulations.

func (AppModule) RegisterInvariants 

func (am AppModule) RegisterInvariants(ir sdk.InvariantRegistry)

RegisterInvariants registers the capability module's invariants.

func (AppModule) RegisterServices 

func (am AppModule) RegisterServices(cfg module.Configurator)

RegisterServices registers a GRPC query service to respond to the module-specific GRPC queries.

func (AppModule) RegisterStoreDecoder 

func (am AppModule) RegisterStoreDecoder(_ sdk.StoreDecoderRegistry)

RegisterStoreDecoder registers a decoder

func (AppModule) WeightedOperations 

func (am AppModule) WeightedOperations(simState module.SimulationState) []simtypes.WeightedOperation

WeightedOperations returns the all the gov module operations with their respective weights.

type AppModuleBasic 

type AppModuleBasic struct {
	// contains filtered or unexported fields
}

AppModuleBasic implements the AppModuleBasic interface for the capability module.

func NewAppModuleBasic 

func NewAppModuleBasic(cdc codec.BinaryCodec) AppModuleBasic

func (AppModuleBasic) DefaultGenesis 

func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage

DefaultGenesis returns the capability module's default genesis state.

func (AppModuleBasic) GetQueryCmd 

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd returns the capability module's root query command.

func (AppModuleBasic) GetTxCmd 

func (a AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd returns the capability module's root tx command.

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

Name returns the capability module's name.

func (AppModuleBasic) RegisterCodec 

func (AppModuleBasic) RegisterCodec(cdc *codec.LegacyAmino)

func (AppModuleBasic) RegisterGRPCGatewayRoutes 

func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the module.

func (AppModuleBasic) RegisterInterfaces 

func (a AppModuleBasic) RegisterInterfaces(reg cdctypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types

func (AppModuleBasic) RegisterLegacyAminoCodec 

func (AppModuleBasic) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)

func (AppModuleBasic) RegisterRESTRoutes 

func (AppModuleBasic) RegisterRESTRoutes(clientCtx client.Context, rtr *mux.Router)

RegisterRESTRoutes registers the capability module's REST service handlers.

func (AppModuleBasic) ValidateGenesis 

func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the capability module.

Source Files

View all Source files

Directories

Path Synopsis
client
cli
Package types is a reverse proxy.
 Package types is a reverse proxy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.