@mysten/move-bytecode-template
v0.1.0
Published
WASM variant of the move-binary-format which allows bytecode templates
Downloads
372
Keywords
Readme
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 Sui 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 Move by Example book.
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 = 0;
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.
import { fromHEX, update_identifiers } from '@mysten/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).
import * as template from '@mysten/move-bytecode-template';
import { bcs } from '@mysten/bcs';
// 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.vector(bcs.string()).serialize('MYC').toBytes(), // new value
bcs.vector(bcs.string()).serialize('TMPL').toBytes(), // current value
'Vector(U8)', // type of the constant
);
// Update NAME
updated = update_constants(
updated,
bcs.vector(bcs.string()).serialize('My Coin').toBytes(), // new value
bcs.vector(bcs.string()).serialize('Template Coin').toBytes(), // current value
'Vector(U8)', // type of the constant
);
Usage in Web applications
The package consists of code and a wasm binary. While the former can be imported directly, the latter should be made available in static / public assets as a Web application. Initialization needs to be performed via a URL, and once completed, other functions become available.
import init, initSync, * as template from '@mysten/move-bytecode-template';
await init('path/to/move_binary_format_bg.wasm');
// alternatively initSync(...);
let version = template.version();
let json = template.deserialize(fromHEX('a11ceb0b06....'));
let bytes = template.serialize(json);
console.assert(json == bytes, '(de)serialization failed!');
Using with Vite
To use this package with Vite, you need to import the source file and the wasm binary.
import init, * as template from "@mysten/move-bytecode-template";
import url from '@mysten/move-bytecode-template/move_bytecode_template_bg.wasm?url';
Later, you can initialize the package with the URL.
await init(url);
Lastly, once the package is initialized, you can use the functions as described in the previous section.
const templateBytecode = fromHEX("a11ceb0b06....");
template.deserialize(templateBytecode);
template.version();
template.update_identifiers(templateBytecode, {
"TEMPLATE": "MY_MODULE",
"template": "my_module"
});
Build locally
To build the binary, you need to have Rust installed and then the wasm-pack
. The installation script can be found here.
Building for test (nodejs) environment - required for tests.
pnpm build:dev
Building for web environment.
pnpm build:release
Running tests
Local tests can only be run on the dev
build. To run tests, follow these steps:
pnpm build:dev
pnpm test