Skip to main content

Encoding Examples

Encoding Output​

BNB Beacon Chain (Amino) encoding logic may encode a data structure into two output formats: Binary and JSON.

JSON Marshal​

Amino supports JSON encoding natively, which is the same as other usual json marshalers. Except that it can add one more type info for registered type, as shown below.

{
"type": "<amino type name>",
"value": <JSON>
}

Examples in Go-SDK​

Let's take a look at an example function of BNB Beacon Chain go-sdk.

func (c *HTTP) GetProposal(proposalId int64) (types.Proposal, error) {
params := types.QueryProposalParams{
ProposalID: proposalId,
}
bz, err := c.cdc.MarshalJSON(params)
if err != nil {
return nil, err
}
rawProposal, err := c.ABCIQuery("custom/gov/proposal", bz)
if err != nil {
return nil, err
}
if !rawProposal.Response.IsOK(){
return nil, fmt.Errorf(rawProposal.Response.Log)
}
var proposal types.Proposal

err = c.cdc.UnmarshalJSON(rawProposal.Response.GetValue(), &proposal)
return proposal, err
}

In order to query the proposal, you can use Amino to marshal the request JSON first.

  bz, err := c.cdc.MarshalJSON(params)

Then, use the unmarshal method to get the returned result.

  err = c.cdc.UnmarshalJSON(rawProposal.Response.GetValue(), &proposal)

Binary Marshal​

Binary encoding is a variant of Google protocol buffer. The bytes are layed out in the below sequence:

  1. a varint encoded integer - it contains the length of the encoded bytes for the object, which is displayed as SIZE-OF-ENCODED in the below structs. Please note that it contains the length of encoded bytes and also the type prefix (below), but not itself, e.g. if the encoded msg is 20 bytes, then the length would be 20 + 4 = 24, while 4 is used for the type prefix bytes.
  2. an object type prefix of 4-8 bytes - For different type of objects, there will be different type prefixes, and they are displayed as in the specific objects below (data structures).
  3. a binary encoded object - the encoding is mostly the same as protocol buffer encoding mechanism, except the embedded fields of complex type:
    • to encode data field of some specific types, an object type prefix for the field will be added ahead of the real encoding.
  4. repeated (array) Encoding - it is the same as google protocol buffer, while encoding of the object/struct may contain the type prefix as shown below.

Examples in Go-SDK​

Let's take a look at an example function of BNB Beacon Chain go-sdk. The signed transaction needs to be amino-encoded, thus ready to be posted to BncChain API.

rawBz, err := c.keyManager.Sign(*signMsg)
if err != nil {
return nil, err
}
hexTx := []byte(hex.EncodeToString(rawBz))
param := map[string]string{}
if sync {
param["sync"] = "true"
}
commits, err := c.basicClient.PostTx(hexTx, param)

hexTx is derived from the following function:

  bz, err := tx.Cdc.MarshalBinaryLengthPrefixed(&newTx)

BNB Beacon Chain Transaction Encoding​

Below are the data types that can be sent to BNB Beacon Chain as requests, and their encoding layout. To simplify the presentation, we will use a variant of Google protocol buffer proto3 language to illustrate how the data fields are organized. Except the all-capitalized fields, other fields will use the default proto3 encoding logic.

Standard Transaction​

Transactions are each wrapped in the below "Standard Transaction": structure:

// please note the field name is the JSON name.
message StdTx {
uint64 SIZE-OF-ENCODED // varint encoded length of the structure after encoding, please note this includes both the below type prefix (4 bytes) and the all encoding bytes
0xF0625DEE // hardcoded, object type prefix in 4 bytes
repeated Msg msgs // array of size 1, containing the transaction message, which are one of the transaction types below. please check the above "Array Encoding"
repeated StdSignature signatures // array of size 1, containing the standard signature structure of the transaction sender
string memo // a short sentence of remark for the transaction. Please only `Transfer` transaction allows 'memo' input, and other transactions with non-empty `Memo` will be rejected.
int64 source // an identifier for tools triggerring this transaction, set to zero if unwilling to disclose.
bytes data // byte array, reserved for future use
}

StdSignBytes​

type StdSignDoc struct {
AccountNumber int64 `json:"account_number"`
ChainID string `json:"chain_id"`
Memo string `json:"memo"`
Msgs []json.RawMessage `json:"msgs"`
Sequence int64 `json:"sequence"`
Source int64 `json:"source"`
Data []byte `json:"data"`
}

