feat: storage deposit #4035

piux2 · 2025-03-31T10:16:14Z

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

Paying for Storage
Whenever data is stored in a realm (e.g., via SetObject), an amount of GNOT is locked as a “storage deposit.”
Reclaiming Storage & Deposit
When stored data is removed, the corresponding deposit is released back to the user.
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

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.
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.
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

Make a MsgCall / MsgRun / AddPkg Call
- The user (or contract) sets how many GNOT to allow for extra storage usage.
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.
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 · 2025-03-31T10:17:33Z

🛠 PR Checks Summary

All Automated Checks passed. ✅

Manual Checks (for Reviewers):

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

✅ Automated Checks (for Contributors):

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

☑️ Contributor Actions:

Fix any issues flagged by automated checks.
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:

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

📚 Resources:

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 · 2025-03-31T10:21:51Z

Codecov Report

Attention: Patch coverage is 62.01550% with 98 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
tm2/pkg/overflow/overflow_impl.go	0.00%	44 Missing ⚠️
gno.land/pkg/sdk/vm/keeper.go	66.33%	24 Missing and 10 partials ⚠️
gno.land/pkg/sdk/vm/params.go	60.00%	4 Missing and 2 partials ⚠️
gno.land/pkg/sdk/vm/handler.go	63.63%	3 Missing and 1 partial ⚠️
gno.land/pkg/keyscli/addpkg.go	75.00%	2 Missing and 1 partial ⚠️
gno.land/pkg/keyscli/call.go	75.00%	2 Missing and 1 partial ⚠️
gno.land/pkg/keyscli/run.go	76.92%	2 Missing and 1 partial ⚠️
gno.land/pkg/sdk/vm/msgs.go	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

Kouteki · 2025-03-31T13:57:02Z

Closes #3418

jaekwon · 2025-04-11T00:51:51Z

examples/gno.land/p/demo/avl/z_0_filetest.gno

