From b2937d7c80d3724dfbc8e707abf28756d4a21a66 Mon Sep 17 00:00:00 2001
From: Dhaiwat <dhaiwatpandya@gmail.com>
Date: Tue, 25 Jul 2023 19:06:27 +0530
Subject: [PATCH] docs: add docs around custom storage slots (#1126)

* docs: add docs around custom storage slots

* fix import

* fix incorrect path
---
 .changeset/quiet-eggs-fetch.md                |  2 +
 apps/docs/.vitepress/config.ts                |  4 ++
 .../docs/src/guide/contracts/storage-slots.md | 11 ++++
 .../src/storage-test-contract.test.ts         | 53 +++++++++++++++++--
 4 files changed, 67 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/quiet-eggs-fetch.md
 create mode 100644 apps/docs/src/guide/contracts/storage-slots.md

diff --git a/.changeset/quiet-eggs-fetch.md b/.changeset/quiet-eggs-fetch.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/quiet-eggs-fetch.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/apps/docs/.vitepress/config.ts b/apps/docs/.vitepress/config.ts
index 3292413f207..51991ba0c93 100644
--- a/apps/docs/.vitepress/config.ts
+++ b/apps/docs/.vitepress/config.ts
@@ -243,6 +243,10 @@ export default defineConfig({
                 text: 'Configurable Constants',
                 link: '/guide/contracts/configurable-constants',
               },
+              {
+                text: 'Storage Slots',
+                link: '/guide/contracts/storage-slots',
+              },
               {
                 text: 'Logs',
                 link: '/guide/contracts/logs',
diff --git a/apps/docs/src/guide/contracts/storage-slots.md b/apps/docs/src/guide/contracts/storage-slots.md
new file mode 100644
index 00000000000..c544562e20c
--- /dev/null
+++ b/apps/docs/src/guide/contracts/storage-slots.md
@@ -0,0 +1,11 @@
+# Storage Slots
+
+When deploying a contract, you can specify the custom storage slots that you want to use.
+
+<<< @/../../../packages/fuel-gauge/src/storage-test-contract.test.ts#contract-deployment-storage-slots{ts:line-numbers}
+
+In the above example, we directly imported the storage slots from a JSON file generated by the Sway compiler.
+
+Instead of importing from a file, you can also specify the custom storage slots directly in your code:
+
+<<< @/../../../packages/fuel-gauge/src/storage-test-contract.test.ts#contract-deployment-storage-slots-inline{ts:line-numbers}
diff --git a/packages/fuel-gauge/src/storage-test-contract.test.ts b/packages/fuel-gauge/src/storage-test-contract.test.ts
index e9aa025840a..a305e485731 100644
--- a/packages/fuel-gauge/src/storage-test-contract.test.ts
+++ b/packages/fuel-gauge/src/storage-test-contract.test.ts
@@ -6,19 +6,26 @@ import { join } from 'path';
 import abi from '../fixtures/forc-projects/storage-test-contract/out/debug/storage-test-abi.json';
 import storageSlots from '../fixtures/forc-projects/storage-test-contract/out/debug/storage-test-storage_slots.json';
 
+const binPath = join(
+  __dirname,
+  '../fixtures/forc-projects/storage-test-contract/out/debug/storage-test.bin'
+);
+
 const setup = async () => {
   const provider = new Provider('http://127.0.0.1:4000/graphql');
   // Create wallet
   const wallet = await generateTestWallet(provider, [[1_000, BaseAssetId]]);
 
   // Deploy contract
-  const bytecode = readFileSync(
-    join(__dirname, '../fixtures/forc-projects/storage-test-contract/out/debug/storage-test.bin')
-  );
+  const bytecode = readFileSync(binPath);
+  // #region contract-deployment-storage-slots
+  // #context import storageSlots from '../your-sway-project/out/debug/your-sway-project-storage_slots.json';
+
   const factory = new ContractFactory(bytecode, abi, wallet);
   const contract = await factory.deployContract({
     storageSlots,
   });
+  // #endregion contract-deployment-storage-slots
 
   return contract;
 };
@@ -36,4 +43,44 @@ describe('StorageTestContract', () => {
     const { value: count } = await contract.functions.counter().get();
     expect(count.toHex()).toEqual(toHex(1337));
   });
+
+  it('can increment counter - using custom inline storage slots', async () => {
+    const provider = new Provider('http://127.0.0.1:4000/graphql');
+    const wallet = await generateTestWallet(provider, [[1_000, BaseAssetId]]);
+    const bytecode = readFileSync(binPath);
+    const factory = new ContractFactory(bytecode, abi, wallet);
+    // #region contract-deployment-storage-slots-inline
+    const contract = await factory.deployContract({
+      storageSlots: [
+        {
+          key: '02dac99c283f16bc91b74f6942db7f012699a2ad51272b15207b9cc14a70dbae',
+          value: '0000000000000001000000000000000000000000000000000000000000000000',
+        },
+        {
+          key: '6294951dcb0a9111a517be5cf4785670ff4e166fb5ab9c33b17e6881b48e964f',
+          value: '0000000000000001000000000000003200000000000000000000000000000000',
+        },
+        {
+          key: 'b48b753af346966d0d169c0b2e3234611f65d5cfdb57c7b6e7cd6ca93707bee0',
+          value: '000000000000001e000000000000000000000000000000000000000000000000',
+        },
+        {
+          key: 'de9090cb50e71c2588c773487d1da7066d0c719849a7e58dc8b6397a25c567c0',
+          value: '0000000000000014000000000000000000000000000000000000000000000000',
+        },
+        {
+          key: 'f383b0ce51358be57daa3b725fe44acdb2d880604e367199080b4379c41bb6ed',
+          value: '000000000000000a000000000000000000000000000000000000000000000000',
+        },
+      ],
+    });
+    // #endregion contract-deployment-storage-slots-inline
+    const { value: initializeResult } = await contract.functions.initialize_counter(1300).call();
+    expect(initializeResult.toHex()).toEqual(toHex(1300));
+    const { value: incrementResult } = await contract.functions.increment_counter(37).call();
+    expect(incrementResult.toHex()).toEqual(toHex(1337));
+
+    const { value: count } = await contract.functions.counter().get();
+    expect(count.toHex()).toEqual(toHex(1337));
+  });
 });