Skip to main content

Introduction

All transaction interfaces use Post request method, and the data format of the request parameters is JSON.

Step​

Constructing a transaction​

According to different interfaces, different parameter values are passed in. The interfaces for sending transactions include /GetTransaction, /GetStakeTransaction, /GetUnStakeTransaction,/GetInvestTransaction, /GetDisInvestTransaction, /GetBouns etc

Signature of transaction entity​

Based on the content returned by the interface above, use SDK to Sign the transaction entity.

Broadcast transaction​

The signed transaction body is used as a parameter to generate a /SendMessage for broadcasting the transaction.

Confirm transaction​

After the transaction is sent, use the /ConfirmTransaction interface to check if the transaction is on chain.

Signature Method​

There are two ways to sign a transaction:

Signature MethodSignature fieldAdvantage
txJsonSign(message,privatePkey)Sign the txJson field of the return body1. Not distinguishing transaction types
2. Easy to maintain in the later stage
sig_tx(message,message_size,privatePkey)Sign the entire transaction return result body1. Easy to use
2. Only need to determine the transaction type
sig_contract_tx(message,message_size,privatePkey)Sign the return values of the contract related interfaces

txJsonSign()​

Sign the txJson in the result field of the transaction return value, pass in the message to be signed and the private key handle, and return the signed message

txJson = ...;
message = txJson;
message_size = message.length;
signature = api.txJsonSign(message,privatePkey);

sig_tx()​

Sign the non contract transactions returned by /GetTransaction (GetStakeTransaction,GetUnStakeTransaction,GetInvestTransaction,GetDisInvestTransaction,GetBounss, etc.), sign the entire return body as the message value, message length, and private key handle, and return the signed message

message = tx;
message_size = message.length;
signature = api.sig_tx(message,message_size,privatePkey);

sig_contract_tx()​

Sign the contract transaction returned by the /GetDeployContractTransaction or /GetCallContractTransaction interface, pass in the message to be signed, the message length and private key handle, and return the signed transaction JSON.

message = tx;
message_size = message.length;
signature = api.sig_contract_tx(message,message_size,privatePkey);

Transaction on chain​

Determine whether the transaction has been successfully uploaded to the blockchain

  1. First, obtain the node height, call the GetBlockNumber interface, and obtain the top field value in the returned result as the node height.
  2. Call the ConfirmTransaction interface again.
  • Parameter:
    • height: Pass the top field value returned by the GetBlockNumber interface
    • txHash: The txHash value returned by calling the SendMessage or SendContractMessage interface when sending a transaction

The ConfirmTransaction interface returns a percent value field greater than or equal to 0.8, indicating a successful transaction on the chain.

Attention in transactions​

Attention should be paid when making transactions

  1. Determine the time difference between this transaction and the previous transaction sent on this account.

    • Within 30 seconds of the time difference, it is necessary to determine whether the previous transaction has been successfully uploaded to the blockchain. If it has been successfully on chain, the current transaction will be sent. If it has not been successfully on chain, the user will be prompted with frequent operations.
    • If the time difference is greater than or equal to 30 seconds, directly send this transaction.

  2. Check if the code in the result returned by the interface is 0 to confirm if the interface call is functioning properly. The next interface call can only be made when the code for the interface call is 0.

  3. In the process of sending transactions, it is necessary to parse the content of the interface return body and cache useful information such as gas, time, height, txHash and other fields in the return structure to your database or device terminal.

Because the gas fee needs to be displayed to the user when sending the transaction, and after the transaction is completed, the ConfirmTransaction interface needs to be called to confirm and query the successful on chain transaction.

API use example​

The following is an example of sending mainnet transactions

1. GetTransaction​

Send the transaction body and obtain the regular transaction body through the GetTransaction RPC interface (see RPC documentation for details)

Parameter​