@@ -24,7 +24,7 @@ func main() {

 // Realm:
 // switchrealm["gno.land/r/test"]
-// u[a8ada09dee16d791fd406d629fe29bb0ed084a30:4]=
+// u[a8ada09dee16d791fd406d629fe29bb0ed084a30:4](2)=


i like this syntax.

jaekwon · 2025-04-11T00:52:57Z

gno.land/pkg/integration/testdata/storage_rent.txtar

@@ -0,0 +1,80 @@
+# test the storage rent


It isn't rent. It's ownership. (but we already use "owner" for objects so need a different term).
Rent is when you pay an upkeep for something.
GNOT deposits are forever.

just "deposit".

jaekwon · 2025-04-11T00:57:57Z

gno.land/pkg/sdk/vm/keeper.go

@@ -328,6 +330,7 @@ func (vm *VMKeeper) AddPackage(ctx sdk.Context, msg MsgAddPackage) (err error) {
 	creator := msg.Creator
 	pkgPath := msg.Package.Path
 	memPkg := msg.Package
+	send := msg.Send


note to self: is send amount segregated from storage deposits?
(the realm should not be able to spend its storage deposits)

jaekwon · 2025-04-11T00:59:08Z

gno.land/pkg/sdk/vm/keeper.go

 	m2.RunMemPackage(memPkg, true)

+	// use the parameters before executing the message, as they may change during execution.
+	// The message should not fail due to parameter changes in the same transaction.


wild edge case!

jaekwon · 2025-04-11T01:00:53Z

gno.land/pkg/sdk/vm/keeper.go

+// QueryStorage returns storage and deposit for a realm.
+func (vm *VMKeeper) QueryStorage(ctx sdk.Context, pkgPath string) (string, error) {
+	store := vm.newGnoTransactionStore(ctx) // throwaway (never committed)
+	// Ensure pkgPath is realm.


why not allow the query for packages? could be good to know, even if it is not mutable.

jaekwon · 2025-04-11T01:02:21Z

gno.land/pkg/sdk/vm/keeper.go

+// An error is returned if there's insufficient deposit, a transfer error occurs,
+// or an invariant violation happens during deposit or storage adjustments.
+
+func (vm *VMKeeper) processDeposit(ctx sdk.Context, caller crypto.Address, deposit std.Coins, gnostore gno.Store, params Params) error {


process storage deposit

jaekwon · 2025-04-11T01:05:50Z

gno.land/pkg/sdk/vm/keeper.go

+		} else {
+			// release storage used and return deposit
+			released := -diff
+			if rlm.Storage < uint64(released) {


note to self: why is this check needed?

jaekwon · 2025-04-11T01:06:38Z

gno.land/pkg/sdk/vm/keeper.go

+					rlmPath, rlm.Deposit, ugnot.Denom, depositUnlocked, ugnot.Denom))
+			}
+
+			err := vm.refundStorageDeposit(ctx, caller, rlm, depositUnlocked, released)


the refund should happen aggregated once, not per realm.

jaekwon · 2025-04-11T01:10:06Z

tm2/pkg/overflow/overflow_impl.go

@@ -87,6 +87,24 @@ func Quotient8(a, b int8) (int8, int8, bool) {
 	return c, a % b, status
 }

+// AddUint8 performs + operation on two uint8 operands, returning a result and status.
+func AddUint8(a, b uint8) (uint8, bool) {


this is cool, is it used?

jaekwon · 2025-04-11T01:12:22Z

gnovm/pkg/gnolang/store.go

 // Unstable.
 // This function is used to clear the object cache every transaction.
 // It also sets a new allocator.
 func (ds *defaultStore) ClearObjectCache() {
 	ds.alloc.Reset()
 	ds.cacheObjects = make(map[ObjectID]Object) // new cache.
-	ds.opslog = nil                             // new ops log.
+	ds.objectSizeCache = make(map[ObjectID]int64)


Let's put this in ObjectInfo as unexposed lastObjectSize so as to avoid a map lookup.

jaekwon · 2025-04-11T01:15:28Z

gno.land/pkg/sdk/vm/msgs.go

@@ -86,6 +87,7 @@ func (msg MsgAddPackage) GetReceived() std.Coins {
 type MsgCall struct {
 	Caller  crypto.Address `json:"caller" yaml:"caller"`
 	Send    std.Coins      `json:"send" yaml:"send"`
+	Deposit std.Coins      `json:"deposit" yaml:"deposit"`


Suggest "MaxDeposit" so it's clear it's not just sending coins, it's doing something and you get something back.
Also json omitempty so that users don't have to worry about it usually.

jaekwon

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

jaekwon · 2025-04-11T01:30:07Z

gno.land/pkg/sdk/vm/params.go

+	sysNamesPkgDefault    = "gno.land/r/sys/names"
+	chainDomainDefault    = "gno.land"
+	defaultDepositDefault = "600000000ugnot"
+	storagePriceDefault   = "1000ugnot" // cost per byte (1 gnot per KB)


100, 1B GNOT == 10TB.

storage deposit

1cdb921

github-project-automation bot added this to 🧙‍♂️gno.land core team and 💪 Bounties & Worx Mar 31, 2025

github-project-automation bot moved this to Triage in 🧙‍♂️gno.land core team Mar 31, 2025

github-actions bot assigned piux2 Mar 31, 2025

github-actions bot added 🧾 package/realm Tag used for new Realms or Packages. 📦 🤖 gnovm Issues or PRs gnovm related 📦 🌐 tendermint v2 Issues or PRs tm2 related 📦 ⛰️ gno.land Issues or PRs gno.land package related labels Mar 31, 2025

piux2 changed the title ~~storage deposit~~ feat: storage deposit Mar 31, 2025

Kouteki moved this from Triage to In Review in 🧙‍♂️gno.land core team Mar 31, 2025

Kouteki requested a review from jaekwon March 31, 2025 15:05

zivkovicmilos added this to the 🚀 Mainnet beta launch milestone Apr 1, 2025

piux2 requested review from moul and zivkovicmilos April 2, 2025 04:42

jaekwon reviewed Apr 11, 2025

View reviewed changes

jaekwon requested changes Apr 11, 2025

View reviewed changes

github-project-automation bot moved this to In Progress in 💪 Bounties & Worx Apr 11, 2025

jaekwon reviewed Apr 11, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: storage deposit #4035

feat: storage deposit #4035

piux2 commented Mar 31, 2025 •

edited

Loading

Gno2D2 commented Mar 31, 2025 •

edited

Loading

✅ Automated Checks (for Contributors):

☑️ Contributor Actions:

☑️ Reviewer Actions:

📚 Resources:

If

Then

If

Can be checked by

codecov bot commented Mar 31, 2025 •

edited

Loading

Kouteki commented Mar 31, 2025

jaekwon Apr 11, 2025

jaekwon Apr 11, 2025 •

edited

Loading

jaekwon Apr 11, 2025

jaekwon Apr 11, 2025

jaekwon Apr 11, 2025

jaekwon Apr 11, 2025

jaekwon Apr 11, 2025 •

edited

Loading

jaekwon Apr 11, 2025

jaekwon Apr 11, 2025

jaekwon Apr 11, 2025

jaekwon Apr 11, 2025

jaekwon left a comment

jaekwon Apr 11, 2025

feat: storage deposit #4035

Are you sure you want to change the base?

feat: storage deposit #4035

Conversation

piux2 commented Mar 31, 2025 • edited Loading

Solution for : #3418

BREAKING CHANGES

New Message Flag

AddPkg Additional Logic

Purpose

High-Level Design

Usage Tracking

Deposit & Retrieval Flow

Tools

Future Improvements

Gno2D2 commented Mar 31, 2025 • edited Loading

🛠 PR Checks Summary

Manual Checks (for Reviewers):

✅ Automated Checks (for Contributors):

☑️ Contributor Actions:

☑️ Reviewer Actions:

📚 Resources:

If

Then

If

Can be checked by

codecov bot commented Mar 31, 2025 • edited Loading

Codecov Report

Kouteki commented Mar 31, 2025

Choose a reason for hiding this comment

jaekwon Apr 11, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jaekwon Apr 11, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jaekwon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

piux2 commented Mar 31, 2025 •

edited

Loading

Gno2D2 commented Mar 31, 2025 •

edited

Loading

codecov bot commented Mar 31, 2025 •

edited

Loading

jaekwon Apr 11, 2025 •

edited

Loading

jaekwon Apr 11, 2025 •

edited

Loading