Canonical Bytes for Signing​

A transaction signature is not formed from the Amino-encoded transaction bytes themselves. Rather, a canonical representation of the transaction is generated in JSON format for signing.

This would allow for clients to sign a transaction off-chain, for example, a hardware HSM device like a Ledger, or within a micro-service in an algorithmic trading system. For example an external system will not have to understand Amino encoding to be able to approve of the transaction's content and produce the signed JSON string.

The canonical bytes for signing are generated from the StdSignBytes method. It produces a JSON string similar to the format below (formatted for clarity):

{
"sequence" : "64",
"account_number" : "12",
"data" : null,
"chain_id" : "chain-bnb",
"memo" : "smiley",
"msgs" : [
{
"inputs" : [
{
"coins" : [
{
"denom" : "BNB",
"amount" : "200000000"
}
],
"address" : "bnc1hgm0p7khfk85zpz5v0j8wnej3a90w7098fpxyh"
}
],
"outputs" : [
{
"address" : "bnc1cku54wwn66w2rkgs3h6v5zxrwtzyew8chcl720",
"coins" : [
{
"denom" : "BNB",
"amount" : "200000000"
}
]
}
]
}
],
"source" : "1"
}

This JSON string, with all whitespace removed and keys sorted in alphabetical order, is signed with the private key of the sender. This signature is then attached to the StdTx structure described in the above section. Please note that the transaction broadcasted to the blockchain is not JSON - the JSON is merely used as a canonical representation to generate the signature.

The next section describes how the generated signature is attached to a transaction.

Standard Signature​

The sender's signature is stored in the Standard Transaction data via a Standard Signature, as shown below. This structure is included in the StdTx (see above).

Please note that StdSignature itself doesn't have type prefix, while the PubKey does.

message StdSignature {
uint64 SIZE-OF-ENCODED // varint encoded length of the structure after encoding
// please note there is no type prefix for StdSignature
message PubKey {
0xEB5AE987 // hardcoded, object type prefix in 4 bytes
uint64 SIZE-OF-ENCODED // varint encoded length of the bytes below
bytes // no name or field id, just encode the bytes
}
PubKey pub_key // public key bytes of the signer address
bytes signature // signature bytes, please check chain access section for signature generation
int64 account_number // another identifier of signer, which can be read from chain by account REST API or RPC
int64 sequence // sequence number for the next transaction of the client, which can be read from the chain by account REST API or RPC. Please check chain acces section for details.
}

Message Types​

Messages represent the individual operations possible on BNB Beacon Chain , and these can be inserted into StdTx.msgs field. Message types are otherwise known as "transaction types", and these terms are used interchangeably in this document and in our technical documentation. So far every StdTx transaction "container" can only contain one "message".

Transfer​

Transfer is the transaction for transferring funds to different addresses.

// please note the field name is the JSON name.
message Send {
0x2A2C87FA // hardcoded, object type prefix in 4 bytes
message Token {
string denom
int64 amount
}
message Input {
bytes address
repeated Token coins
}
message Output {
bytes address
repeated Token coins
}
repeated Input inputs
repeated Output outputs
}

Freeze​

Freeze transaction will move the amount of the tokens into a frozen state, in which they cannot be used for transfers or sending new orders.

// please note the field name is the JSON name.
message TokenFreeze {
0xE774B32D // hardcoded, object type prefix in 4 bytes
bytes from // owner address
string symbol // token symbol, in full name with "-" suffix
int64 amount // amount of tokens to freeze
}

Unfreeze​

Unfreeze will reversely turn the amount of frozen tokens back to free state.

// please note the field name is the JSON name.
message TokenUnfreeze {
0x6515FF0D // hardcoded, object type prefix in 4 bytes
bytes from // owner address
string symbol // token symbol, in full name with "-" suffix
int64 amount // amount of tokens to unfreeze
}

Vote​

Vote transactions for proposals.

// please note the field name is the JSON name.
message Vote {
0xA1CADD36 // hardcoded, object type prefix in 4 bytes
int64 proposal_id // ID of the proposal
bytes voter // address of the voter
uint64 option // option from OptionSet chosen by the voter
}

Below are options for option:

