@haneullabs/move-bytecode-template 0.1.0

package/README.md

@@ -0,0 +1,175 @@
+# Move Bytecode Template
+
+Move Bytecode Template allows updating a pre-compiled bytecode, so that a standard template could be
+customized and used to publish new modules on Haneul directly in the browser. Hence, removing the need
+for a backend to compile new modules.
+
+This crate builds a WASM binary for the `move-language/move-binary-format` allowing bytecode
+serialization and deserialization in various environments. The main target for this package is
+"web".
+
+## Applications
+
+This package is a perfect fit for the following applications:
+
+- Publishing new Coins
+- Publishing TransferPolicies
+- Initializing any base type with a custom sub-type
+
+## Example of a Template Module
+
+The following code is a close-copy of the `Coin` example from the
+[Coins and Tokens](https://docs.sui.io/standards/currency).
+
+```move
+module 0x0::template {
+    use std::option;
+    use sui::coin;
+    use sui::transfer;
+    use sui::tx_context::{Self, TxContext};
+
+    /// The OTW for the Coin
+    struct TEMPLATE has drop {}
+
+    const DECIMALS: u8 = 6;
+    const SYMBOL: vector<u8> = b"TMPL";
+    const NAME: vector<u8> = b"Template Coin";
+    const DESCRIPTION: vector<u8> = b"Template Coin Description";
+
+    /// Init the Coin
+    fun init(witness: TEMPLATE, ctx: &mut TxContext) {
+        let (treasury, metadata) = coin::create_currency(
+            witness, DECIMALS, SYMBOL, NAME, DESCRIPTION, option::none(), ctx
+        );
+
+        transfer::public_transfer(treasury, tx_context::sender(ctx));
+        transfer::public_transfer(metadata, tx_context::sender(ctx));
+    }
+}
+```
+
+To update the identifiers, you can use the `update_identifiers` function.
+
+```ts
+import { fromHex, update_identifiers } from '@haneullabs/move-bytecode-template';
+
+let bytecode = /* ... */;
+let updated = update_identifiers(bytecode, {
+    "TEMPLATE": "MY_MODULE",
+    "template": "my_module"
+});
+
+console.assert(updated != bytecode, 'identifiers were not updated!');
+```
+
+To update constants in the bytecode, you can use the `update_constants` function. For each constant
+you need to supply new value as BCS bytes, existing value as BCS, and the type of the constant (as a
+string: `U8`, `U16` ... `U256`, `Address`, `Vector(U8)` and so on).
+
+```ts
+import { bcs } from '@haneullabs/bcs';
+import * as template from '@haneullabs/move-bytecode-template';
+
+// please, manually scan the existing values, this operation is very sensitive
+console.log(template.get_constants(bytecode));
+
+let updated;
+
+// Update DECIMALS
+updated = update_constants(
+	bytecode,
+	bcs.u8().serialize(3).toBytes(), // new value
+	bcs.u8().serialize(6).toBytes(), // current value
+	'U8', // type of the constant
+);
+
+// Update SYMBOL
+updated = update_constants(
+	updated,
+	bcs.string().serialize('MYC').toBytes(), // new value
+	bcs.string().serialize('TMPL').toBytes(), // current value
+	'Vector(U8)', // type of the constant
+);
+
+// Update NAME
+updated = update_constants(
+	updated,
+	bcs.string().serialize('My Coin').toBytes(), // new value
+	bcs.string().serialize('Template Coin').toBytes(), // current value
+	'Vector(U8)', // type of the constant
+);
+```
+
+After updating the bytecode, refer to the
+[Asset Tokenization](https://docs.sui.io/guides/developer/nft/asset-tokenization#closer-view-of-the-template-module)
+guide to deploy the contract.
+
+## Usage in Web applications
+
+In some bundler and web applications you will need to set up and initialize the wasm bindings. The
+exact requirements depend on how your application is being built.
+
+The `@haneullabs/move-bytecode-template` has 2 relevant exports you might need to get things working
+correctly.
+
+- `init` is an exported function that initializes the wasm module in browser environments (a no-op
+  function is exported when running in node so you can use this anywhere)
+- `/web/walrus_wasm_bg.wasm` is an export of the wasm module itself, which may be needed in some
+  bundlers to know where to import the wasm module from
+
+### Initializing in webpack and nodejs
+
+In webpack and nodejs you should be able to initialize the wasm module without specifying the
+location of the wasm module:
+
+```ts
+import init, * as template from '@haneullabs/move-bytecode-template';
+
+await init();
+
+const json = template.deserialize(fromHex('a11ceb0b06....'));
+const bytes = template.serialize(json);
+```
+
+## Vite
+
+In vite (and some other bundlers) you may need to disable certain optimizations so the wasm module
+can be loaded correctly. You can add something like this to your vite config:
+
+```ts
+export default defineConfig({
+	optimizeDeps: {
+		exclude: ["@haneullabs/move-bytecode-template"],
+	},
+});
+```
+
+## Initializing wasm with a url
+
+If initialization fails without the url, you may need to specify a url where the wasm module can be
+loaded. Some bundlers support a `?url` suffix for imports that will return a url where the resource
+can be loaded from:
+
+```ts
+import init, * as template from '@haneullabs/move-bytecode-template';
+import url from '@haneullabs/move-bytecode-template/web/move_bytecode_template_bg.wasm?url';
+
+await init({ module_or_path: url });
+```
+
+## Build locally
+
+To build the binary, you need to have Rust installed and then the `wasm-pack`. The installation
+script [can be found here](https://github.com/rustwasm/wasm-pack).
+
+```
+pnpm build:wasm
+```
+
+## Running tests
+
+After building tests can be run with
+
+```
+pnpm test
+```

package/index.js

@@ -0,0 +1,7 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+const wasm = require('./nodejs/move_bytecode_template.js');
+function init() {}
+module.exports = init;
+Object.assign(module.exports, wasm, { default: init });

package/index.mjs

@@ -0,0 +1,5 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export * from './nodejs/move_bytecode_template.js';
+export default function init() {}

package/nodejs/move_bytecode_template.d.ts

@@ -0,0 +1,76 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Get the version of the crate (useful for testing the package).
+ */
+export function version(): string;
+/**
+ * Deserialize the `Uint8Array`` bytecode into a JSON object.
+ * The JSON object contains the ABI (Application Binary Interface) of the module.
+ *
+ * ```javascript
+ * import * as template from '@haneullabs/move-binary-template';
+ *
+ * const json = template.deserialize( binary );
+ * console.log( json, json.identifiers );
+ * ```
+ */
+export function deserialize(binary: Uint8Array): any;
+/**
+ * Update the identifiers in the module bytecode, given a map of old -> new identifiers.
+ * Returns the updated bytecode.
+ *
+ * ```javascript
+ * import * as template from '@haneullabs/move-binary-template';
+ *
+ * const updated = template.update_identifiers( binary, {
+ *     'TEMPLATE': 'NEW_VALUE',
+ *     'template': 'new_value',
+ *     'Name':     'NewName'
+ * });
+ * ```
+ */
+export function update_identifiers(binary: Uint8Array, map: any): Uint8Array;
+/**
+ * Updates a constant in the constant pool. Because constants don't have names,
+ * the only way to identify them is by their type and value.
+ *
+ * The value of a constant is BCS-encoded and the type is a string representation
+ * of the `SignatureToken` enum. String identifier for `SignatureToken` is a
+ * capitalized version of the type: U8, Address, Vector(Bool), Vector(U8), etc.
+ *
+ * ```javascript
+ * import * as template from '@haneullabs/move-binary-template';
+ * import { bcs } from '@haneullabs/bcs';
+ *
+ * let binary = template.update_constants(
+ *     binary, // Uint8Array
+ *     bcs.u64().serialize(0).toBytes(),      // new value
+ *     bcs.u64().serialize(100000).toBytes(), // old value
+ *     'U64'                                  // type
+ * );
+ * ```
+ */
+export function update_constants(binary: Uint8Array, new_value: Uint8Array, expected_value: Uint8Array, expected_type: string): Uint8Array;
+/**
+ * Convenience method to analyze the constant pool; returns all constants in order
+ * with their type and BCS value.
+ *
+ * ```javascript
+ * import * as template from '@haneullabs/move-binary-template';
+ *
+ * let consts = template.get_constants(binary);
+ * ```
+ */
+export function get_constants(binary: Uint8Array): any;
+/**
+ * Serialize the JSON module into a `Uint8Array` (bytecode).
+ */
+export function serialize(json_module: any): Uint8Array;
+/**
+ * A transformed constant from the constant pool.
+ */
+export class Constant {
+  private constructor();
+  free(): void;
+}