BEATOZ Wallet Integration Guide

Wallet Integration Overview

BEATOZ wallet support is a native chain integration. Balance, nonce, transaction construction, signing, broadcasting, and transaction decoding should use the BEATOZ native RPC and the native transaction format documented in this guide.

Accounts and Addresses

BEATOZ accounts use secp256k1 keys and 20-byte addresses. Serialized public keys are compressed 33-byte secp256k1 keys. On the current testnet, Tendermint is replaced by the beatoz/tendermint-ethaddr fork, so secp256k1 PubKey.Address() decompresses the public key, applies Ethereum-style Keccak-256 to the uncompressed key without the 0x04 prefix, and takes the last 20 bytes. Transaction signing hashes with SHA-256.

privateKey     = 32 random bytes                         // secp256k1 scalar
serializedPub  = compressed_secp256k1_pubkey(privateKey) // 33 bytes, 0x02/0x03 || X
uncompressed   = decompress_secp256k1_pubkey(serializedPub) // 65 bytes, 0x04 || X || Y
address        = keccak256(uncompressed[1:])[12:32]         // 20 bytes

// Node-equivalent Go path:
// tmsecp256k1.PubKey(serializedPub).Address()
// The testnet replaces Tendermint with beatoz/tendermint-ethaddr, so Address()
// returns the Ethereum-style Keccak address bytes above.

Wallet Implementation Checklist

Implement these items in order. Each step links to the section that documents it in full — this list intentionally repeats no detail.

Transaction Flow Overview

Native BEATOZ transactions are protobuf-marshaled application transactions. Wallets build the transaction fields, RLP-encode the signing payload, sign the SHA-256 digest with secp256k1, attach the signature, marshal the signed transaction with proto3, and broadcast the resulting bytes.

1. Read account state
   RPC: account({ addr })
   Use: value.nonce (string), value.balance (fons, string)

2. Read network parameters
   RPC: gov_params({})
   Use: value.gasPrice, value.minTrxGas

3. Build TRX_TRANSFER
   version  = 1
   time     = current Unix time in NANOSECONDS
   nonce    = account nonce, used AS-IS (first tx of a new account: 0)
   from     = sender address
   to       = receiver address
   amount   = amount in fons
   gas      = minTrxGas            // for regular transfer to a normal account
   gasPrice = gov_params gasPrice  // must match the network value EXACTLY
   payload  = nil

4. Sign with V1  (see Signing)
   preimage = rlpBytes || chainIdBytes
   digest   = SHA-256(preimage)
   sig      = secp256k1.sign(digest)
   if sig.v is 0 or 1: sig.v += 27

5. Marshal and hash  (see Proto Marshal)
   signedTxBytes = proto3.Marshal(TrxProto)
   txHash        = SHA-256(signedTxBytes)      // 32 bytes

6. Broadcast  (see Broadcast)
   RPC: broadcast_tx_commit({ tx: base64(signedTxBytes) })
   Success: check_tx.code == 0 AND deliver_tx.code == 0

7. Lookup  (see Lookup & History)
   RPC: tx({ hash: base64(txHash), prove: false })
   Decode result.tx (base64) as TrxProto.

Transaction Data Structure

All BEATOZ native transaction types share the same envelope. The type-specific payload has two encodings in the full flow: RLP payload bytes are used only inside the V1 signing preimage, while the final TrxProto _payload field stores protobuf-marshaled payload bytes.

Supported Transaction Types

The transaction type number determines which payload schema is used and which validation rules apply. The rules column lists the constraints the node enforces — violating any of them rejects the transaction.

Fees & Gas

The charged transaction fee is gasUsed × gasPrice, paid in fons by the sender (or by the payer when fee delegation is used). For non-EVM paths gasUsed equals tx.gas, so this is the full gas limit; for EVM paths it is the actual used gas. BEATOZ has no fee market: gasPrice is a governance parameter, and the node rejects any transaction whose gasPrice differs from it.

