hello_wasm.sol

Overview

This file defines a smart contract named helloWorld written in Solidity with Gosh-specific extensions. The contract primarily demonstrates interactions with the blockchain environment, including token conversions, WASM execution, contract deployment, and token transfers within the same or different decentralized application (Dapp) IDs. It also maintains a timestamp reflecting the last interaction time with the contract. The contract leverages low-level TVM (TON Virtual Machine) instructions and Gosh-specific functions to handle token operations and WASM runtime calls.

Contract: helloWorld

State Variables

• uint32 public timestamp
  Stores the Unix timestamp of the last time the contract was either deployed or interacted with through certain functions such as touch().

• bytes public wasmResSaved
  Holds the result bytes from the last WASM runtime invocation.

Constructor

constructor(uint64 value)

Initializes the contract by converting the specified amount of SHELL tokens to VMSHELL tokens, checks the contract's public key, accepts the deployment message for processing, and sets the timestamp to the current block time.

• Parameters:

  • value - The amount of SHELL tokens to convert to VMSHELL for transaction fee payment.

• Implementation Details:

  • Calls gosh.cnvrtshellq(value) to convert tokens.

  • Requires the contract's public key to be non-zero (require(tvm.pubkey() != 0, 101)).

  • Calls tvm.accept() to accept the deployment transaction.

  • Sets timestamp to the current block timestamp.

• Usage Example:
  Deploy the contract with an initial token conversion value to cover gas fees.

Functions

exchangeToken

function exchangeToken(uint64 value) public pure

Converts a given amount of SHELL tokens to VMSHELL tokens.

• Parameters:

  • value - Amount of SHELL tokens to convert.

• Implementation Details:

  • Calls tvm.accept() to accept the message.

  • Invokes getTokens() to replenish contract balance if low.

  • Calls gosh.cnvrtshellq(value) for token conversion.

renderHelloWorld

function renderHelloWorld () public pure returns (string)

Returns a fixed string "helloWorld".

• Return Value:

  • A string literal "helloWorld".

• Usage Example:
  Can be used as a simple test or greeting function.

runWasm

function runWasm(bytes wasmBinary, string wasmModule, string wasmFunction, bytes wasmArgs, bytes wasmHash) public returns (bytes)

Executes a WASM binary module function with provided arguments and returns the result bytes.

• Parameters:

  • wasmBinary - The WASM binary code in bytes.

  • wasmModule - Name of the WASM module.

  • wasmFunction - Function name inside the WASM module to call.

  • wasmArgs - Encoded arguments to the WASM function.

  • wasmHash - Hash identifying the WASM module.

• Return Value:

  • Bytes returned by the WASM function execution.

• Implementation Details:

  • Calls getTokens() to ensure sufficient gas.

  • Uses gosh.runwasm() passing encoded parameters to invoke WASM execution on-chain.

  • Decodes the returned TvmCell result into bytes.

  • Saves the result in wasmResSaved.

  • Accepts the transaction with tvm.accept().

• Usage Example:
  Invoke a specific function inside a WASM module deployed on-chain to perform computation.

runWasmConcatMultiarg

function runWasmConcatMultiarg(bytes wasmBinary, string wasmModule, string wasmFunction, bytes wasmArgs, bytes wasmArgs2, bytes wasmArgs3, bytes wasmArgs4, bytes wasmHash) public returns (bytes)

Executes a WASM function with multiple concatenated arguments.

• Parameters:

  • Same as runWasm with four separate wasmArgs parameters to handle multiple arguments.

• Return Value:

  • Bytes returned from the WASM execution.

• Implementation Details:

  • Similar to runWasm but calls gosh.runwasmconcatmultiarg() with multiple argument encodings.

  • Saves the result in wasmResSaved.

  • Accepts the transaction.

touch

function touch() external

Updates the timestamp variable with the current block time. This function can be called externally.

• Implementation Details:

  • Calls tvm.accept() to accept the incoming message.

  • Calls getTokens() to ensure sufficient balance.

  • Updates the timestamp with block.timestamp.

• Usage Example:
  External contracts or users can invoke this to update the contract state timestamp.

callExtTouch

function callExtTouch(address addr) public view

Calls the touch method of another contract via an internal message.

• Parameters:

  • addr - Address of the target contract implementing IHelloWorld.

• Implementation Details:

  • Requires the message to be signed by the contract's public key (msg.pubkey() == tvm.pubkey()).

  • Calls tvm.accept() and getTokens().

  • Invokes IHelloWorld(addr).touch() via the interface.

• Usage Example:
  Used to programmatically trigger touch() on another helloWorld contract.

sendVMShell

function sendVMShell(address dest, uint128 amount, bool bounce) public view

Transfers VMSHELL tokens to another contract within the same Dapp ID.

• Parameters:

  • dest - Destination contract address.

  • amount - Amount of VMSHELL tokens to transfer.

  • bounce - Flag indicating whether to bounce funds back if the destination contract does not exist.