{
    "id": "",
    "jsonrpc": "",
    "params": {
        "fromAddr": [
            "cED97dA085527Fe7e1772CA59Aa1e64A78143128"
        ],
        "isFindUtxo": false,
        "toAddr": [
            {
                "addr": "06BA76F46631d4F344d1344303895001F1E3Af29",
                "value": "13.5"
            }
        ],
        "txInfo": ""
    }
}

Response​

{
  "id": "",
  "jsonrpc": "",
  "method": "GetTransaction",
  "result": {
    "code": 0,
    "gas": "20200",
    "height": "2506",
    "message": "success",
    "time": "1717557136905780",
    "txJson": "{\"time\":\"1717557136905780\",\"identity\":\"0796B6DB27e5eb1e9F8Bd2c4d03191C902D22F0f\",\"utxo\":{\"owner\":[\"cED97dA085527Fe7e1772CA59Aa1e64A78143128\"],\"vin\":[{\"prevOut\":[{\"hash\":\"26cc05fef65e94c15d759a27a24a57793253f25a3dece8e7761024ab0d0220dd\"}]}],\"vout\":[{\"value\":\"1350000000\",\"addr\":\"06BA76F46631d4F344d1344303895001F1E3Af29\"},{\"value\":\"1978395583553\",\"addr\":\"cED97dA085527Fe7e1772CA59Aa1e64A78143128\"},{\"value\":\"20200\",\"addr\":\"VirtualBurnGas\"}]},\"type\":\"Tx\",\"consensus\":7,\"txType\":1}",
    "txType": "0",
    "vrfJson": "{}"
  }
}

2. txJsonSign(message,privatePkey)​

Sign the txJson field of the return body.

txJson = ...;
message = txJson;
message_size = message.length;
signature = api.txJsonSign(message,privatePkey);

Signed structure​

{
    "id": "",
    "jsonrpc": "",
    "result": {
        "code": "",
        "gas": "20200",
        "height": "600",
        "message": "",
        "time": "1717148047269517",
        "txJson": "{\"time\":\"1717148047269517\",\"identity\":\"2eb2F635320c3Dbf29eadD35E894c13EE3F20bd5\",\"utxo\":{\"owner\":[\"cED97dA085527Fe7e1772CA59Aa1e64A78143128\"],\"vin\":[{\"prevOut\":[{\"hash\":\"3f1342e96e426e2905021ad991787131ec70d31298646b1e80da9d912eeff274\"}],\"vinSign\":{\"sign\":\"ApxL8NDgh9YYDuUXpdbsbVv0cEAr3HyXmr2TICkD4mfuDIZqVlZJNUmaPAKHCs5kkn7JnZx7r12+CpnnR4ZpAg==\",\"pub\":\"MCowBQYDK2VwAyEA89VSBQU7d4uL+jvqAKeCRbgYz2tzk/Rf8DNRhB0sLbg=\"}}],\"vout\":[{\"value\":\"1350000000\",\"addr\":\"06BA76F46631d4F344d1344303895001F1E3Af29\"},{\"value\":\"1982446992477\",\"addr\":\"cED97dA085527Fe7e1772CA59Aa1e64A78143128\"},{\"value\":\"20200\",\"addr\":\"VirtualBurnGas\"}],\"multiSign\":[{\"sign\":\"WCoFsLKML69x1rSpQc7pwbnd+GMfZ0Ce3wTPg96Rdb1v7ezFw9KuEBXwvGecTz264pVZB6T8hzgJIx26GuKVAA==\",\"pub\":\"MCowBQYDK2VwAyEA89VSBQU7d4uL+jvqAKeCRbgYz2tzk/Rf8DNRhB0sLbg=\"}]},\"type\":\"Tx\",\"consensus\":7,\"txType\":1}",
        "txType": "1",
        "vrfJson": "{\"vrfdata\":{\"hash\":\"6cf89d80c98eecd9138caca4f55d7ad0fda2aed9d8e68dd4642543ae3ee056d6\"},\"Vrfsign\":{\"sign\":\"u5dNZ16Rd77B4nLd8gAcKTwz+GxeHH1HIlcGennGbPaKgIFXUkmFzS/EnVxRC4nmSfESAdWyMEmj4pKBhwuqAg==\",\"pub\":\"MCowBQYDK2VwAyEAcUcydwF7CSr9bjBiUbd3drV+WMd4yd8xFL7HWGA4FTw=\"}}"
    }
}

