Dynamic storage opcodes: base instructions

[Dentosal]

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

• I have reviewed the code myself

[cursor]

PR Summary

Medium Risk
Specification-only changes, but they redefine contract state instruction semantics (including new panic conditions) and add new opcodes/consensus parameter docs, which can affect implementers and tooling if misinterpreted.

Overview
Documents the new dynamic (variable-sized) contract storage slot instruction set, adding SCLR, SRDD/SRDI, SWRD/SWRI, SUPD/SUPI, and SPLD, plus updated semantics for SRW to support word reads at an offset.

Marks legacy bulk 32-byte slot ops (SCWQ, SRWQ, SWWQ) as DEPRECATED and clarifies their behavior/limitations with variable-sized slots (notably new panics when slot sizes don’t match expectations). Also adds a short spec note that storage accesses are cached across contract call boundaries, and introduces the MAX_STORAGE_SLOT_LENGTH consensus parameter plus a few new spellcheck dictionary entries.

^{Reviewed by Cursor Bugbot for commit 73e150b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Dentosal]

Meeting notes 2025-12-17:

• Use $err to signal errors instead of a status output register (new opcodes only, of course)
• Change SLEN to load the value to a "staging area", add separate opcodes to memcopy from it
• Remove write status
• New storage clear opcode without status
• Document the slot size limit
• SRW: add immediate offset
• Buffer extend support to SUPD/SUPI

I'll update the PR to include these.

[ironcev]

👍

[cursor]

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

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: SRDI panic condition references wrong register
  • Updated the SRDI panic bound check to use STATE[MEM[$rB, 32]], matching the instruction operation and SRDD behavior.

Or push these changes by commenting:

@cursor push 6123ebaf91

Preview (6123ebaf91)

diff --git a/src/fuel-vm/instruction-set.md b/src/fuel-vm/instruction-set.md
--- a/src/fuel-vm/instruction-set.md
+++ b/src/fuel-vm/instruction-set.md
@@ -2425,7 +2425,7 @@
 - `$rB + 32` overflows or `> VM_MAX_RAM`
 - `$rA + imm` overflows or `> VM_MAX_RAM`
 - The memory range `MEM[$rA, imm]` does not pass [ownership check](./index.md#ownership)
-- `$rC + imm` overflows or `> len(STATE[MEM[$rC, 32]])`
+- `$rC + imm` overflows or `> len(STATE[MEM[$rB, 32]])`
 - `$fp == 0` (in the script context)
 
 Register `$err` will be set to `1` if the slot did not exist, and `0` otherwise. If the slot didn't exist, memory is not modified.

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

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

^{Reviewed by Cursor Bugbot for commit 36b4bf3. Configure here.}