V1 Signing

V1 signing clears the signature, RLP-encodes the transaction as one 11-element list in the exact order below, appends the chain ID bytes, hashes the preimage with SHA-256, signs the digest with secp256k1, and stores v as 27/28. Add 27 only when the signing library returns a raw recovery id 0/1; if it already returns 27/28, keep it unchanged. The node selects the signature scheme by the v byte: 27/28 means V1. A legacy V0 scheme (v = 0/1) exists for backward compatibility — do NOT use it for new integrations.

// Signer V1
tx.sig = nil          // the cleared sig is still an element of the RLP list (empty string)
// payer / payerSig are never part of the sender's RLP struct

payloadBytes = (tx.payload == nil)
  ? EMPTY                          // transfer, staking
  : rlpEncode(payload)             // see the "RLP payload" column in Payload Structures

rlpBytes = rlpEncode([             // ONE list with exactly 11 elements
  version,        // RLP unsigned integer
  time,           // RLP unsigned integer (Unix nanoseconds)
  nonce,          // RLP unsigned integer
  from,           // 20-byte string
  to,             // 20-byte string (empty string for contract deploy)
  amountBytes,    // uint256 -> minimal big-endian bytes (empty string for 0)
  gas,            // RLP unsigned integer
  gasPriceBytes,  // uint256 -> minimal big-endian bytes
  type,           // RLP unsigned integer
  payloadBytes,   // byte string (empty when there is no payload)
  ''              // the cleared sig -> always an empty string when signing
])

chainIdBytes = minimalBigEndianBytes(parseChainId(chainId))
// chainId "0xbea701" is parsed as a NUMBER (hex because of the 0x prefix).
// uint256(0xbea701).bytes() = 0xBE 0xA7 0x01  (3 bytes)
// It is NOT the ASCII bytes of the string "0xbea701".

preimage = rlpBytes || chainIdBytes
digest   = SHA-256(preimage)                  // NOT keccak
sig      = secp256k1.sign(digest, privateKey) // r(32) || s(32) || v(1)
if (sig[64] === 0 || sig[64] === 1) sig[64] += 27
// final v must be 27 or 28; do not add 27 again if your signer already returns 27/28
tx.sig = sig

Signed Transaction Marshal

After the signature is attached, the transaction is converted to the Go-node TrxProto schema and marshaled with protobuf v3. The resulting bytes are the signed transaction bytes used by check_tx and broadcast_tx methods, and their SHA-256 hash is the transaction hash. Note: the current JavaScript SDK transaction type omits payer/payer_sig, so treat the Go proto as canonical for fee-delegated transactions.

message TrxProto {
  int32 version = 1;
  int64 time = 2;
  int64 nonce = 3;
  bytes from = 4;
  bytes to = 5;
  bytes _amount = 6;
  int64 gas = 7;
  bytes _gasPrice = 8;
  int32 type = 9;
  bytes _payload = 10;
  bytes sig = 11;
  bytes payer = 12;
  bytes payer_sig = 13;
}

signedTxBytes = proto3.Marshal(trxProto)
txHash        = SHA-256(signedTxBytes)   // full 32 bytes
// Display the hash as hex; pass it as base64 in JSON-RPC params.

Broadcast Signed Transaction

Send the signed proto3 bytes through JSON-RPC. In the JSON body, the transaction bytes are passed as a base64 string in the tx parameter.

POST https://rpc-testnet0.beatoz.io/
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "broadcast_tx_commit",
  "params": {
    "tx": "<base64 signed TrxProto bytes>"
  }
}

Tx 조회와 파싱

브로드캐스트 이후 월렛에는 두 흐름이 필요합니다: transaction result를 읽는 것과 signed transaction bytes를 decode하는 것입니다. tx RPC는 실행 결과와 raw signed TrxProto bytes를 함께 반환합니다.

