Các RPC Endpoint
Ví dụ:
Send transaction
Sends transaction. Returns the guaranteed execution status and the results the blockchain can provide at the moment.
- method:
send_tx
- các param:
signed_tx_base64
: SignedTransaction encoded in base64- [Optional]
wait_until
: the required minimal execution level. Read more here. The default value isEXECUTED_OPTIMISTIC
.
Using send_tx
with wait_until = NONE
is equal to legacy broadcast_tx_async
method.
Using send_tx
with finality wait_until = EXECUTED_OPTIMISTIC
is equal to legacy broadcast_tx_commit
method.
Ví dụ về response nhận được:
- JSON
- HTTPie
{
"jsonrpc": "2.0",
"id": "dontcare",
"method": "send_tx",
"params": {
"signed_tx_base64": "DgAAAHNlbmRlci50ZXN0bmV0AOrmAai64SZOv9e/naX4W15pJx0GAap35wTT1T/DwcbbDwAAAAAAAAAQAAAAcmVjZWl2ZXIudGVzdG5ldNMnL7URB1cxPOu3G8jTqlEwlcasagIbKlAJlF5ywVFLAQAAAAMAAACh7czOG8LTAAAAAAAAAGQcOG03xVSFQFjoagOb4NBBqWhERnnz45LY4+52JgZhm1iQKz7qAdPByrGFDQhQ2Mfga8RlbysuQ8D8LlA6bQE=",
"wait_until": "INCLUDED_FINAL"
}
}
http post https://rpc.testnet.near.org jsonrpc=2.0 id=dontcare method=send_tx \
params:='{
"signed_tx_base64": "DgAAAHNlbmRlci50ZXN0bmV0AOrmAai64SZOv9e/naX4W15pJx0GAap35wTT1T/DwcbbDwAAAAAAAAAQAAAAcmVjZWl2ZXIudGVzdG5ldNMnL7URB1cxPOu3G8jTqlEwlcasagIbKlAJlF5ywVFLAQAAAAMAAACh7czOG8LTAAAAAAAAAGQcOG03xVSFQFjoagOb4NBBqWhERnnz45LY4+52JgZhm1iQKz7qAdPByrGFDQhQ2Mfga8RlbysuQ8D8LlA6bQE=",
"wait_until": "EXECUTED"
}'
http post https://rpc.testnet.near.org jsonrpc=2.0 id=dontcare method=send_tx \
params:='{
"signed_tx_base64": "DgAAAHNlbmRlci50ZXN0bmV0AOrmAai64SZOv9e/naX4W15pJx0GAap35wTT1T/DwcbbDwAAAAAAAAAQAAAAcmVjZWl2ZXIudGVzdG5ldNMnL7URB1cxPOu3G8jTqlEwlcasagIbKlAJlF5ywVFLAQAAAAMAAACh7czOG8LTAAAAAAAAAGQcOG03xVSFQFjoagOb4NBBqWhERnnz45LY4+52JgZhm1iQKz7qAdPByrGFDQhQ2Mfga8RlbysuQ8D8LlA6bQE="
}'
Các kết quả cuối cùng của transaction có thể được query qua Transaction Status hoặc NEAR Explorer bằng cách sử dụng kết quả
hash được trả về như ví dụ sau đây.
{
"jsonrpc": "2.0",
"result": {
"final_execution_status": "FINAL",
"status": {
"SuccessValue": ""
},
"transaction": {
"signer_id": "sender.testnet",
"public_key": "ed25519:Gowpa4kXNyTMRKgt5W7147pmcc2PxiFic8UHW9rsNvJ6",
"nonce": 13,
"receiver_id": "receiver.testnet",
"actions": [
{
"Transfer": {
"deposit": "1000000000000000000000000"
}
}
],
"signature": "ed25519:7oCBMfSHrZkT7tzPDBxxCd3tWFhTES38eks3MCZMpYPJRfPWKxJsvmwQiVBBxRLoxPTnXVaMU2jPV3MdFKZTobH",
"hash": "ASS7oYwGiem9HaNwJe6vS2kznx2CxueKDvU9BAYJRjNR"
},
"transaction_outcome": {
"proof": [],
"block_hash": "9MzuZrRPW1BGpFnZJUJg6SzCrixPpJDfjsNeUobRXsLe",
"id": "ASS7oYwGiem9HaNwJe6vS2kznx2CxueKDvU9BAYJRjNR",
"outcome": {
"logs": [],
"receipt_ids": ["BLV2q6p8DX7pVgXRtGtBkyUNrnqkNyU7iSksXG7BjVZh"],
"gas_burnt": 223182562500,
"tokens_burnt": "22318256250000000000",
"executor_id": "sender.testnet",
"status": {
"SuccessReceiptId": "BLV2q6p8DX7pVgXRtGtBkyUNrnqkNyU7iSksXG7BjVZh"
}
}
},
"receipts_outcome": [
{
"proof": [],
"block_hash": "5Hpj1PeCi32ZkNXgiD1DrW4wvW4Xtic74DJKfyJ9XL3a",
"id": "BLV2q6p8DX7pVgXRtGtBkyUNrnqkNyU7iSksXG7BjVZh",
"outcome": {
"logs": [],
"receipt_ids": ["3sawynPNP8UkeCviGqJGwiwEacfPyxDKRxsEWPpaUqtR"],
"gas_burnt": 223182562500,
"tokens_burnt": "22318256250000000000",
"executor_id": "receiver.testnet",
"status": {
"SuccessValue": ""
}
}
},
{
"proof": [],
"block_hash": "CbwEqMpPcu6KwqVpBM3Ry83k6M4H1FrJjES9kBXThcRd",
"id": "3sawynPNP8UkeCviGqJGwiwEacfPyxDKRxsEWPpaUqtR",
"outcome": {
"logs": [],
"receipt_ids": [],
"gas_burnt": 0,
"tokens_burnt": "0",
"executor_id": "sender.testnet",
"status": {
"SuccessValue": ""
}
}
}
]
},
"id": "dontcare"
}
Sự cố nào có thể xảy ra?
Khi API request không thành công, RPC server sẽ trả về một error response được cấu trúc sẵn, với một số lượng giới hạn các error variant đã được định nghĩa rõ ràng, từ đó client code có thể handle toàn bộ các error case có thể xảy ra. Các JSON-RPC error của chúng tôi tuân theo quy ước verror để cấu trúc cho error response:
{
"error": {
"name": <ERROR_TYPE>,
"cause": {
"info": {..},
"name": <ERROR_CAUSE>
},
"code": -32000,
"data": String,
"message": "Server error",
},
"id": "dontcare",
"jsonrpc": "2.0"
}
Chú ý
Các field
code
,data
, vàmessage
trong structure trên là những field kế thừa từ Verror và có thể không được dùng nữa trong tương lai. Do đó vui lòng không sử dụng chúng.
Ví dụ:
ERROR_TYPE | ERROR_CAUSEerror.cause.name | Nguyên nhân | Giải pháp |
---|---|---|---|
HANDLER_ERROR | INVALID_TRANSACTION | Một eror đã xảy ra trong quá trình thực thi transaction |
|
TIMEOUT_ERROR | Transaction đã được định tuyến (route), nhưng chưa được record trên chain sau 10 giây. |
| |
REQUEST_VALIDATION_ERROR | PARSE_ERROR | Đã pass các argument mà JSON RPC server không thể parse được (thiếu các argument, sai format, v.v...) |
|
INTERNAL_ERROR | INTERNAL_ERROR | Đã xảy ra lỗi với chính node đó, hoặc bị overload |
|
Status của Transaction
Query status của một transaction bằng hash và trả về kết quả cuối cùng của transaction.
- method:
tx
- các param:
tx_hash
(see NearBlocks Explorer for a valid transaction hash)sender_account_id
(used to determine which shard to query for transaction)- [Optional]
wait_until
: the required minimal execution level. Read more here. The default value isEXECUTED_OPTIMISTIC
.
A Transaction status request with wait_until != NONE
will wait until the transaction appears on the blockchain. If the transaction does not exist, the method will wait until the timeout is reached. If you only need to check whether the transaction exists, use wait_until = NONE
, it will return the response immediately.
Dưới đây là danh sách đầy đủ các error variant có thể được trả về theo loại request view_access_key_list
:
- JSON
- HTTPie
{
"jsonrpc": "2.0",
"id": "dontcare",
"method": "tx",
"params": {
"tx_hash": "6zgh2u9DqHHiXzdy9ouTP7oGky2T4nugqzqt9wJZwNFm",
"sender_account_id": "sender.testnet",
"wait_until": "EXECUTED"
}
}
http post https://rpc.testnet.near.org jsonrpc=2.0 id=dontcare method=tx \
params:='{"tx_hash": "6zgh2u9DqHHiXzdy9ouTP7oGky2T4nugqzqt9wJZwNFm", "sender_account_id": "sender.testnet"}'
Ví dụ kết quả nhận được là:
{
"jsonrpc": "2.0",
"result": {
"final_execution_status": "FINAL",
"status": {
"SuccessValue": ""
},
"transaction": {
"signer_id": "sender.testnet",
"public_key": "ed25519:Gowpa4kXNyTMRKgt5W7147pmcc2PxiFic8UHW9rsNvJ6",
"nonce": 15,
"receiver_id": "receiver.testnet",
"actions": [
{
"Transfer": {
"deposit": "1000000000000000000000000"
}
}
],
"signature": "ed25519:3168QMdTpcwHvM1dmMYBc8hg9J3Wn8n7MWBSE9WrEpns6P5CaY87RM6k4uzyBkQuML38CZhU18HzmQEevPG1zCvk",
"hash": "6zgh2u9DqHHiXzdy9ouTP7oGky2T4nugqzqt9wJZwNFm"
},
"transaction_outcome": {
"proof": [
{
"hash": "F7mL76CMdfbdZ3xCehVGNh1fCyaR37gr3MeGX3EZkiVf",
"direction": "Right"
}
],
"block_hash": "ADTMLVtkhsvzUxuf6m87Pt1dnF5vi1yY7ftxmNpFx7y",
"id": "6zgh2u9DqHHiXzdy9ouTP7oGky2T4nugqzqt9wJZwNFm",
"outcome": {
"logs": [],
"receipt_ids": ["3dMfwczW5GQqXbD9GMTnmf8jy5uACxG6FC5dWxm3KcXT"],
"gas_burnt": 223182562500,
"tokens_burnt": "22318256250000000000",
"executor_id": "sender.testnet",
"status": {
"SuccessReceiptId": "3dMfwczW5GQqXbD9GMTnmf8jy5uACxG6FC5dWxm3KcXT"
}
}
},
"receipts_outcome": [
{
"proof": [
{
"hash": "6h95oEd7ih62KXfyPT4zsZYont4qy9sWEXc5VQVDhqtG",
"direction": "Right"
},
{
"hash": "6DnibgZk1T669ZprcehUy1GpCSPw1kjzXRGu69nSaUNn",
"direction": "Right"
}
],
"block_hash": "GgFTVr33r4MrpAiHc9mr8TZqLnpZAX1BaZTNvhBnciy2",
"id": "3dMfwczW5GQqXbD9GMTnmf8jy5uACxG6FC5dWxm3KcXT",
"outcome": {
"logs": [],
"receipt_ids": ["46KYgN8ddxs4Qy8C7BDQH49XUfcYZsaQmAvdU1nfcL9V"],
"gas_burnt": 223182562500,
"tokens_burnt": "22318256250000000000",
"executor_id": "receiver.testnet",
"status": {
"SuccessValue": ""
}
}
},
{
"proof": [
{
"hash": "CD9Y7Bw3MSFgaPZzpc1yP51ajhGDCAsR61qXcMNcRoHf",
"direction": "Left"
}
],
"block_hash": "EGAgKuW6Bd6QKYSaxAkx2pPGmnjrjAcq4UpoUiqMXvPH",
"id": "46KYgN8ddxs4Qy8C7BDQH49XUfcYZsaQmAvdU1nfcL9V",
"outcome": {
"logs": [],
"receipt_ids": [],
"gas_burnt": 0,
"tokens_burnt": "0",
"executor_id": "sender.testnet",
"status": {
"SuccessValue": ""
}
}
}
]
},
"id": "dontcare"
}