Skip to main content

Storage Module

The storage module in Gitopia blockchain is responsible for managing storage providers, handling storage challenges, and distributing rewards. This section explains the key components and functionality of the storage module.

Provider Management​

Storage providers are registered on the blockchain and must stake tokens to participate in the network. The module provides the following functionality for provider management:

  • Registration: New providers can register by providing their URL, description, and staking tokens
  • Updates: Providers can update their URL and description
  • Unregistration: Providers can initiate the process of leaving the network
  • Staking: Providers must stake a minimum amount of tokens to participate

Storage Challenges​

The module implements a challenge-response system to verify that providers are maintaining the data properly. For a detailed explanation of the challenge system, see the Storage Challenge System documentation.

  • Challenge Generation: Challenges are automatically generated at regular intervals (every challenge_interval_blocks)
  • Challenge Types: Three types of challenges are supported:
    • Packfile challenges: Verify storage of Git repository packfiles
    • Release asset challenges: Verify storage of release assets
    • LFS object challenges: Verify storage of LFS objects
  • Challenge Response: Providers must submit proofs within the challenge_period
  • Rewards and Penalties:
    • Assigned Provider: Each challenge is pseudo-randomly assigned to one active provider. This provider is rewarded upon successful and timely submission of a valid proof. Failure to do so (either by submitting an invalid proof or no proof at all) is considered a Proof Fault, which incurs a significant penalty.
    • All Active Providers: To ensure network-wide data integrity and availability, all active providers are required to respond to every challenge, not just the assigned one. Their responses are tracked to calculate a min_liveness_ratio. Failing to respond to a challenge results in a Liveness Fault, which is a less severe penalty but affects their overall liveness score. Providers falling below the minimum ratio face penalties.
    • This dual mechanism ensures that while one provider is incentivized with a direct reward, the entire network of providers is continuously verifying their stored data, ensuring high availability and reliability.

Data Management​

The module tracks various types of data stored in the network:

  • Packfiles: Git repository packfiles with their CID, root hash, and size
  • Release Assets: Release assets with their CID, root hash, size, and SHA256 hash
  • LFS Objects: LFS objects with their OID, CID, root hash, and size

Storage Costs​

Gitopia provides 150 MB of free storage to every user, as defined by the free_storage_mb parameter. When a user's total storage usage exceeds this limit, they are charged for any subsequent increase in storage. The cost is determined by the storage_price_per_mb parameter.

How Charges are Calculated​

The storage fee logic is designed to be fair and transparent, only charging for what you use beyond the free tier.

  1. Within the Free Tier: As long as a user's total stored data (repository packfiles, LFS objects, and release assets) remains below the 150 MB free limit, there are no storage costs.

  2. Crossing the Free Tier: When a push operation causes the total storage to exceed the free limit for the first time, the user is charged only for the portion of the data that goes over the limit. For example, if the free limit is 150 MB and a user with 140 MB of existing data pushes a 20 MB update, their new total is 160 MB. They will be charged only for the 10 MB that exceeded the free tier.

  3. Beyond the Free Tier: Once a user's storage has surpassed the 150 MB limit, any subsequent operation that increases their total storage will be charged. For instance, if a user has 200 MB of data and pushes a 5 MB update, they will be charged for the additional 5 MB.

  4. No Charge for Deletion: If a user deletes data, reducing their total storage, they are not charged. If their usage drops back below the free limit, they will not be charged for new storage until they exceed the 150 MB limit again.

  5. Transaction: The storage fee is automatically deducted from the user's wallet during the approval transaction (e.g., MsgApproveRepositoryPackfileUpdate). If the user has insufficient funds, the approval fails, and the storage update is not completed.

This model ensures that users only pay for increased storage consumption beyond a generous free tier, making Gitopia an accessible platform for projects of all sizes.

Module Parameters​