OptionYes           = 0x01  // yes
OptionAbstain = 0x02 // abstain
OptionNo = 0x03 // no
OptionNoWithVeto = 0x04 // no with veto

Issue​

Issue (create) new asset on BNB Beacon Chain .

message IssueTokenValue  {
0x17EFAB80 // hardcoded, object type prefix in 4 bytes
bytes from // issuer's address
string name // token name
string symbol // token symbol
string total_supply // total supply
bool mintable // is mintable
}

Mint​

Mint is used to increase the total supply of a token.

message Mint {
0x467E0829 // hardcoded, object type prefix in 4 bytes
bytes from // sender's address
string symbol string // token symbol
int64 amount // increase amount
}

Burn​

Burn is used to decrease the total supply of a token.

message TokenBurn {
0x7ED2D2A0 // hardcoded, object type prefix in 4 bytes
bytes from // sender's address
string symbol string // token symbol
int64 amount // increase amount
}

Submit Proposal​

Submit proposal is used to create a proposal for validators about adding trading pairs

message Submit{
0xB42D614E // hardcoded, object type prefix in 4 bytes
string title // Title of the proposal
string description // Description of the proposal
byte proposal_type // Type of proposal. Initial set {PlainTextProposal, SoftwareUpgradeProposal,ListTradingPair, FixedFeeParams}
bytes proposer // Address of the proposer
message Coin {
string denom
int64 amount
}
int64 VotingPeriod // Length of the voting period (s)
}

Deposit​

Deposit is used to increase the total deposit of a proposal.

message Deposit{
0xA18A56E5 // hardcoded, object type prefix in 4 bytes
int64 ProposalID // ID of the proposal
bytes Depositer // Address of the depositer
message Coin {
string denom
int64 amount
}
}

Set Account Flags​

You can set the flag value of your account.

message SetAccountFlags{
0xBEA6E301 // hardcoded, object type prefix in 4 bytes
bytes from // sender's address
int64 flag // account flag
}

Time-lock​

You can only lock tokens on your own account for a certain period of time.

message Timerelock{
0x07921531 // hardcoded, object type prefix in 4 bytes
bytes from // sender's address
string description // Description of the lock
message Coin {
string denom
int64 amount
}
repeated Coin amount
int64 lock_time // lock time
}

Time-unlock​

You can unlock tokens on your own account after a certain period of time.

message Timeunlock{
0xC4050C6C // hardcoded, object type prefix in 4 bytes
bytes from // sender's address
int64 id // lock time id
}

Time-relock​

You can relock tokens on your own account after a certain period of time.

message Timerelock{
0x504711DA // hardcoded, object type prefix in 4 bytes
bytes from // sender's address
int64 Id // lock time id
string description // Description of the lock
message Coin {
string denom
int64 amount
}
repeated Coin amount
int64 lock_time // lock time
}

HTLT​

Hash Timer Locked Transfer (HTLT) is a new transaction type on BNB Beacon Chain , to serve as HTLC in the first step of Atomic Swap

message HTLT{
0xB33F9A24 // hardcoded, object type prefix in 4 bytes
bytes from // sender's address
bytes to // receiver's address
string recipient_other_chain
string sender_other_chain
bytes random_number_hash
int64 timestamp
message Coin {
string denom
int64 amount
}
repeated Coin amount
string expected_income
int64 height_span
bool cross_chain
}

Deposit HTLT​

Deposit Hash Timer Locked Transfer is to lock new BEP2 asset to an existed HTLT which is for single chain atomic swap.

message DepositHTLT{
0x63986496 // hardcoded, object type prefix in 4 bytes
bytes from // sender's address
message Coin {
string denom
int64 amount
}
repeated Coin amount
bytes swap_id
}

Claim HTLT​

Claim Hash Timer Locked Transfer is to claim the locked asset by showing the random number value that matches the hash. Each HTLT locked asset is guaranteed to be release once.

message ClaimHTLTMsg{
0xC1665300 // hardcoded, object type prefix in 4 bytes
bytes from // sender's address
bytes swap_id
bytes random_number
}

Refund HTLT​

Refund Hash Timer Locked Transfer is to refund the locked asset after timelock is expired.

message RefundHTLTMsg{
0x3454A27C // hardcoded, object type prefix in 4 bytes
bytes from // sender's address
bytes swap_id