Add vinSign,multiSign signature data in txJson, and determine whether the signature is successful by adding Sign data

"vinSign":{sign:"ApxL8NDgh9YYDuUXpdbsbVv0cEAr3HyXmr2TICkD4mfuDIZqVlZJNUmaPAKHCs5kkn7JnZx7r12+CpnnR4ZpAg==",pub:"MCowBQYDK2VwAyEA89VSBQU7d4uL+jvqAKeCRbgYz2tzk/Rf8DNRhB0sLbg="}

"multiSign":[{sign:"WCoFsLKML69x1rSpQc7pwbnd+GMfZ0Ce3wTPg96Rdb1v7ezFw9KuEBXwvGecTz264pVZB6T8hzgJIx26GuKVAA==",pub:"MCowBQYDK2VwAyEA89VSBQU7d4uL+jvqAKeCRbgYz2tzk/Rf8DNRhB0sLbg="}]

3. SendMessage​

Using the signed structure as a parameter, send the transaction to the node through the SendMessage interface to complete the transaction

Response

{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "SendMessage",
    "result": {
        "code": 0,
        "message": "success",
        "txHash": "0x01f46aaee0d0d87f1164d9dda4154544cc67627b70d512805fd85c0f92a45706"
    }
}

4. ConfirmTransaction​

Use the height obtained from interface 1.GetTransaction and the txHash obtained from interface 3.SendMessage to query whether the transaction is on chain.

Parameter

{
  "id":"1",
  "jsonrpc":"2.0",
  "params":{
      "txhash":"0x01f46aaee0d0d87f1164d9dda4154544cc67627b70d512805fd85c0f92a45706",
      "height": "2506"
    }
}

The /ConfirmTransaction interface returns a percent >= 0.8, indicating a successful transaction on the chain.

Transaction body details​

  • Consensus: Consensus quantity
  • identity: Packager
  • time: Transaction time
  • txHash: Transaction hash
  • type: The default field is Tx
  • utxo
    • multisign: UTXO's signature
      • pub: Public key base64
      • sign: Signature based on 64
    • owner: The initiator of the transaction
    • vin
      • prevout
        • hash: Vin's transaction hash
      • vinsign: Vin's signature
        • pub: Public key base64
        • sign: Signature based on 64
    • vout
      • addr: Target account for transfer
      • value: Transfer amount
  • verifySign: Transaction signature information
    • pub: Public key base64
    • sign: Signature based on 64
    • signaddr: Address of the signing node
  • txType: transaction type
    • 0: Unknown transaction type
    • 1: Transfer transaction
    • 2: Pledge transaction
    • 3: Pledge release transaction
    • 4: invest
    • 5: Resolve investment transactions
    • 7: Deploy contract
    • 8: Execute contract
    • 99: Apply for transaction
  • data
    • Stake transaction
      • TxInfo: Stake transaction information
        • CommissionRate: Pumping ratio
        • StakeAmount: Stake amount
        • StakeType: Stake type, default is Net
    • Stake release transaction
      • TxInfo: Stake release transaction information
        • UnstakeUtxo: UTXO for Stake transactions
    • Investment transactions
      • TxInfo Investment transaction information
        • BonusAddr: Investment address
        • InvestAmount: investment amount
        • InvestType: Investment type, default is Normal
    • Resolve investment transactions
      • TxInfo resolve investment transaction information
        • BonusAddr: Investment address
        • DisinvestUtxo: Invest in UTXO
    • Apply for transaction
      • TxInfo Apply for transaction information
        • BonusAddrList: Number of applied addresses
        • BonusAmount: Application amount