home / skills / multiversx / mx-ai-skills / mvx_sdk_go_builders

mvx_sdk_go_builders skill

safe

This skill helps you construct and sign transactions in Go SDK using builders, ensuring correct fields, signing, and ready-to-submit payloads.

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

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

Files (1)

SKILL.md

2.2 KB

---
name: mvx_sdk_go_builders
description: Transaction construction and signing using Builders in Go SDK.
---

# MultiversX SDK-Go Builders

Using `TxBuilder` to construct and sign transactions.

## Transaction Builder

```go
import (
    "github.com/multiversx/mx-sdk-go/builders"
    "github.com/multiversx/mx-sdk-go/core"
    "github.com/multiversx/mx-sdk-go/data"
)

// Initialize
txBuilder, err := builders.NewTxBuilder(core.Marshalizer)

// Manual Transaction Construction
tx := &data.Transaction{
    Nonce:    nonce,
    Value:    "1000000000000000000", // 1 EGLD
    RcvAddr:  receiverAddressString,
    SndAddr:  senderAddressString,
    GasPrice: 1000000000,
    GasLimit: 50000,
    Data:     []byte("memo"),
    ChainID:  "D",
    Version:  1,
}

// Sign Transaction
err = txBuilder.ApplySignature(tx, privateKey)
// tx.Signature, tx.SenderUsername are updated
```

## Contract Builders (High Level)

There are specific builders for SC interactions (often generated code or custom implementations), but the core pattern is:

1. Create `data.Transaction` struct
2. Populate fields (Date = endpoint@arg1@arg2)
3. Sign with `TxBuilder`

## Token Transfers

ESDT transfers require specific data fields.

```go
// Native EGLD
tx.Value = "1000000000000000000"
tx.Data = []byte("")

// ESDT Transfer
// Function: ESDTTransfer
// Args: TokenIdentifier (hex), Amount (hex)
tx.Value = "0"
tx.Data = []byte("ESDTTransfer@" + hexTokenId + "@" + hexAmount)
```

## Relayed V3 Transactions

Constructing the inner transaction for a relayed call.

```go
// Inner Tx (User)
innerTx := &data.Transaction{...}
// Sign Inner Tx
signature, _ := userPrivateKey.Sign(innerTxBytes)

// Relayer Tx
relayerTx := &data.Transaction{
    Sender: relayerAddress,
    Data: []byte("relayedTx@" + innerTxBytesHex + "@" + signatureHex),
    ...
}
```

## Data Serialization

The SDK uses a `Marshalizer` interface (usually JSON).

```go
import "github.com/multiversx/mx-sdk-go/core"

bytes, err := core.Marshalizer.Marshal(tx)
```

## Best Practices

1. **Validate fields** before building
2. **Use correct ChainID** ('1', 'D', 'T')
3. **Handle Big Ints as strings** in `Value` field
4. **Gas Limit estimation** is manual or via proxy simulation

Overview

This skill demonstrates how to construct, sign, and prepare transactions using the MultiversX Go SDK builders. It focuses on the TxBuilder pattern, manual transaction creation, contract interaction payloads, token transfers (native and ESDT), relayed transactions, and serialization. The goal is to get developers from raw fields to a signed transaction ready for broadcast.

How this skill works

You create a data.Transaction object, populate canonical fields (Nonce, Value, Sender, Receiver, GasPrice, GasLimit, Data, ChainID, Version), then use TxBuilder.ApplySignature to attach the sender signature and derived sender metadata. For contract calls and ESDT transfers the Data field encodes function name and hex-encoded args (e.g., "ESDTTransfer@<tokenHex>@<amountHex>"). For relayed flows you sign an inner user transaction, embed its bytes and signature into a relayer transaction Data payload, then the relayer publishes it.

When to use it

When manually constructing simple EGLD or ESDT transfers from backend services.
When invoking smart contract functions that require encoded arguments.
When building relayed transactions where a relayer submits an inner signed tx.
When serializing transactions for storage, inspection, or cross-service transfer.
When you need programmatic signing flow integrated into server-side key management.

Best practices

Validate all transaction fields before signing: addresses, nonces, chain ID and version.
Keep monetary values as decimal strings or hex when required; avoid native int overflow.
Use the correct ChainID (e.g., '1', 'D', 'T') and consistent Version for the network.
Estimate GasLimit via simulation if possible; otherwise add safe headroom to avoid failure.
Always marshal and inspect the transaction bytes you sign to ensure payload correctness.

Example use cases

Server constructs and signs a 1 EGLD payment, then broadcasts the signed tx to a gateway.
Backend prepares an ESDT transfer by building Data = "ESDTTransfer@tokenHex@amountHex" and signs it.
A relayer service embeds a user-signed inner transaction and signature into a relayer tx for gas sponsorship.
CLI tooling that serializes transactions to JSON for offline signing and later submission.
Automated contract deployment or interaction scripts using generated contract builders that follow the same TxBuilder flow.

FAQ

How should I represent large token amounts?

Represent large amounts as decimal strings in Value or hex-encoded strings for ESDT arguments to avoid integer overflow.

How do I sign a relayed transaction?

Sign the inner user transaction bytes to get a signature, then embed innerTxBytesHex and signatureHex into relayerTx.Data as the relayed payload before the relayer signs.