hello_wasm.abi.json

Overview

The hello_wasm.abi.json file defines the Application Binary Interface (ABI) for a smart contract designed to interact with WebAssembly (WASM) binaries within a blockchain environment. The ABI specifies the contract's callable functions, their inputs and outputs, persistent storage fields, and metadata such as the ABI version and contract version.

This ABI facilitates functionalities such as executing WASM functions with various argument formats, managing tokens, deploying new contracts, and creating complex on-chain data structures called "cells." The contract maintains state variables including a public key, timestamps, and stored WASM execution results.

ABI Structure and Components

Metadata

• ABI version: 2 — Specifies the ABI specification version used.

• Version: "2.4" — The contract version.

• Header: ["pubkey", "time", "expire"] — Standard headers included in external inbound messages for authorization, time tracking, and expiration.

Persistent Fields

These fields represent the contract's storage variables:

Functions

The contract exposes multiple functions with varying purposes. Each function's inputs, outputs, and usage are detailed below.

1. constructor(value: uint64)

• Purpose: Initializes the contract with a specified 64-bit unsigned integer value.

• Inputs:

  • value (uint64): Initialization parameter, possibly used to set internal state or initial token balance.

• Outputs: None.

• Usage: Called once during contract deployment to set up initial state.

2. exchangeToken(value: uint64)

• Purpose: Handles token exchange operations within the contract.

• Inputs:

  • value (uint64): Amount of tokens to exchange.

• Outputs: None.

• Usage: Facilitates token transfers or swaps, likely updating internal balances.

3. renderHelloWorld() -> string

• Purpose: Returns a greeting message.

• Inputs: None.

• Outputs:

  • value0 (string): A string message, presumably "Hello, World!".

• Usage Example:

  let greeting = contract.renderHelloWorld();
  console.log(greeting); // Expected output: "Hello, World!"
  

• Note: This function provides a simple readable output, useful for testing contract responsiveness.

4. runWasm(wasmBinary: bytes, wasmModule: string, wasmFunction: string, wasmArgs: bytes, wasmHash: bytes) -> bytes

• Purpose: Executes a WASM function on-chain with specified arguments.

• Inputs:

  • wasmBinary (bytes): The raw WASM binary code.

  • wasmModule (string): Name of the WASM module.

  • wasmFunction (string): Function name inside the WASM module to execute.

  • wasmArgs (bytes): Serialized arguments for the WASM function.

  • wasmHash (bytes): Hash of the WASM binary for integrity verification.

• Outputs:

  • value0 (bytes): The serialized output from the WASM function execution.

• Implementation Details:

  • The function validates the WASM binary using the provided hash.

  • Executes the specified function within the module with given arguments.

  • Saves or returns the execution result.

• Usage: Enables dynamic execution of WASM code, allowing extensible smart contract logic.

5. runWasmConcatMultiarg(...) -> bytes

• Purpose: Similar to runWasm, but supports multiple concatenated argument bytes for the WASM function.

• Inputs: Same as runWasm, with additional argument bytes:

  • wasmArgs2, wasmArgs3, wasmArgs4 (bytes): Additional serialized argument segments.

• Outputs: Same as runWasm.

• Usage: Allows passing multiple separate argument blocks to the WASM function, facilitating complex data input.

6. touch()

• Purpose: Likely a no-operation or ping function used to update contract state or trigger events.

• Inputs: None.

• Outputs: None.

7. callExtTouch(addr: address)

• Purpose: Calls the touch function on an external contract at the given address.

• Inputs:

  • addr (address): External contract address to invoke.

• Outputs: None.

• Usage: Enables inter-contract communication by invoking actions on external contracts.

8. sendVMShell(dest: address, amount: uint128, bounce: bool)

• Purpose: Sends a message along with a specified amount to a destination address with bounce behavior.

• Inputs:

  • dest (address): Recipient address.

  • amount (uint128): Amount of tokens/value to send.

  • bounce (bool): Indicates if the message should bounce back on failure.

• Outputs: None.

9. sendShell(dest: address, value: uint128)

• Purpose: Sends tokens or value to a specified address without bounce behavior.

• Inputs:

  • dest (address): Recipient address.

  • value (uint128): Amount to send.

• Outputs: None.

10. deployNewContract(stateInit: cell, initialBalance: uint128, payload: cell)

• Purpose: Deploys a new smart contract on-chain.

