Dynamic storage support by Dentosal · Pull Request #982 · FuelLabs/fuel-vm

Dentosal · 2026-01-05T14:48:57Z

Implements dynamic storage instructions as described in FuelLabs/fuel-specs#640

The storage initialization in Create transactions is left as-is, i.e. it only allows 32 byte slots. This feature isn't used much, and I don't think it's worth it to continue supporting.

The only breaking change introduced here is adding an immediate offset operand to SRW instruction. Backwards compatibility is retained as the field as previously required to be zeroed.

Checklist

Breaking changes are clearly marked as such in the PR description and changelog
New behavior is reflected in tests
If performance characteristic of an instruction change, update gas costs as well or make a follow-up PR for that
The specification matches the implemented behavior (link update PR if changes are needed)

Before requesting review

I have reviewed the code myself
I have created follow-up issues caused by this PR and linked them here:
- New storage bytes cost rework #987

cursor · 2026-01-12T12:15:09Z

PR Summary

High Risk
High risk because it changes FuelVM instruction encoding/semantics (SRW operand change + new storage opcodes), rewires core storage read/write APIs, and updates gas/consensus parameters that affect transaction execution and metering.

Overview
Adds dynamic/variable-length contract storage support by introducing new VM opcodes (SCLR, SRDD/SRDI, SWRD/SWRI, SUPD/SUPI, SPLD, SPCP) plus a storage-preload memory area used by SPLD/SPCP, and updates the interpreter to enforce a new max_storage_slot_length limit.

Makes a backwards-compatible instruction format change to SRW by adding an immediate offset operand, updates legacy storage paths (SRW, SRWQ, range reads) to operate safely over variable-sized slots (including new StorageOutOfBounds panic reason), and bumps gas costs to GasCostsValuesV7 with default costs for the new opcodes.

Reworks fuel-storage’s StorageRead API from read -> bool to read_exact/read_zerofill returning Result<usize, StorageReadError>, and propagates the new typed errors through fuel-vm storage implementations, call/return flow, and tests.

^{Written by Cursor Bugbot for commit 0fb12cf. This will update automatically on new commits. Configure here.}

xgreenx · 2026-01-14T11:15:58Z

