hello_wasm.code

Overview

The hello_wasm.code file contains the low-level code fragments and logic for a smart contract module implemented in a stack-based, assembly-like language, likely for blockchain virtual machine execution. It manages contract lifecycle events such as deployment, token exchange, message handling, and state updates while providing interaction mechanisms with external contracts and WASM execution. The file defines reusable code fragments representing internal procedures, external entry points, and utility methods for contract operations.

Core Functionalities

• Contract Initialization and Deployment: Handles creation of contract instances and deployment of new contracts.

• Token Management: Functions to mint and exchange tokens within the contract context.

• WASM Execution: Supports running WASM code with varying argument structures.

• Message Handling: Processing of incoming messages, external touches, and internal state updates.

• Time and State Management: Updates timestamp fields and manages replay protection.

• Shell and VM Shell Messaging: Sending raw and VM shell messages for contract interactions.

• Function Dispatching: Selects public functions based on incoming function selectors.

Detailed Fragment Descriptions

Fragment: constructor

• Purpose: Initializes a new contract instance.

• Key operations:

  • Checks if an internal data structure is null and sets it if necessary.

  • Validates permissions via global variables.

  • Converts and processes the initial token supply.

  • Accepts the message and records the current timestamp.

  • Updates global state with new contract data.

• Parameters: Implicitly uses global variables for initialization context.

• Return: None (contract initialization).

• Usage: Called automatically on contract deployment.

Fragment: deployNewContract

• Purpose: Deploys a new contract instance from within the current contract.

• Internal Fragment: deployNewContract_e6e22826_internal

• Key operations:

  • Accepts the incoming message.

  • Obtains tokens through internal calls.

  • Constructs a new contract cell with hashed tokens and associated parameters.

  • Sends a raw message to deploy the new contract.

• Parameters: Uses global state and message slices.

• Return: None.

• Usage: Invoked to spawn new contract instances dynamically.

Fragment: exchangeToken

• Purpose: Handles token exchange transactions.

• Internal Fragment: exchangeToken_53d168e3_internal

• Key operations:

  • Accepts the message.

  • Uses internal token retrieval logic.

  • Converts tokens to shell quantity format.

• Parameters: Uses the message context and global state.

• Return: None.

• Usage: Called when an exchange token operation is requested.

Fragment: runWasm

• Purpose: Executes WASM code embedded or referenced by the contract.

• Internal Fragment: runWasm_449543f3_internal

• Key operations:

  • Retrieves tokens.

  • Creates multiple new cells storing function arguments and state.

  • Executes WASM code using the RUNWASM opcode.

  • Commits changes and prints a status string.

  • Updates global state with execution results.

• Parameters: Utilizes global state and message slices.

• Return: Execution result is committed and printed.

• Usage: Called when WASM execution is requested.

Fragment: runWasmConcatMultiarg

• Purpose: Executes WASM code with multiple concatenated arguments.

• Internal Fragment: runWasmConcatMultiarg_be417fbd_internal

• Key operations:

  • Similar to runWasm but handles more arguments.

  • Uses RUNWASMCONCATMULTIARG opcode for multi-argument WASM runs.

• Parameters: Global state and message slices.

• Return: Result committed and printed.

• Usage: For invoking WASM code requiring multiple concatenated inputs.

Fragment: sendShell and sendVMShell

• Purpose: Sends raw shell messages or VM shell messages.

• Internal Fragments: sendShell_77e2a3b5_internal, sendVMShell_e1519e7b_internal

• Key operations:

  • Validates sender against global state.

  • Accepts the message and obtains tokens.

  • Constructs message cells with specific constants and parameters.

  • Sends raw messages using SENDRAWMSG.

• Parameters: Uses message slices and global variables.

• Return: None.

• Usage: For low-level messaging to other contracts or VM shells.

Fragment: touch and callExtTouch

• Purpose: Updates contract state timestamp and handles external touch calls.

• Internal Fragments: touch_a55526db_internal, callExtTouch_347a50dc_internal

• Key operations:

  • Validates message and sender.

  • Accepts messages and updates the timestamp in global state.

  • Calls internal token retrieval and message sending routines.

• Parameters: Global state variables and message slices.

• Return: None.

• Usage: For pinging or updating state externally.

Fragment: public_function_selector

• Purpose: Dispatches incoming calls to appropriate internal fragments based on function selectors.

• Key operations:

  • Compares incoming function selector integers against known values.

  • Executes the matching fragment inline.

  • Throws exceptions if no match found.

• Parameters: Function selector integer from message.

• Return: None.

• Usage: Acts as the main entry point for function dispatch.

Fragment: main_external and main_internal

• Purpose: Entry points for external and internal message processing.