txHashBytes = hexToBytes(txHashHex)        // 32 bytes
txRequestHash = base64(txHashBytes)        // JSON-RPC tx.hash param

result = rpc.tx({ hash: txRequestHash, prove: false })

// Execution status for wallet UI
statusCode = result.tx_result.code
statusLog  = result.tx_result.log

// What the user signed
signedTxBytes = base64Decode(result.tx)
trxProto = proto3.Unmarshal<TrxProto>(signedTxBytes)

from     = hex(trxProto.from)
to       = hex(trxProto.to)
amount   = bigEndianBytesToDecimal(trxProto._amount)   // fons
gasPrice = bigEndianBytesToDecimal(trxProto._gasPrice) // fons
payload  = decodePayloadByType(trxProto.type, trxProto._payload)

{
  "jsonrpc": "2.0",
  "id": -1,
  "result": {
    "hash": "68B5403533AAAD4D125BD24291A763F853E31F9E955112BA43CF7517BDBEB9D4",
    // Display hash. It equals SHA-256(base64Decode(result.tx)).

    "height": "175621",
    // Block height as an int64 string.

    "index": 0,
    // Transaction index inside the block.

    "tx_result": {
      "code": 0,
      // Execution status. 0 = success, non-zero = failed DeliverTx.

      "data": "gXtFlm4t5BIVj2Gpk7Wex8fVBEfAIdO/tPBtxrKg3PY=",
      // Base64 bytes returned by execution. Decode to bytes first.

      "log": "",
      "info": "",
      // Human-readable failure detail usually appears in log when code != 0.

      "gas_wanted": "2000000",
      "gas_used": "58355",
      // Gas fields are strings. For TRX_CONTRACT, gas_used is actual EVM usage.

      "events": [
        {
          "type": "evm",
          // Event namespace. This field is plain text, not base64.
          "attributes": [
            {
              "key": "Y29udHJhY3RBZGRyZXNz",
              "value": "OTYwMzExNTM2ZTdhMDM2Y2UyNTc3OGM3OTkyNGUyNjQ0NjgwYTM0ZQ==",
              "index": false
            },
            // key = base64("contractAddress")
            // value = base64("960311536e7a036ce25778c79924e2644680a34e")

            {
              "key": "dG9waWMuMA==",
              "value": "RERGMjUyQUQxQkUyQzg5QjY5QzJCMDY4RkMzNzhEQUE5NTJCQTdGMTYzQzRBMTE2MjhGNTVBNERGNTIzQjNFRg==",
              "index": true
            },
            // key = base64("topic.0")
            // value = base64("DDF252AD1BE2C89B69C2B068FC378DAA952BA7F163C4A11628F55A4DF523B3EF")
            // index=true means this attribute can be used by tx_search.

            { "key": "dG9waWMuMQ==", "value": "MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA==", "index": true },
            { "key": "dG9waWMuMg==", "value": "MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwNzZCOEIzQkFENjlBNzdEQzYwQzdFQjJENTE2QTFCQjQ4N0Y5NURDMQ==", "index": true },
            { "key": "ZGF0YQ==", "value": "MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDA2OWUxMGRlNzY2NzZkMDgwMDAwMA==", "index": false },
            { "key": "YmxvY2tOdW1iZXI=", "value": "MA==", "index": false },
            { "key": "cmVtb3ZlZA==", "value": "ZmFsc2U=", "index": false }
          ]
        },
        {
          "type": "tx",
          // BEATOZ transaction event namespace.
          "attributes": [
            { "key": "dHlwZQ==", "value": "Y29udHJhY3Q=", "index": true },
            // type = contract

            { "key": "c2VuZGVy", "value": "RDlBRDE4ODg0ODA3N0E5RjAzNjhFNzVGNzczMzExM0ZBOUI5MDYzRA==", "index": true },
            // sender = D9AD188848077A9F0368E75F7733113FA9B9063D

            { "key": "cmVjZWl2ZXI=", "value": "OTYwMzExNTM2RTdBMDM2Q0UyNTc3OEM3OTkyNEUyNjQ0NjgwQTM0RQ==", "index": true },
            // receiver = 960311536E7A036CE25778C79924E2644680A34E

            { "key": "YWRkcnBhaXI=", "value": "RDlBRDE4ODg0ODA3N0E5RjAzNjhFNzVGNzczMzExM0ZBOUI5MDYzRDk2MDMxMTUzNkU3QTAzNkNFMjU3NzhDNzk5MjRFMjY0NDY4MEEzNEU=", "index": true },
            { "key": "YW1vdW50", "value": "MA==", "index": false },
            // amount = "0" fons

            { "key": "c3RhdHVz", "value": "MA==", "index": false }
            // status = "0"
          ]
        }
      ],
      "codespace": ""
    },

    "tx": "CAEQgMnQ4rvgmt8YGBQiFNmtGIhIB3qfA2jnX3czET+puQY9KhSWAxFTbnoDbOJXeMeZJOJkRoCjTjiAiXpCBQstBeAASAZSRgpEQMEPGQAAAAAAAAAAAAAAAHa4s7rWmnfcYMfrLVFqG7SH+V3BAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGnhDedmdtCAAABaQeItYCrmymyc21ZfzkmkSQVI5K+7hbp/4oqzyGyzCy3xcG7xhsi90l4JrK7dnsKpGSAS4mi0j+5oqOiiZLsmpUsB"
    // Base64 signed TrxProto bytes. Decode and proto-unmarshal this field.
  }
}

