home / skills / multiversx / mx-ai-skills / mvx_sdk_go_data

mvx_sdk_go_data skill

safe

This skill helps you understand and utilize core MultiversX Go SDK data structures, enabling safer transaction handling and efficient API usage.

npx playbooks add skill multiversx/mx-ai-skills --skill mvx_sdk_go_data

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.0 KB

---
name: mvx_sdk_go_data
description: Core data structures and types for MultiversX Go SDK.
---

# MultiversX SDK-Go Data Structures

These types define the core objects interacting with the blockchain.

## Transaction

`data.Transaction` is the main struct for all network interactions.

```go
type Transaction struct {
    Nonce            uint64 `json:"nonce"`
    Value            string `json:"value"`
    RcvAddr          string `json:"receiver"`
    SndAddr          string `json:"sender"`
    GasPrice         uint64 `json:"gasPrice,omitempty"`
    GasLimit         uint64 `json:"gasLimit,omitempty"`
    Data             []byte `json:"data,omitempty"`
    Signature        string `json:"signature,omitempty"`
    ChainID          string `json:"chainID"`
    Version          uint32 `json:"version"`
    Options          uint32 `json:"options,omitempty"`
    Guardian         string `json:"guardian,omitempty"`
    GuardianSignature string `json:"guardianSignature,omitempty"`
    Relayer          string `json:"relayer,omitempty"`
    RelayerSignature string `json:"relayerSignature,omitempty"`
}
```

## Address

```go
type AddressWithType struct {
    address []byte
    hrp     string // "erd" usually
}

// Methods
// NewAddressFromBech32String(bech32)
// NewAddressFromBytes(bytes)
// AddressAsBech32String()
```

## Account

```go
type Account struct {
    Address         string `json:"address"`
    Nonce           uint64 `json:"nonce"`
    Balance         string `json:"balance"` // BigInt string
    Username        string `json:"username"`
    CodeHash        string `json:"codeHash"`
    RootHash        string `json:"rootHash"`
    DeveloperReward string `json:"developerReward"`
}
```

## Network Config

```go
type NetworkConfig struct {
    ChainID                  string
    MinGasLimit              uint64
    MinGasPrice              uint64
    GasPerDataByte           uint64
    GasPriceModifier         float64
    AdditionalGasForTxSize   uint64
    ...
}
```

## VM Query

```go
type VmValueRequest struct {
    Address    string   `json:"scAddress"`
    FuncName   string   `json:"funcName"`
    CallValue  string   `json:"value"`
    CallerAddr string   `json:"caller"`
    Args       []string `json:"args"` // Hex encoded arguments
}

type VmValuesResponseData struct {
    ReturnData      []string `json:"returnData"` // Hex encoded return values
    ReturnCode      string   `json:"returnCode"`
    ReturnMessage   string   `json:"returnMessage"`
    GasRemaining    uint64   `json:"gasRemaining"`
    GasRefund       uint64   `json:"gasRefund"`
    OutputAccounts  map[string]*OutputAccount `json:"outputAccounts"`
}
```

## Best Practices

1. **Use `Value` as string**: To prevent overflow (Go's `int64` is too small for big token amounts).
2. **Bech32 addresses**: API expects bech32 strings, internal logic often uses bytes.
3. **Hex encoding**: `Data` field is often hex-encoded when checking explorers, but SDK expects bytes/string.
4. **Options bitmask**: Used for specialized txs (e.g. guarded).

Overview

This skill provides a concise reference for the core data structures used by the MultiversX Go SDK focused on transactions, accounts, addresses, network configuration and VM queries. It explains the primary fields, common encodings, and practical guidance to avoid common pitfalls when building or inspecting transactions and smart contract calls.

How this skill works

The package models on-chain objects as Go structs: Transaction for signed operations, Account for chain state, AddressWithType for bech32/byte conversion, NetworkConfig for chain limits and gas economics, and VM query request/response types for smart contract interactions. Fields that represent token amounts or large numeric results use strings to avoid integer overflow. Data payloads and arguments are handled as raw bytes or hex-encoded strings depending on context.

When to use it

Building and serializing signed transactions to submit to a MultiversX node.
Querying account state and parsing balances, nonces, and code/root hashes.
Preparing VM function calls with hex-encoded args and reading VM return values.
Converting between bech32 addresses and raw bytes for internal logic.
Validating gas limits and pricing against network configuration before sending txs.

Best practices

Represent any token amount or large integer as a decimal string to avoid Go integer overflow.
Send and receive bech32 address strings in API calls; convert to bytes only for low-level operations.
Treat transaction Data/arguments as bytes in the SDK, but expect hex encoding when inspecting explorers or raw JSON.
Check NetworkConfig (MinGasLimit, MinGasPrice, GasPerDataByte) and compute gas costs before submission.
Use the Options bitmask for guarded or specialized transaction behavior and include guardian/relayer signatures when required.

Example use cases

Create a Transaction struct, set nonce/value/receiver/sender/data and sign it for broadcast.
Load Account from node API to display balance and username in a wallet UI.
Build VmValueRequest for read-only contract calls and parse VmValuesResponseData.returnData.
Validate a prepared transaction against NetworkConfig to ensure it meets minimum gas constraints.
Convert user-entered bech32 addresses to AddressWithType bytes before cryptographic operations.

FAQ

Why are amounts stored as strings instead of integers?

Token balances and transfer values can exceed native 64-bit limits, so using decimal strings prevents overflow and preserves precision across JSON APIs.

When should I hex-encode data or arguments?

Use raw bytes in SDK structs; hex-encode when sending payloads to explorers, reading logs, or when APIs require hex strings for arguments and return values.