feat: re-exporting @fuels/vm-asm as FuelAsm from fuels (#3866)

arboleya · web-flow · commit 640d6131e5b2 · 2025-04-25T16:27:19.000-03:00
* Re-exporting [wrapped] `FuelAsm` from within main `fuels` entrypoint

* Improving demo apps to included wrapped `FuelAsm` for validation purposes

* Adding docs

* Adding changeset

* Adding new words to spell check dictionary

* Moving nested gitignore rules upward

* Adjusting titles

* Ignoring crate link, for some reason it always return 404 for the workflow

* Moving rust [excample] project outside `src` dir

* Fixing snippet path

* Fixing example description
diff --git a/.changeset/cold-ants-notice.md b/.changeset/cold-ants-notice.md
@@ -0,0 +1,5 @@
+---
+"fuels": patch
+---
+
+feat: re-exporting `@fuels/vm-asm` as `FuelAsm` from `fuels`
diff --git a/apps/demo-nextjs/src/app/page.tsx b/apps/demo-nextjs/src/app/page.tsx
@@ -1,5 +1,5 @@
 import * as asm from "@fuels/vm-asm";
-import { ZeroBytes32, decrypt, encrypt } from "fuels";
+import { ZeroBytes32, decrypt, encrypt, FuelAsm } from "fuels";
 import Image from "next/image";
 
 import styles from "./page.module.css";
@@ -8,7 +8,8 @@ export default function Home() {
   const { log } = console;
 
   log("Hello Fuels", ZeroBytes32, encrypt, decrypt);
-  log("Hello ASM", asm);
+  log("Hello ASM:standalone", asm);
+  log("Hello ASM:wrapped", FuelAsm);
 
   return (
     <main className={styles.main}>
diff --git a/apps/demo-react-cra/src/App.tsx b/apps/demo-react-cra/src/App.tsx
@@ -1,14 +1,14 @@
-import React from "react";
 import logo from "./logo.svg";
 import "./App.css";
-import { ZeroBytes32, encrypt, decrypt, bn } from "fuels";
+import { ZeroBytes32, encrypt, decrypt, bn, FuelAsm } from "fuels";
 import * as asm from "@fuels/vm-asm";
 
 function App() {
   const { log } = console;
 
   log("Hello Fuels", ZeroBytes32, encrypt, decrypt);
-  log("Hello ASM", asm);
+  log("Hello ASM:standalone", asm);
+  log("Hello ASM:wrapped", FuelAsm);
   log("Hello BN", bn(1000));
 
   return (
diff --git a/apps/demo-react-vite/src/App.tsx b/apps/demo-react-vite/src/App.tsx
@@ -4,15 +4,16 @@ import viteLogo from "/vite.svg";
 import "./App.css";
 
 import * as asm from "@fuels/vm-asm";
-import { ZeroBytes32, encrypt, decrypt } from "fuels";
+import { ZeroBytes32, encrypt, decrypt, FuelAsm } from "fuels";
 
 function App() {
   const [count, setCount] = useState(0);
 
   const { log } = console;
 
   log("Hello Fuels", ZeroBytes32, encrypt, decrypt);
-  log("Hello ASM", asm);
+  log("Hello ASM:standalone", asm);
+  log("Hello ASM:wrapped", FuelAsm);
 
   return (
     <>
diff --git a/apps/docs/.gitignore b/apps/docs/.gitignore
@@ -3,4 +3,5 @@
 
 src/typegend
 src/guide/**/*.test.ts
+
 .fuels/
diff --git a/apps/docs/.vitepress/config.ts b/apps/docs/.vitepress/config.ts
@@ -596,6 +596,12 @@ export default defineConfig({
             collapsed: false,
             items: [],
           },
+          {
+            text: 'Fuel ASM',
+            link: '/guide/fuel-asm/',
+            collapsed: false,
+            items: [],
+          },
         ],
       },
     ],
diff --git a/apps/docs/fuel-asm-example/.gitignore b/apps/docs/fuel-asm-example/.gitignore
@@ -0,0 +1 @@
+target
diff --git a/apps/docs/fuel-asm-example/Cargo.lock b/apps/docs/fuel-asm-example/Cargo.lock
diff --git a/apps/docs/fuel-asm-example/Cargo.toml b/apps/docs/fuel-asm-example/Cargo.toml
@@ -0,0 +1,8 @@
+[package]
+name = "original-example"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.85.0"
+
+[dependencies]
+fuel-asm = "0.60.2"
diff --git a/apps/docs/fuel-asm-example/src/main.rs b/apps/docs/fuel-asm-example/src/main.rs
@@ -0,0 +1,23 @@
+// #region main
+use fuel_asm::*;
+
+fn main() {
+
+  let program = vec![
+    op::move_(0x10, 0x01),      // set r[0x10] := $one
+    op::slli(0x20, 0x10, 5),    // set r[0x20] := `r[0x10] << 5 == 32`
+    op::slli(0x21, 0x10, 6),    // set r[0x21] := `r[0x10] << 6 == 64`
+    op::aloc(0x21),             // alloc `r[0x21] == 64` to the heap
+    op::addi(0x10, 0x07, 1),    // set r[0x10] := `$hp + 1` (allocated heap)
+    op::move_(0x11, 0x04),      // set r[0x11] := $ssp
+    op::add(0x12, 0x04, 0x20),  // set r[0x12] := `$ssp + r[0x20]`
+    op::eck1(0x10, 0x11, 0x12), // recover public key in memory[r[0x10], 64]
+    op::ret(0x01),              // return `1`
+  ];
+
+  let bytes: Vec<u8> = program.iter().copied().collect();
+
+  println!("Bytes: {:#?}", bytes);
+
+}
+// #endregion main
diff --git a/apps/docs/spell-check-custom-words.txt b/apps/docs/spell-check-custom-words.txt
@@ -351,3 +351,8 @@ AssembleTxResponse
 AssembleTx
 Unparsed
 zero'd
+asm
+io
+asm
+github
+vm
diff --git a/apps/docs/src/guide/fuel-asm/index.md b/apps/docs/src/guide/fuel-asm/index.md
@@ -0,0 +1,28 @@
+# Fuel ASM
+
+Instruction set for the [FuelVM](https://github.com/FuelLabs/fuel-specs).
+
+---
+
+This is a wrapped WASM version of the [`fuel-asm`](https://crates.io/crates/fuel-asm) Rust crate:
+
+- https://crates.io/crates/fuel-asm
+- https://github.com/FuelLabs/fuel-vm/tree/master/fuel-asm
+
+## Usage
+
+This example demonstrates how to use the `FuelAsm` to create a program, represented as a vector of instructions, and then convert it to bytes.
+
+<<< @./snippets/fuel-asm.ts#main{ts:line-numbers}
+
+## Reference
+
+The above usage is the `Typescript` equivalent of the [original example](https://crates.io/crates/fuel-asm) in `Rust`.
+
+<<< @../../../../fuel-asm-example/src/main.rs#main{rs:line-numbers}
+
+## See Also
+
+- [FuelVM Specs](https://docs.fuel.network/docs/specs/fuel-vm/instruction-set/)
+- [FuelVM Semantics](https://docs.fuel.network/docs/specs/fuel-vm/#semantics)
+- [Inline Assembly in Sway](https://docs.fuel.network/docs/sway/advanced/assembly)
diff --git a/apps/docs/src/guide/fuel-asm/snippets/fuel-asm.ts b/apps/docs/src/guide/fuel-asm/snippets/fuel-asm.ts
@@ -0,0 +1,20 @@
+// #region main
+import { FuelAsm } from 'fuels';
+
+// @ts-expect-error method reference missing in DTS
+await FuelAsm.initWasm();
+
+const programBytes = Uint8Array.from([
+  ...FuelAsm.move_(0x10, 0x01).to_bytes(), // set r[0x10] := $one
+  ...FuelAsm.slli(0x20, 0x10, 5).to_bytes(), // set r[0x20] := `r[0x10] << 5 == 32`
+  ...FuelAsm.slli(0x21, 0x10, 6).to_bytes(), // set r[0x21] := `r[0x10] << 6 == 64`
+  ...FuelAsm.aloc(0x21).to_bytes(), // alloc `r[0x21] == 64` to the heap
+  ...FuelAsm.addi(0x10, 0x07, 1).to_bytes(), // set r[0x10] := `$hp + 1` (allocated heap)
+  ...FuelAsm.move_(0x11, 0x04).to_bytes(), // set r[0x11] := $ssp
+  ...FuelAsm.add(0x12, 0x04, 0x20).to_bytes(), // set r[0x12] := `$ssp + r[0x20]`
+  ...FuelAsm.eck1(0x10, 0x11, 0x12).to_bytes(), // recover public key in memory[r[0x10], 64]
+  ...FuelAsm.ret(0x01).to_bytes(), // return `1`
+]);
+
+console.log('Bytes', programBytes);
+// #endregion main
diff --git a/link-check.config.json b/link-check.config.json
@@ -13,6 +13,9 @@
     },
     {
       "pattern": "https://explorer-indexer-testnet.fuel.network"
+    },
+    {
+      "pattern": "https://crates.io/crates/fuel-asm"
     }
   ],
   "replacementPatterns": [
diff --git a/packages/fuels/package.json b/packages/fuels/package.json
@@ -62,6 +62,7 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
+    "@fuels/vm-asm": "0.60.2",
     "@fuel-ts/abi-coder": "workspace:*",
     "@fuel-ts/abi-typegen": "workspace:*",
     "@fuel-ts/account": "workspace:*",
diff --git a/packages/fuels/src/index.ts b/packages/fuels/src/index.ts
@@ -1,6 +1,14 @@
-export { Script } from '@fuel-ts/script';
+// exporting wrapped `@fuels/vm-asm` for convenience
+export * as FuelAsm from '@fuels/vm-asm';
+
+// Exporting CLI entrypoint for programatic API
 export * from './cli/index';
+
+// Exporting all sub-packages
+export { Script } from '@fuel-ts/script';
 export * from '@fuel-ts/abi-coder';
+export * from '@fuel-ts/account';
+export * from '@fuel-ts/account/configs';
 export * from '@fuel-ts/address';
 export * from '@fuel-ts/address/configs';
 export * from '@fuel-ts/contract';
@@ -10,9 +18,7 @@ export * from '@fuel-ts/hasher';
 export * from '@fuel-ts/math';
 export * from '@fuel-ts/math/configs';
 export * from '@fuel-ts/program';
+export * from '@fuel-ts/recipes';
 export * from '@fuel-ts/transactions';
-export * from '@fuel-ts/utils';
-export * from '@fuel-ts/account';
 export * from '@fuel-ts/transactions/configs';
-export * from '@fuel-ts/account/configs';
-export * from '@fuel-ts/recipes';
+export * from '@fuel-ts/utils';
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"fuels": patch
 +---
++
 +feat: re-exporting `@fuels/vm-asm` as `FuelAsm` from `fuels`