function base64ToUtf8(value) {
  return new TextDecoder().decode(Uint8Array.from(atob(value), c => c.charCodeAt(0)));
}

function normalizeAddress(value) {
  return value.replace(/^0x/i, "").toUpperCase(); // 40 hex chars, no 0x
}

function parseBeatozEvents(events) {
  return (events || []).map(event => {
    const parsed = {
      type: event.type,             // plain text: "tx", "evm", ...
      attributes: {},
      indexed: {},                  // values usable in tx_search when attr.index === true
    };

    for (const attr of event.attributes || []) {
      const key = base64ToUtf8(attr.key);
      const rawValue = base64ToUtf8(attr.value);
      let value = rawValue;

      if (["sender", "receiver", "contractAddress"].includes(key)) {
        value = normalizeAddress(rawValue);
      } else if (key === "addrpair" && rawValue.length === 80) {
        value = {
          sender: normalizeAddress(rawValue.slice(0, 40)),
          receiver: normalizeAddress(rawValue.slice(40, 80)),
        };
      } else if (key === "amount") {
        value = { fons: rawValue };
      } else if (key.startsWith("topic.") || key === "data") {
        value = `0x${rawValue}`;    // EVM log topic/data; base64 payload is ASCII hex
      }

      parsed.attributes[key] = value;
      if (attr.index === true) {
        // Use event.type + "." + key in tx_search, e.g. tx.sender or evm.topic.2.
        parsed.indexed[key] = rawValue; // decoded raw string without 0x
      }
    }

    return parsed;
  });
}