The storage module has several configurable parameters:

  • min_stake_amount: Minimum amount of tokens required to become a provider.
  • challenge_interval_blocks: Number of blocks between challenges.
  • challenge_period: Time window for providers to respond to challenges.
  • reward_per_day: Total reward per day for a provider. This is distributed to the assigned provider for successful challenges.
  • unstake_cooldown_blocks: Number of blocks to wait before completing unstaking.
  • storage_price_per_mb: Price per MB for storage updates beyond free_storage_mb.
  • free_storage_mb: Free storage in MB per user.
  • max_providers: Maximum number of providers allowed in the network.

Liveness and Slashing Parameters​

The challenge system uses a sophisticated set of parameters to manage provider liveness and penalize failures.

  • liveness_window_challenges: The number of recent challenges used to calculate a provider's liveness ratio (e.g., 100).
  • min_liveness_ratio: The minimum percentage of successful responses within the liveness window required to be considered live (e.g., 67%).
  • liveness_slash_amount: A fixed token amount slashed when a provider's liveness ratio drops below the minimum threshold.
  • liveness_slash_percentage: A percentage of the provider's stake slashed for a liveness fault.
  • liveness_jail_time: The duration a provider is jailed for a liveness fault.
  • proof_fault_slash_amount: A fixed token amount slashed when the assigned provider commits a proof fault. This is typically higher than the liveness slash amount.
  • proof_fault_slash_percentage: A percentage of the provider's stake slashed for a proof fault.
  • proof_fault_jail_time: The duration a provider is jailed for a proof fault. This is typically longer than the liveness jail time.
  • max_proof_faults: The maximum number of consecutive proof faults an assigned provider can have before facing more severe penalties.

Transaction Messages​

The module supports the following transaction messages:

  • MsgRegisterProvider: Register as a new storage provider
  • MsgUpdateProvider: Update provider information
  • MsgSubmitChallengeResponse: Submit proof for a storage challenge
  • MsgWithdrawProviderRewards: Withdraw accumulated rewards
  • MsgUnregisterProvider: Initiate provider unregistration
  • MsgCompleteUnstake: Complete the unstaking process
  • MsgUpdateParams: Update module parameters (governance)
  • MsgProposeRepositoryPackfileUpdate: Propose an update to a repository packfile. This is initiated by a storage provider after a user pushes new data. The proposal is temporary and awaits user approval.
  • MsgApproveRepositoryPackfileUpdate: Approve a proposed repository packfile update. This is sent by the user's client (git-remote-gitopia) to confirm the changes proposed by the provider. Upon approval, the blockchain state is finalized.
  • MsgRejectRepositoryPackfileUpdate: Reject a proposed repository packfile update. This allows a user to reject a proposal if it is incorrect or unwanted.
  • MsgIncreaseStake: Increase a provider's stake.
  • MsgDecreaseStake: Decrease a provider's stake.
  • MsgUnjailProvider: Unjail a jailed provider.
  • MsgCompleteDecreaseStake: Complete the stake decrease process.
  • MsgProposeReleaseAssetsUpdate: Propose an update to release assets. Similar to packfile updates, this is initiated by a provider.
  • MsgApproveReleaseAssetsUpdate: Approve a proposed release assets update. Sent by the user to confirm the new assets.
  • MsgRejectReleaseAssetsUpdate: Reject a proposed release assets update.
  • MsgProposeLFSObjectUpdate: Propose an update to an LFS object. Initiated by a provider when a user uploads an LFS file.
  • MsgApproveLFSObjectUpdate: Approve a proposed LFS object update. Sent by the user to confirm the LFS object change.
  • MsgRejectLFSObjectUpdate: Reject a proposed LFS object update.
  • MsgProposeRepositoryDelete: Propose the deletion of a repository.
  • MsgApproveRepositoryDelete: Approve the deletion of a repository.

This blockchain integration ensures the reliability and security of the storage network by incentivizing proper data maintenance and penalizing misbehavior.