feat: storage deposit

[piux2]

Solution for : #3418

BREAKING CHANGES

New Message Flag

• MsgCall and MsgRun now include an optional deposit field to specify how many GNOT the caller is willing to lock for storage.
• This deposit is used to pay storage changes at the end of each message.
• The user's balance is deducted or refunded based on actual storage changes.

AddPkg Additional Logic

• AddPkg now includes:
  • A send flag to send tokens to the realm.
  • A deposit flag to specify how much GNOT to include for storage fees.
• Previously, the -deposit flag was used in place of -send within AddPkg.
• The user's balance is deducted or refunded based on actual storage changes.

---

Purpose

1. Paying for Storage
   Whenever data is stored in a realm (e.g., via SetObject), an amount of GNOT is locked as a “storage deposit.”

2. Reclaiming Storage & Deposit
   When stored data is removed, the corresponding deposit is released back to the user.

3. Encouraging Efficient Storage
   Users must pay to keep data on-chain, incentivizing them to store only what is necessary.

High-Level Design

The system imposes a GNOT deposit for stored data. Each realm tracks its total number of bytes in use and the total tokens locked for that storage. After each message is processed, the net change in storage usage is calculated, and the appropriate amount of GNOT is locked or unlocked. By default, deposit tracking is aggregated per realm rather than per user. Any user refunds or reward mechanisms for freeing storage are determined by the realm.

---

Usage Tracking

1. Realm-Level Tracking

   • Storage: The total number of bytes used in this realm.
   • Deposits: The total GNOT locked to pay for the realm’s storage.

2. Global VM Parameters

   • Storage Price: A rate (in GNOT per byte) defining how much GNOT must be locked per byte stored (e.g., “1 GNOT/KB” or another fraction).
   • Default Deposit: A fallback amount if the user does not specify a custom deposit.

3. Message-Level Fields

   • Optional Deposit Field (in MsgCall/MsgRun/AddPkg): The user can specify how many GNOT to deposit for potential storage usage.
   • Settlement at Message End: When a message finishes, the net storage change is computed, and tokens are transferred accordingly (locked or refunded).

---

Deposit & Retrieval Flow

1. Make a MsgCall / MsgRun / AddPkg Call

   • The user (or contract) sets how many GNOT to allow for extra storage usage.

2. During Execution

   • The system tracks changes in storage size (growth or shrinkage).
   • If storage grows: GNOT from the deposit buffer is locked into the realm.
   • If storage shrinks: GNOT is unlocked from the realm and refunded to the user.

3. Anyone Can Free Storage

   • Because deposits are tracked per realm (not per user), anyone can remove data.
   • This can create a “cleanup reward” scenario where the person who deletes data gains the released deposit.
   • It also gives the realm developer flexibility to design and manage user storage.

---

Tools

• gnokey query vm/qstorage -data <realm_path>: Shows a realm’s locked tokens and current storage usage.
• Storage Directive in Tests: A Storage: directive can be added to file tests to display storage usage across realms.

---

Future Improvements

• Large Default Deposit: Currently, the default deposit is set to a high number, so below that threshold, users do not need to explicitly specify their own deposit. This is used as a workaround for genesis transactions.
• High Storage Price: A rate of 1 GNOT per KB can significantly increase the cost of deploying a package.
• Better User Information: Tools and feedback should be improved to show users how much deposit is being locked or released.
• The realm subsidizes the storage deposit.
• More examples to manage the storage deposit and refund.

[Gno2D2]

🛠 PR Checks Summary

All Automated Checks passed. ✅

Manual Checks (for Reviewers):

• IGNORE the bot requirements for this PR (force green CI check)

Read More

🤖 This bot helps streamline PR reviews by verifying automated checks and providing guidance for contributors and reviewers.

✅ Automated Checks (for Contributors):

🟢 Maintainers must be able to edit this pull request (more info)

☑️ Contributor Actions:

1. Fix any issues flagged by automated checks.
2. Follow the Contributor Checklist to ensure your PR is ready for review.
   • Add new tests, or document why they are unnecessary.
   • Provide clear examples/screenshots, if necessary.
   • Update documentation, if required.
   • Ensure no breaking changes, or include BREAKING CHANGE notes.
   • Link related issues/PRs, where applicable.

☑️ Reviewer Actions:

1. Complete manual checks for the PR, including the guidelines and additional checks if applicable.

📚 Resources:

• Report a bug with the bot.
• View the bot’s configuration file.

Debug

Automated Checks

Maintainers must be able to edit this pull request (more info)

If

🟢 Condition met
└── 🟢 And
    ├── 🟢 The base branch matches this pattern: ^master$
    └── 🟢 The pull request was created from a fork (head branch repo: piux2/gno)

Then

🟢 Requirement satisfied
└── 🟢 Maintainer can modify this pull request

Manual Checks

**IGNORE** the bot requirements for this PR (force green CI check)

If

🟢 Condition met
└── 🟢 On every pull request

Can be checked by

• Any user with comment edit permission

[codecov]

Codecov Report

Attention: Patch coverage is 83.33333% with 12 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
gnovm/pkg/gnolang/misc.go	0.00%	8 Missing ⚠️
gnovm/pkg/gnolang/values.go	0.00%	2 Missing ⚠️
gnovm/stdlibs/std/crypto.go	0.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Kouteki]

Closes #3418

[jaekwon]

Overall direction looks great, just needs some changes. Please call me after changes.

[jaekwon]

I'll take a look!

[thehowl]

superseded by #4281