• Inputs:

  • stateInit (cell): Serialized initial state of the new contract.

  • initialBalance (uint128): Initial token balance to fund the new contract.

  • payload (cell): Additional data or parameters for the new contract.

• Outputs: None.

• Usage: Enables dynamic contract creation from within this contract.

11. create_big_cell2(iterations: uint256) -> cell

• Purpose: Constructs a large "cell" data structure via iterative operations.

• Inputs:

  • iterations (uint256): Number of iterations to build the cell.

• Outputs:

  • value0 (cell): The constructed cell.

• Usage: Useful for testing or manipulating large on-chain data structures.

12. create_big_cell(iterations: uint256) -> cell

• Purpose: Similar to create_big_cell2, constructs a large cell.

• Inputs & Outputs: Same as create_big_cell2.

• Note: Possibly an alternative algorithm or version of big cell creation.

13. create_deep_cell(iterations: uint256) -> cell

• Purpose: Creates a deeply nested cell structure.

• Inputs:

  • iterations (uint256): Depth of nesting to create.

• Outputs:

  • value0 (cell): Resulting nested cell.

• Implementation Details: Uses recursive or iterative nesting to achieve depth.

14. timestamp() -> uint32

• Purpose: Returns the current contract timestamp.

• Inputs: None.

• Outputs:

  • timestamp (uint32): The current timestamp value.

• Usage: Provides time-related data for contract logic.

15. wasmResSaved() -> bytes

• Purpose: Retrieves the saved result bytes from the last WASM execution.

• Inputs: None.

• Outputs:

  • wasmResSaved (bytes): Stored WASM execution output.

• Usage: Allows retrieving previous WASM run results for reference.

Implementation Details and Algorithms

• WASM Execution: The contract supports dynamic invocation of WASM functions through runWasm and runWasmConcatMultiarg. These functions validate the binary using a hash and execute specific functions with serialized arguments, returning serialized byte results. This allows for flexible and extensible contract logic using WASM modules.

• Cell Creation: The three functions create_big_cell2, create_big_cell, and create_deep_cell generate complex on-chain data structures called "cells." These are likely implemented using iterative or recursive algorithms to build large or deeply nested cells, which can be used for efficient storage or data representation in the blockchain context.

• Contract Deployment: deployNewContract facilitates on-chain deployment of new contracts by accepting serialized initial state and payload cells, along with initial funding, enabling dynamic contract creation.

• Token and Message Handling: Functions like exchangeToken, sendVMShell, and sendShell manage value transfers and message sending with optional bounce behavior, supporting typical token operations and asynchronous communication.

Interaction with Other System Components

• External Contracts: Through callExtTouch, this contract can invoke methods on other contracts, enabling inter-contract collaboration.

• WASM Modules: The contract interacts with external WASM binaries provided as input, executing their functions dynamically. This allows the contract to extend its behavior based on external WASM code.

• Blockchain State: The contract stores persistent state fields such as public keys and timestamps that relate to blockchain state and authorization, ensuring secure and time-aware operations.

• Cell Data Structures: Cells constructed by this contract can be used by other contracts or system components requiring complex serialized data.

Visual Diagram

flowchart TD
A[hello_wasm.abi.json ABI] --> B[Constructor]
A --> C[Token Management]
A --> D[WASM Execution]
A --> E[Cell Creation]
A --> F[Contract Deployment]
A --> G[Inter-contract Calls]
A --> H[Timestamp & State Access]
B --> B1["constructor(value)"]
C --> C1["exchangeToken(value)"]
C --> C2["sendVMShell(dest, amount, bounce)"]
C --> C3["sendShell(dest, value)"]
D --> D1["runWasm(...)"]
D --> D2["runWasmConcatMultiarg(...)"]
D --> D3["wasmResSaved()"]
E --> E1["create_big_cell(iterations)"]
E --> E2["create_big_cell2(iterations)"]
E --> E3["create_deep_cell(iterations)"]
F --> F1["deployNewContract(stateInit, initialBalance, payload)"]
G --> G1["callExtTouch(addr)"]
G --> G2["touch()"]
H --> H1["timestamp()"]
H --> H2["renderHelloWorld()"]

This diagram groups the contract's functions into functional categories, illustrating their relationship to the overall ABI definition. It highlights the main workflows: initialization, token handling, WASM execution, data structure creation, deployment, inter-contract communication, and state/time access.