• Implementation Details:

  • Validates message signature.

  • Calls tvm.accept() and getTokens().

  • Uses dest.transfer() with specified parameters.

• Usage Example:
  Sending gas tokens to other contracts within the Dapp ecosystem.

sendShell

function sendShell(address dest, uint128 value) public view

Transfers SHELL tokens to a specified address, which can be within the same or a different Dapp ID.

• Parameters:

  • dest - Target address for transfer.

  • value - Amount of SHELL tokens to send.

• Implementation Details:

  • Requires message signed by the contract owner.

  • Calls tvm.accept() and getTokens().

  • Constructs an internal message with a payload and transfer flags.

  • Executes the transfer.

• Usage Example:
  Used for cross-Dapp token transfers or sending tokens externally.

deployNewContract

function deployNewContract(TvmCell stateInit, uint128 initialBalance, TvmCell payload) public pure

Deploys a new contract within the same Dapp by specifying its initial state and funding.

• Parameters:

  • stateInit - Cell containing the contract's code and initial data.

  • initialBalance - Initial balance allocated to the new contract.

  • payload - Message body for the constructor call.

• Implementation Details:

  • Accepts the transaction and calls getTokens().

  • Calculates the new contract address from the hash of stateInit.

  • Transfers the specified funds and deploys the contract with the given payload.

• Usage Example:
  Dynamically deploy subcontracts from this contract.

getTokens

function getTokens() private pure

Checks if the contract balance is below 100 VMSHELL and mints tokens if necessary.

• Implementation Details:

  • Compares contract balance to 100 VMSHELL threshold (expressed in nanotokens).

  • Calls gosh.mintshellq() to mint tokens when balance is low.

• Purpose:
  Enables automatic replenishment of contract's gas token balance for transaction fees.

Cell Creation Functions

These functions demonstrate creation of complex and nested TvmCell structures for data storage or processing.

• create_cell()
  Returns a deep cell with 700 iterations (depth).

• create_big_cell2(uint256 iterations)
  Creates a large cell with nested references by iterating and storing references twice per iteration.

• create_big_cell(uint256 iterations)
  Similar to create_big_cell2 but stores four references per iteration, creating a larger cell structure.

• create_deep_cell(uint256 iterations)
  Creates a deeply nested cell structure by storing a single reference in each iteration, increasing depth.

• Parameters:

  • iterations controls the depth or size of the created cell structure.

• Usage:
  These functions can be used to test cell size limits or prepare complex data structures for contract logic.

Interface: IHelloWorld

Defines an external interface with one function:

function touch() external;

Used to call the touch() function on other contracts that implement this interface.

Important Implementation Details

• Token Handling:
  The contract uses Gosh-specific functions such as gosh.cnvrtshellq() and gosh.mintshellq() to convert and mint tokens. These are essential for managing gas fees on the platform.

• WASM Execution:
  WASM-related functions (runWasm and runWasmConcatMultiarg) use low-level calls to execute WASM binaries on-chain, passing encoded arguments and module/function identifiers.

• Security Checks:
  Functions that modify the state or transfer tokens require the caller to have the correct public key (msg.pubkey() == tvm.pubkey()) to prevent unauthorized actions.

• Use of TVM Features:
  The contract uses tvm.accept() to accept incoming messages and pay gas fees, tvm.commit() to commit changes, and TvmCell structures for complex data storage.

• Balance Management:
  The private getTokens() function ensures the contract maintains sufficient balance to cover transaction fees by minting tokens when the balance falls below a threshold.

Interactions with Other Parts of the System

• Token Conversion and Minting:
  Relies on the Gosh environment for token conversion and minting operations.

• WASM Runtime:
  Interfaces with the WASM executor via gosh.runwasm and gosh.runwasmconcatmultiarg to run WebAssembly code on-chain.

• Other Contracts:
  Calls external contracts implementing the IHelloWorld interface, particularly invoking their touch method.

• Contract Deployment:
  Can deploy new contracts dynamically within the same Dapp ID by constructing TvmCell state initialization data.

Mermaid Diagram: Contract Structure

classDiagram
class helloWorld {
+uint32 timestamp
+bytes wasmResSaved
+constructor(uint64)
+exchangeToken(uint64)
+renderHelloWorld() string
+runWasm(bytes, string, string, bytes, bytes) bytes
+runWasmConcatMultiarg(bytes, string, string, bytes, bytes, bytes, bytes, bytes) bytes
+touch()
+callExtTouch(address)
+sendVMShell(address, uint128, bool)
+sendShell(address, uint128)
+deployNewContract(TvmCell, uint128, TvmCell)
-getTokens()
+create_cell() TvmCell
+create_big_cell2(uint256) TvmCell
+create_big_cell(uint256) TvmCell
+create_deep_cell(uint256) TvmCell
}
helloWorld ..> IHelloWorld : uses

This diagram illustrates the helloWorld contract's key methods and properties, as well as its usage of the external interface IHelloWorld.