[
  {
    "type": "evm",
    "attributes": {
      "contractAddress": "960311536E7A036CE25778C79924E2644680A34E",
      "topic.0": "0xDDF252AD1BE2C89B69C2B068FC378DAA952BA7F163C4A11628F55A4DF523B3EF",
      "topic.1": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "topic.2": "0x00000000000000000000000076B8B3BAD69A77DC60C7EB2D516A1BB487F95DC1",
      "data": "0x0000000000000000000000000000000000000000000069e10de76676d0800000",
      "blockNumber": "0",
      "removed": "false"
    },
    "indexed": {
      "topic.0": "DDF252AD1BE2C89B69C2B068FC378DAA952BA7F163C4A11628F55A4DF523B3EF",
      "topic.1": "0000000000000000000000000000000000000000000000000000000000000000",
      "topic.2": "00000000000000000000000076B8B3BAD69A77DC60C7EB2D516A1BB487F95DC1"
    }
  },
  {
    "type": "tx",
    "attributes": {
      "type": "contract",
      "sender": "D9AD188848077A9F0368E75F7733113FA9B9063D",
      "receiver": "960311536E7A036CE25778C79924E2644680A34E",
      "addrpair": {
        "sender": "D9AD188848077A9F0368E75F7733113FA9B9063D",
        "receiver": "960311536E7A036CE25778C79924E2644680A34E"
      },
      "amount": { "fons": "0" },
      "status": "0"
    },
    "indexed": {
      "type": "contract",
      "sender": "D9AD188848077A9F0368E75F7733113FA9B9063D",
      "receiver": "960311536E7A036CE25778C79924E2644680A34E",
      "addrpair": "D9AD188848077A9F0368E75F7733113FA9B9063D960311536E7A036CE25778C79924E2644680A34E"
    }
  }
]

History Search

Use tx_search to discover candidate account history from indexed transaction events. For custody/deposit credit, always perform direct tx lookup, decode result.tx, and verify tx_result.code == 0, type, to, and amount.

// Outgoing transactions
{ "method": "tx_search", "params": {
    "query": "tx.sender='13BB453C5D5FE390D2AF30F345E679B3E6AB9D74'",
    "prove": false, "page": "1", "per_page": "30", "order_by": "desc" } }

// Incoming transactions
{ "method": "tx_search", "params": {
    "query": "tx.receiver='13BB453C5D5FE390D2AF30F345E679B3E6AB9D74'",
    "prove": false, "page": "1", "per_page": "30", "order_by": "desc" } }

// Also indexed: tx.type (e.g. tx.type='transfer'), tx.height=<n>
// Note: event attribute keys/values inside results are base64-encoded.

// REP-20 / ERC-20 Transfer(address,address,uint256)
// topic.0 = keccak256("Transfer(address,address,uint256)")
// topic.1/topic.2 = 32-byte ABI topic: 000000000000000000000000 + 20-byte address
{ "method": "tx_search", "params": {
    "query": "evm.topic.0='DDF252AD1BE2C89B69C2B068FC378DAA952BA7F163C4A11628F55A4DF523B3EF' AND evm.topic.2='00000000000000000000000013BB453C5D5FE390D2AF30F345E679B3E6AB9D74'",
    "prove": false, "page": "1", "per_page": "30", "order_by": "desc" } }

Transaction Results & Error Codes

Broadcast and lookup responses include both transport-level JSON-RPC status and application-level execution status. Inspect the JSON-RPC error first, then the result code fields. Note that int64 values (height, gas) are returned as strings.

Quickstart

The SDK is useful for JavaScript/TypeScript integration examples, account lookup, unit helpers, and RPC wrappers. Important: the current SDK signer still uses the legacy V0 preimage (v = 0/1), its transaction type omits payer/payer_sig, its proposal payload field numbers differ from the Go proto, and TrxProtoBuilder.signedRawTrxProto hard-codes localnet0. Use account.signTransaction(tx, CHAIN_ID) for SDK examples, and use the Transactions chapter and Go proto as the canonical spec for new V1 wallet signing, fee-delegated transactions, and TRX_PROPOSAL.

npm install @beatoz/web3 @beatoz/web3-accounts

import { Web3 } from '@beatoz/web3';

const RPC_URL = 'https://rpc-testnet0.beatoz.io/';
const web3 = new Web3(RPC_URL);

const status = await web3.beatoz.status();
console.log(status.node_info.network);        // 0xbea701
console.log(status.sync_info.latest_block_height);

Account Lookup