• Key operations:

  • main_external verifies message signatures and replay protection.

  • Calls public_function_selector to dispatch function calls.

  • main_internal manages internal message processing, empty checks, and dispatch.

• Parameters: Message slices, global states.

• Return: None.

• Usage: Entry points called by the runtime on respective message types.

Fragment: upd_only_time_in_c4

• Purpose: Updates only the timestamp in the contract's internal cell representation.

• Key operations:

  • Reads the current contract state.

  • Creates a new cell with updated timestamp.

  • Updates global state.

• Parameters: None explicitly; uses global state.

• Return: None.

• Usage: Used internally after state-changing operations to update timestamps.

Fragment: c4_to_c7 and c7_to_c4

• Purpose: Conversion between two internal cell representations (c4 and c7).

• Key operations:

  • c4_to_c7: Prepares contract state for internal use by pushing roots and setting globals.

  • c7_to_c4: Reverses the operation, constructing a new cell and popping roots.

• Parameters: Implicit stack and global variables.

• Return: None.

• Usage: Used internally for state transformations.

Important Implementation Details

• Stack-Based Execution: The code uses stack manipulation commands (PUSH, POP, SWAP, ROT) typical of Forth-like or custom VM assembly.

• Global Variables: Several global variables (indexed via GETGLOB and SETGLOB) are used to store contract state, such as keys, timestamps, and flags.

• Message Processing: The code distinguishes between external and internal messages, performing signature checks and replay protection.

• Cell and Slice Operations: Uses NEWC, STREF, STSLICE, and related opcodes to manipulate cells and slices, which are fundamental data structures in this environment.

• Error Handling: Uses THROW and THROWIFNOT for error states and permission enforcement.

• WASM Integration: The RUNWASM and RUNWASMCONCATMULTIARG opcodes indicate embedded WASM code execution capabilities.

• Function Dispatch: Efficient dispatch logic using function selector integers and jump references.

Interaction with Other System Parts

• Global State: The contract relies on a set of global variables that hold critical state information such as contract keys, timestamps, and flags.

• Messaging: Constructs and sends raw messages (SENDRAWMSG) to other contracts or VM shells for inter-contract communication.

• WASM Environment: Interfaces with the WASM runtime through specific opcodes, enabling execution of WASM code as part of contract logic.

• Signature Verification: Validates signatures on external messages to ensure authenticity before executing sensitive operations.

• Replay Protection: Implements replay protection by checking timestamps embedded in messages against the contract state.

Usage Examples

Deploying a New Contract

CALLREF {
    .inline deployNewContract
}

This fragment accepts an incoming message, processes tokens, constructs a new contract cell, and sends a raw message to deploy a contract.

Running WASM Code with Multiple Arguments

CALLREF {
    .inline runWasmConcatMultiarg
}

Runs embedded WASM code with many concatenated arguments, updating the contract state accordingly.

Handling an External Call

CALLREF {
    .inline main_external
}

Verifies an external message's signature, applies replay protection, and dispatches the function selector.

Mermaid Diagram

flowchart TD
A[main_external] -->|signature check| B[public_function_selector]
C[main_internal] -->|dispatch| B
B --> |function selector| D{Function}
D --> E[constructor]
D --> F[deployNewContract]
D --> G[exchangeToken]
D --> H[runWasm]
D --> I[runWasmConcatMultiarg]
D --> J[sendShell]
D --> K[sendVMShell]
D --> L[touch]
D --> M[callExtTouch]
D --> N[upd_only_time_in_c4]
E --> O[c4_to_c7]
F --> P[deployNewContract_e6e22826_internal]
G --> Q[exchangeToken_53d168e3_internal]
H --> R[runWasm_449543f3_internal]
I --> S[runWasmConcatMultiarg_be417fbd_internal]
J --> T[sendShell_77e2a3b5_internal]
K --> U[sendVMShell_e1519e7b_internal]
L --> V[touch_a55526db_internal]
M --> W[callExtTouch_347a50dc_internal]
O --> X[c7_to_c4]
W --> X
V --> X
T --> X
U --> X
S --> X
R --> X
Q --> X
P --> X
X --> N

Summary of Key Functions

Notes on Code Style and Structure

• The code is organized into .fragment sections, each representing a reusable code block or function.

• Inline fragments are used for internal helper procedures.

• The contract uses a dictionary for function selector dispatch, optimizing call routing.

• Comments indicate source locations in the original .sol file, useful for debugging or reverse mapping.

Relevant Topics

• Smart Contract Execution and Messaging

• WASM Integration in Smart Contracts

• Stack-Based Virtual Machine Programming

• Contract State Management

• Signature Verification in Blockchain

• Inter-Contract Communication