+        self,
+        interpreter: &mut Interpreter<M, S, Tx, Ecal, V>,
+    ) -> IoResult<ExecuteState, S::DataError> {
+        let (a, b, c, d) = self.unpack();


It would be nice if we used readable names here like in hte opcode definition

Done in eec4b1d

xgreenx · 2026-01-14T11:54:40Z

+            .storage
+            .contract_state(&contract_id, &key)
+            .map_err(RuntimeError::Storage)?
+            .map(|v| v.as_ref().as_ref().to_vec())


You can convert the value into owned type (because, under the hood, it is already owned). Overwise you create vector two times(one when we create value, and another here).

Sure. f07f99e

xgreenx · 2026-01-14T11:55:53Z

+        let dst = self.memory.as_mut().write(owner, dst_ptr, len)?;
+        let value = self
+            .storage
+            .contract_state(&contract_id, &key)


Maybe it is better to use read_bytes here? In this case we will avoud creation of the vector on the fuel-core side

Not sure which read_bytes you're talking about?

Sorry, I thought it was the name=D I meant StorageRead::read

I don't think that works. We need to charge gas based on the full size of the storage slot, and StorageRead::read doesn't expose that info.

Decided on call: lets change the API of StorageRead then

That required quite a bit of refactoring due to zero filling that was already going against the documentation. Since we need to handle the returned error properly, the trait had to be reworked quite a bit.

37ef2c6

cursor · 2026-02-06T03:48:09Z

+        let Some(value) = value else {
+            self.registers[RegId::ERR] = 1;
+            return Ok(0);
+        };


Stale data in preload area after failed SPLD

Medium Severity

When storage_preload doesn't find the requested key, the ERR register is set and 0 is returned, but the preload area is not cleared. If a previous successful SPLD loaded data, that stale data remains in the preload area. A subsequent SPCP call that doesn't properly check ERR could copy this stale data, potentially leading to unexpected behavior or information leakage between different storage keys within the same call frame.

The is the intended behavior from the specification.

Voxelot · 2026-02-07T22:12:46Z

        srdd: DependentCost::LightOperation {
-            base: 50,
-            units_per_gas: 5,
+            base: 2513,


why is this so much more expensive than the original SRWQ?

The values in default_gas_costs.rs aren't related to reality in any way at all. I'll be getting rid of this file in a follow-up PR, see issue #985

The real value from fuel-core that you could compare with is:

srwq: DependentCost::HeavyOperation { base: 520, gas_per_unit: 522, },

which is still cheaper than this, but not unreasonably so

MitchTurner

I'd like to understand what the "preload" is doing.

I had Codex walk me through all the tests because they are inscrutable for me to read unfortunately. Seems good to me, but I wish the could be a little more human-friendly. Also, we use rstest on a lot of them in a way that obscures logic, i.e. we use the cases to create logical differences in the test, rather than helping get better coverage. I think of rstest as a manual prop test solution, but we are using it as a DRYing tool, at the cost of clarity.

MitchTurner · 2026-02-08T15:58:55Z

+    /// Returns `Ok(Ok(length))` if the value does exist, where
+    /// the `length` is the total length of the value stored at the key.
+    ///
+    /// Note that inner error `Ok(Err(_))` is used to communicate errors that the


This isn't very intuitive. I'll see how it works later in the code and readdress.

We could instead flatten the error variants into an enum, but that would make it way less ergonomic to call. The idea here is that the outer error you'll always want to propagate using ?, as there's no way you can handle it in any meaningful way at the call site. The inner error, however, you'll always handle using a match statement, because there will be logic to handle missing keys, at least.

MitchTurner · 2026-02-08T16:08:16Z

+    pub const DEFAULT: Self = Self::V2(ScriptParametersV2::DEFAULT);

    /// Replace the max script length with the given argument
+    #[cfg(feature = "test-helpers")]


Why are these test only now?

Since the new operation with_max_storage_slot_length will panic if used with V1 variant. I don't want to have that kind of thing happen outside tests, and since these are not used anywhere else, it seems prudent to make it test only. The pre-existing functions are marked as test-only for consistency.

MitchTurner · 2026-02-08T16:11:38Z

 fn test_state_read_qword(
    input: SRWQInput,
-) -> Result<(MemoryInstance, bool), RuntimeError<MemoryStorageError>> {
+) -> Result<(MemoryInstance, bool), RuntimeError<Infallible>> {


Why even keep the Result?

Because some cases return an error. It's just that the storage error type nested inside RuntimeError is now infallible, but there are other error types there too, including RuntimeError::Recoverable which is used here.

MitchTurner · 2026-02-08T16:13:58Z

+#[test_case(false, 1, 29, 32, 0 => Ok((0, 0)); "Wrong contract id")]
+#[test_case(false, 0, 29, 33, 0 => Ok((0, 0)); "Wrong key")]
+#[test_case(true, 0, None, Word::MAX, 0 => Err(RuntimeError::Recoverable(PanicReason::MemoryOverflow)); "Overflowing key")]
+#[test_case(true, 0, None, VM_MAX_RAM, 0 => Err(RuntimeError::Recoverable(PanicReason::MemoryOverflow)); "Overflowing key ram")]


Wait. How can we expect a RuntimeError if it's Infallible?

The Infallible is a generic parameter for StorageError, see the definition of RuntimeError:

pub enum RuntimeError<StorageError> { /// Specified error with well-formed fallback strategy, i.e. vm panics. Recoverable(PanicReason), /// Invalid interpreter state reached unexpectedly, this is a bug Bug(Bug), /// Storage io error Storage(StorageError), }

MitchTurner · 2026-02-08T17:05:20Z

    }

-    /// Fetch a mapping from the contract state.
-    pub fn contract_state(


This just isn't used anymore?

MitchTurner · 2026-02-08T18:15:15Z

+}
+
+#[test]
+fn sww_writes_32_bytes() {


This test is breaking my brain. I can't keep track of what thing are slots keys and what things are values while reading it.

Rewritten for clarity in 6d9e197

Dentosal · 2026-02-09T11:44:56Z

I'd like to understand what the "preload" is doing.

The spec says:

The storage preload instruction SPLD loads contents of a storage slot into a staging area. This is a special memory region only readable with SPCP instruction. The staging area is cleared every time a call or return occurs.

This is useful because reading length of a slot requires internally reading the whole slot contents. The primary function of the preload area is to avoid having to load the same slot twice when fetching variable length data. It also allows reading parts of a slot into memory without placing it all continously, which is sometimes useful when i.e. traversing tree structures.

I had Codex walk me through all the tests because they are inscrutable for me to read unfortunately. Seems good to me, but I wish the could be a little more human-friendly.

I attempted abstracting some of the setup code into reusable and well-named functions, but the result was even less readable.

Also, we use rstest on a lot of them in a way that obscures logic, i.e. we use the cases to create logical differences in the test, rather than helping get better coverage. I think of rstest as a manual prop test solution, but we are using it as a DRYing tool, at the cost of clarity.

I'm indeed using it as a DRY tool. I think duplicating the functions would hurt clarity quite a bit more than the rstest does, as now it becomes very hard to see what's the difference between the variants. The code it still by itself rather hard to read, making more of it means you'll have to read twice as much hard-to-understand code. Here rstest-duplication never affects control flow of the fuel-vm instructions.

We could of course do the same thing without rstest and instead move entire test to a separate function, passing in a closure that performs the actual operation-under-test. That would feel rather pointless, and we would lose the nice DX rstest gives us on test failure.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-09T12:01:11Z

+        self.storage
+            .contract_state_insert(&contract_id, &key, &value)
+            .map_err(RuntimeError::Storage)?;
+        Ok(len_after as u64)


SUPD/SUPI gas undercharged for writes to large slots

High Severity

storage_update_from_memory returns len_after (offset + write_len) instead of value.len() (the full slot size). When a small range is updated in a large existing slot, the gas charge is based on the write endpoint, not the total I/O. For example, writing 5 bytes at offset 10 of a 1000-byte slot charges gas for 15 bytes while the storage backend reads and rewrites all 1000 bytes. The return value for gas metering needs to reflect the actual slot size, i.e., value.len(), which equals max(original_len, offset + write_len).

Additional Locations (1)

fuel-vm/src/interpreter/executors/opcodes_impl.rs#L2886-L2896

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-12T10:08:03Z

+            value.len()
+        } else {
+            convert::to_usize(offset).ok_or(PanicReason::MemoryOverflow)?
+        };


Undocumented u64::MAX sentinel enables silent append behavior

Medium Severity

In storage_update_from_memory, offset == u64::MAX is treated as a sentinel meaning "append to end of slot." This implicit behavior is not documented in the SUPD/SUPI opcode descriptions and can be triggered by any contract that sets its offset register to u64::MAX. Instead of getting a StorageOutOfBounds panic (which would naturally occur for such a large offset), the contract silently gets append semantics.

It's documented in the specification

cursor · 2026-02-12T10:08:03Z

+        )?;
+        interpreter.dependent_gas_charge(
+            interpreter.gas_costs().srdd().map_err(PanicReason::from)?,
+            len,


SRDI charges gas using wrong cost accessor name

Low Severity

SRDI charges gas using gas_costs().srdd() and SWRI charges gas using gas_costs().swrd(). While sharing costs between immediate/register variants may be intentional, there are no corresponding srdi or swri fields in GasCostsValuesV7, so these opcodes can never be independently costed. If future gas benchmarking reveals the immediate variants deserve different costs, a new gas cost version will be needed.

Additional Locations (1)

fuel-vm/src/interpreter/executors/opcodes_impl.rs#L2853-L2856

This is intentional and not a real concern

Dentosal · 2026-02-12T18:16:12Z

Gas cost comparison from the latest benchmark run versus existing cost of non-dynamic operations. I'm only comparing read operations here, because the database read cost completely dominates the costs; writing is almost free except that we need to read the value anyway to charge for new bytes written. Read costs:

Using srwq: 520 gas per 32 byte slot.

Using srdd: 2593 gas per op, plus 38 bytes for each gas.

Meaning that if you're able to combine at least six slots, dynamic ops are cheaper for reading.

## Linked Issues/PRs FuelLabs/fuel-vm#982 ## Description Adds support and benchmarks for fuel-vm dynamic storage opcodes. ## Checklist - [x] Breaking changes are clearly marked as such in the PR description and changelog (None!) - [x] New behavior is reflected in tests - [x] [The specification](https://github.com/FuelLabs/fuel-specs/) matches the implemented behavior (link update PR if changes are needed) ### Before requesting review - [x] I have reviewed the code myself - [x] I have created follow-up issues caused by this PR and linked them here --------- Co-authored-by: Green Baneling <XgreenX9999@gmail.com>

Discussed in #517. VM impl PR: FuelLabs/fuel-vm#982 Adds a minimal set of opcodes required to operate with dynamic (variable-sized) storage slots. More instructions can be added later to speed up common operations, as discussed in #517. This PR marks sequential bulk read and write opcodes as deprecated. There's no process for actually removing opcodes, but simply including DEPRECATED in the heading informs readers that they ought to be careful. Most imporatantly, the sequential read opcode now panics if attempting to read slots with size other than 32 bytes. The sequential clear instuction still works as expected and is kept as-is. The PR also clarifies how the old storarge instructions interact with variable sized slots. ### Before requesting review - [x] I have reviewed the code myself --------- Co-authored-by: Brandon Kite <brandonkite92@gmail.com> Co-authored-by: Igor Rončević <ironcev@hotmail.com>

Impl dynamic storage (WIP)

9f2f52a

Dentosal self-assigned this Jan 5, 2026

Dentosal added 10 commits January 6, 2026 08:58

Add full opcode impls

e4bfbbf

Add storage slot max length limit

6f1045f

Add test case for srw offsets

96d00c9

Add tests for storage key read overflow

f13c175

Add changelog entries

996cded

Add SCLR happy path test

f4ad53e

Add SRDD/SRDI test cases

be9257c

Add SWRD/SWRI test cases

78c1d4c

Add tests for SUPD/SUPI

6e989d5

Add tests for SPLD and SPCP

3594710

Dentosal marked this pull request as ready for review January 12, 2026 12:15

Dentosal requested review from MitchTurner, Voxelot and xgreenx as code owners January 12, 2026 12:15

Dentosal added 2 commits January 12, 2026 14:18

Clippy

e83182a

Update check_predicate_allowed test

e8dadfa

cursor Bot reviewed Jan 12, 2026

View reviewed changes

Comment thread fuel-vm/src/interpreter/memory.rs

Comment thread fuel-vm/src/interpreter/memory.rs

Comment thread fuel-vm/src/interpreter/blockchain.rs Outdated

Make tests no_std compatible

4227ffb

Dentosal mentioned this pull request Jan 12, 2026

Dynamic storage opcodes: base instructions FuelLabs/fuel-specs#640

Merged

1 task

xgreenx reviewed Jan 14, 2026

View reviewed changes

Dentosal added 3 commits January 14, 2026 16:33

Require exact 32 byte slots for SRWQ

9c8f7cd

Fix SPCP off-by-one check bug

303c3c6

Name unpacked operands

eec4b1d

cursor Bot reviewed Jan 14, 2026

View reviewed changes

Comment thread fuel-vm/src/interpreter/storage.rs Outdated

Dentosal added 2 commits January 14, 2026 17:15

Remove extra vec creation

f07f99e

Check size before allocating

a00f21a

Dentosal requested a review from xgreenx January 16, 2026 14:23

Dentosal added 3 commits January 27, 2026 14:42

Replace currently unreachable todo with valid impl

7a2f8f7

Add default gas costs

204c52a

Fix no_std

3fd99d5

cursor Bot reviewed Feb 6, 2026

View reviewed changes

Fix preload tests

b55b520

Voxelot reviewed Feb 7, 2026

View reviewed changes

MitchTurner reviewed Feb 8, 2026

View reviewed changes

Dentosal added 3 commits February 9, 2026 12:59

Address some PR comments

6d9e197

Rename verify_storage_size -> verify_storage_smaller_than_max

5bd3f4a

Use intermediate variable to clarify read operation result match

e93e28e

cleanup

39a3cfa

cursor Bot reviewed Feb 9, 2026

View reviewed changes

MitchTurner previously approved these changes Feb 9, 2026

View reviewed changes

Improve gas charging of storage_update_from_memory

0fb12cf

Dentosal dismissed MitchTurner’s stale review via 0fb12cf February 12, 2026 09:54

Dentosal requested a review from MitchTurner February 12, 2026 09:55

cursor Bot reviewed Feb 12, 2026

View reviewed changes

Dentosal enabled auto-merge February 12, 2026 16:12

Dentosal disabled auto-merge February 12, 2026 17:55

MitchTurner approved these changes Feb 12, 2026

View reviewed changes

Dentosal added this pull request to the merge queue Feb 12, 2026

Merged via the queue into master with commit ec7761c Feb 12, 2026
45 of 46 checks passed

Dentosal deleted the dento/dynamic-storage branch February 12, 2026 18:21

Dentosal mentioned this pull request Feb 26, 2026

Dynamic storage: Charge gas for new bytes properly #989

Closed

6 tasks

github-actions Bot mentioned this pull request Mar 10, 2026

Release 0.66.0 #997

Merged

Uh oh!

Conversation

Dentosal commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Before requesting review

Uh oh!

cursor Bot commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot Feb 6, 2026

Choose a reason for hiding this comment

Stale data in preload area after failed SPLD

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MitchTurner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Dentosal commented Jan 5, 2026 •

edited

Loading

cursor Bot commented Jan 12, 2026 •

edited

Loading

Dentosal commented Feb 9, 2026 •

edited

Loading