The SDK accepts addresses with or without the 0x prefix. Note two SDK-side decodes: nonce is converted to a JavaScript number (the raw RPC returns it as a string), and the raw QueryResult height field is not exposed on the SDK response.

import { Web3 } from '@beatoz/web3';

const web3 = new Web3('https://rpc-testnet0.beatoz.io/');
const account = await web3.beatoz.getAccount('0x13BB453C5D5FE390D2AF30F345E679B3E6AB9D74');

console.log(account.value.address); // uppercase hex without 0x, as returned by the node
console.log(account.value.nonce);   // number - use as-is for the next tx
console.log(account.value.balance); // string, balance in fons

Transfer Transaction

Native BEATOZ transfers can be built with TrxProtoBuilder and submitted through broadcastRawTxCommit. The current SDK account signer uses the legacy V0 signing scheme; for new wallet integrations that need V1, implement the Signing chapter directly or wait for an updated SDK signer. Do not use TrxProtoBuilder.signedRawTrxProto on testnet because it hard-codes localnet0 internally. broadcastRawTxSync waits for initial CheckTx only; broadcastRawTxAsync is the non-blocking submission variant.

import { Web3, TrxProtoBuilder } from '@beatoz/web3';
import { privateKeyToAccount } from '@beatoz/web3-accounts';

const RPC_URL = 'https://rpc-testnet0.beatoz.io/';
const CHAIN_ID = '0xbea701';
const PRIVATE_KEY = process.env.BEATOZ_PRIVATE_KEY;
const RECIPIENT_ADDRESS = process.env.BEATOZ_RECIPIENT_ADDRESS;

const web3 = new Web3(RPC_URL);
if (!PRIVATE_KEY) throw new Error('Set BEATOZ_PRIVATE_KEY before broadcasting.');
if (!RECIPIENT_ADDRESS) throw new Error('Set BEATOZ_RECIPIENT_ADDRESS before broadcasting.');
const account = privateKeyToAccount(PRIVATE_KEY);

const accountInfo = await web3.beatoz.getAccount(account.address);
const params = await web3.beatoz.rule();   // gov_params (rule is the legacy alias)

const tx = TrxProtoBuilder.buildTransferTrxProto({
  from: accountInfo.value.address,
  to: RECIPIENT_ADDRESS,
  nonce: accountInfo.value.nonce,           // use as-is, no +1
  amount: web3.utils.toFons('1', 'beatoz'),
  gas: Number(params.value.minTrxGas),      // full gas is charged - do not overprovision
  gasPrice: params.value.gasPrice           // must equal the network value exactly
});

const { rawTransaction, transactionHash } = account.signTransaction(tx, CHAIN_ID);
const result = await web3.beatoz.broadcastRawTxCommit(rawTransaction);

// Do not treat deliver_tx presence as success; CheckTx failures can include an empty object.
const ok = result.check_tx?.code === 0 && result.deliver_tx?.code === 0;
console.log(transactionHash, ok);

Core Calls

Response Notes

Raw RPC response schemas are documented per-method in the RPC Reference. The SDK decodes a few fields differently from the raw JSON — these differences matter when switching between SDK and raw RPC code paths.

RPC List

Each read-only RPC card can call the testnet endpoint with the request envelope shown below. Mutation/broadcast routes show request/response schemas but the live button is disabled in the public guide. This wallet reference focuses on BEATOZ native/testnet integration routes. Do not rely on Ethereum JSON-RPC compatibility for wallet integration: the testnet endpoint exposes only a limited eth_* subset (eth_chainId, eth_blockNumber, eth_getBlockByNumber), and does not provide full Ethereum-shaped balances, nonces, eth_call, eth_estimateGas, eth_getLogs, receipts, or eth_sendRawTransaction. Remember the encoding conventions: BEATOZ-native methods accept 0x-optional hex for addresses/hashes, most Tendermint byte params take base64, abci_query.data takes hex without 0x, int64 response values are strings, and height/page params must be sent as strings.