¶ Web 3 API
This tool is designed to implement the following interaction
site (request) > dashboard (process) > node (response to request) > dashboard (package response) > site (receive response)
Request is a normal GET request to localhost:8045
¶ Request types
¶ 1. Connect()
Connect to the dashboard
Returns A unique session identifier (id) that is issued after successful connection to the dashboard, it must be sent in every request
¶ 2. GetNetworks (id)
Get all the networks
id
A unique session identifier
Returns
A list of networks
¶ 3. GetWallets (id)
Get all the wallets
id
A unique session identifier
Returns
A list of wallets
¶ 4. GetDataWallet (id,walletName)
Get the wallet by name
id
A unique session identifier
walletName
Wallet name
Returns
The data of a specific wallet (balances, networks, addresses, token names)
¶ 5. SendTransaction (id, net, walletName, toAddr, tokenName, value)
Issue a new transaction
id
A unique session identifier
net
Network name
walletName
Wallet name
toAddr
Wallet's address to send coins to
tokenName
Token name
value
Number of coins in datoshi (tokens * 10^18)
¶ 6. GetTransactions (id, addr, net)
Get transaction history by wallet on a specific network
session_id
A unique session identifier
addr
wallet address
net
network
Returns
Transaction's history for the target addr and net
¶ 7. TxCreateJson (id, json)
Creates a custom transaction with arbitrary number of items
session_id
A unique session identifier
json
generated according to the attachment at the end of article
¶ Examples
Request implementation in vue:
async GetWallets() {
try {
const response = await axios.get(this.engineUrl, {
params: {
method: 'GetWallets',
id: this.id
}
})
this.getWalletsData = response.data
} catch(error) {
console log(error)
}
}Test page: https://test-stake.cellframe.net/jhavblidhvil/dash/
¶ Notes
IMPORTANT
The session identifier (id) for accessing the dashboard is valid until the moment the dashboard (GUI) is restarted, i.e. you need to reconnect, otherwise the requests will be rejected.
During the shutdown of the GUI, all issued id are reset
¶ Responses
All responses from the dashboard come in the form of a json document with the following content:
In case everything is ok
{
"data": [ ],
"errorMsg": "",
"status": "ok"
}
¶ Examples
Normal response
{
"data": [
"token Wallet",
"myWallet"
],
"errorMsg": "",
"status": "ok"
}If an error or invalid request
{
"data": "",
"errorMsg": "textError",
"status": "bad"
}
{
"data": "",
"errorMsg": "Can't parse result. Socket connection err: 111\nCan't connect to cellframe-node\n",
"status": "bad"
}
¶ CLI commands
Description of the command to create a custom transaction tx_create_json
Command format
tx_create_json [-net <net name>] [-chain <chain name>] -json <json file path>If the network is not specified, then it must be in the json file
If the chain is not specified, then the transaction is created in the default chain for transactions
json file contains all information about the transaction being created
Command usage examples:
./cellframe-node-cli tx_create_json -json /home/dev/cellframe-node/tx.json
./cellframe-node-cli tx_create_json -json /home/dev/cellframe-node/tx.json -net mileena
./cellframe-node-cli tx_create_json -json /home/dev/cellframe-node/tx.json -net mileena -chain main
¶ json file format
Example:
{
"net" : "mileena",
"chain" : "main",
"items" : [ {
"type" : "in",
"prev_hash" : "0xB5A01C52D6AFAFD4860172F4057A9BDF5E7AAB5A5AD9BE574EA919DB27EFBC0B",
"out_prev_idx" : 2
}, {
"type" : "out",
"value" : "12345",
"addr" : "RpiDC8c1SxrTF3aSu2VL4Pwu8beWMY8ur71TeiR6ViBdnvMQCKudoWkvT8BGFN2ycKnHSaGm5WrNccex2qiZjA4PoEicUmWJNvRQQJYN"
},{
"type" : "sign",
"wallet" : "MyWallet123",
} ]
}The net and chain parameters define the network and chain where the transaction will be added. Network and chain take precedence from the command line if they are specified in the command and in the json file.
The items parameter is an array and contains a list of items in the transaction.
¶ Types
type [string] defines the item type, valid values: in, out, out_ext, sign, in_cond, out_cond, receipt
There can be several items of the same type.
Each type of item has its own additional parameters.
¶ Input
type in: Input
token[string] - token name
addr_from[string] - sender address, if there is prev_hash and out_prev_idx, then it is not required
prev_hash [string] - hash of the previous transaction, if the address is specified, then it is not required
out_prev_idx [int] - sequence number of the exit in the previous transaction, if the address is specified, then it is not required
One thing must be indicated, either the sender's address or the hash of the previous transaction with the number.
If an address is specified, then the hash and number are automatically searched for it, and an output item is created with change, if necessary,
if you specify a hash and a number, you need to take care of the change yourself
¶ Output
type: out
value[string] - amount of data to send
addr[string] - recipient's address
¶ Extended output
type: out_ext
value[string] - amount of data to send
addr[string] - recipient's address
token[string] - Token name
¶ Signature
type: sign
wallet - wallet for signing transactions
cert - certificate for signing the transaction
One thing must be specified, if there is both a wallet and a certificate, then the wallet is used
¶ Receipt
type: receipt
value[string] - board size in datoshi
unit[int] - Number of used units
price_unit[string] - What units are measured in, valid values: mb, bytes or b, sec, day, kb, pcs or pieces
service_id[int] - id of the service used, if not specified, then the service name parameter is searched - service
service[string] - Name of the service to use, valid values: fee, srv_vpn, srv_xchange, srv_stake
Service must be specified
params[string] - Additional parameters, this is an optional parameter
¶ Conditional input
type: in_cond
token[string] - token name
receipt_idx [int] - serial number of the receipt (receipt) in the transaction, if there is only one receipt in the current transaction, then it is not necessary to specify it,
and if there are several, then you need to indicate its serial number [counted from zero]
addr_from[string] - sender address, if there is prev_hash, out_prev_idx and receipt_idx, then it is not required
subtype [string] - defines the conditional input subtype, valid values: fee, srv_pay, srv_xchange, srv_vpn
prev_hash [string] - hash of the previous transaction, if the address and subtype are specified, then it is not required
out_prev_idx [int] - sequence number of the exit in the previous transaction, if the address and subtype are specified, then it is not required
One must be specified, either the sender's address with a subtype, or the hash of the previous transaction with a number and a check.
If the address and subtype are specified, then the hash and number are automatically searched for it, and an output item is created with change, if necessary,
if you specify a hash and a number, you need to take care of the change yourself.
¶ Conditional output
type: out_cond
subtype [string] - defines the conditional output subtype, each subtype has its own parameters, valid values: fee, srv_pay, srv_xchange, srv_stake
¶ Fee
subtype fee: Transaction fee
value[string] - commission amount in datasets
¶ Ordinary service payment
subtype srv_pay: Pay, currently only used for VPN service
value[string] - board size in datoshi
value_max_per_unit[string] - Maximum board size in datoshi per unit
price_unit[string] - What units are measured in, valid values: mb, bytes or b, sec, day, kb, pcs or pieces
service_id[int] - id of the service used, if not specified, then the service name parameter is searched - service
service[string] - Name of the service to use, valid values: srv_vpn, srv_xchange, srv_stake
If the service is not specified, then the default service is used - srv_vpn
params[string] - Padding
¶ Token exchange
subtype srv_xchange: xchange, currently only used for the exchange service
value[string] - board size in datoshi
token[string] - token name
net[string] - network name
service_id[int] - id of the service used, if not specified, then the service name parameter is searched - service
service[string] - Name of the service to use, valid values: srv_vpn, srv_xchange, srv_stake
If the service is not specified, then the default service is used - srv_xchange
params[string] - Additional parameters, this is an optional parameter
¶ Stake delegation for PoS family
subtype srv_stake: stake, currently only used for the staker service
value[string] - board size in datoshi
fee[string] - staker fee
fee_addr[string] - fee recipient address
hldr_addr[string] - holder address
signing_addr[string] - the address of the person who signs the transaction
service_id[int] - id of the service used, if not specified, then the service name parameter is searched - service
service[string] - Name of the service to use, valid values: srv_vpn, srv_xchange, srv_stake
If the service is not specified, then the default service is used - srv_stake
params[string] - Additional parameters, this is an optional parameter
¶ Attachment
{
"net" : "mileena",
"chain" : "main",
"items" : [ {
"type" : "in",
"prev_hash" : "0xB5A01C52D6AFAFD4860172F4057A9BDF5E7AAB5A5AD9BE574EA919DB27EFBC0B",
"out_prev_idx" : 2,
"token" : "COIN"
}, {
"type" : "in",
"addr_from" : "RpiDC8c1SxrTF3aSu2VL4Pwu8beWMY8ur71TeiR6ViBdnvMQCKudoWkvT8BGFN2ycKnHSaGm5WrNccex2qiZjA4PoEicUmWJNvRQQJYN",
"token" : "COIN"
}, {
"type" : "out",
"value" : "12345",
"addr" : "RpiDC8c1SxrTF3aSu2VL4Pwu8beWMY8ur71TeiR6ViBdnvMQCKudoWkvT8BGFN2ycKnHSaGm5WrNccex2qiZjA4PoEicUmWJNvRQQJYN",
"token" : "COIN"
}, {
"type" : "out_ext",
"value" : "100000000000",
"addr_from" : "RpiDC8c1SxrTF3aSteGk3THSTbS7MYfNLsYKqUsKn9NpeHQ4mVuTB4w4NHKp4qGFH71vXXSFTbJgjDGvyyS3zAtMwjyy33WVtALJW52Z",
"token" : "COIN"
}, {
"type" : "receipt",
"value" : "1000",
"units" : 50,
"price_unit" : "sec",
"service" : "srv_stake",
"params" : "add parameters"
}, {
"type" : "in_cond",
"prev_hash" : "0xE48B9C5BA30AD8E79525C3E1101EC5D6BE0837E1E44E1C8BA6D3C7B9CD077890",
"out_prev_idx" : 2,
"receipt_idx" : 0
}, {
"type" : "in_cond",
"subtype" : "srv_pay",
"addr_from" : "RpiDC8c1SxrTF3aSteGk3THSTbS7MYfNLsYKqUsKn9NpeHQ4mVuTB4w4NHKp4qGFH71vXXSFTbJgjDGvyyS3zAtMwjyy33WVtALJW52Z",
"token" : "COIN"
}, {
"type" : "out_cond",
"subtype" : "fee",
"value" : "100000000000"
}, {
"type" : "out_cond",
"subtype" : "srv_pay",
"value" : "1000",
"value_max_per_unit" : "100000",
"price_unit" : "sec",
"service_id" : 1,
"service" : "srv_vpn",
"params" : "add parameters"
}, {
"type" : "out_cond",
"subtype" : "srv_xchange",
"net" : "kelvin-testnet",
"service" : "srv_xchange",
"token" : "COIN",
"value" : "10000",
"params" : "add parameters"
}, {
"type" : "out_cond",
"subtype" : "srv_stake",
"service" : "srv_xchange",
"value" : "1230000000",
"fee" : "1000",
"fee_addr" : "RpiDC8c1SxrTF3aStZGbD94opb1SaJHAfkvcASyHz9DTrDs739WfvjJDLLGsvHJr8jb7tyiFkasuMFCgx1kjbXEFLV3G7YFQGV5ubaJK",
"hldr_addr" : "RpiDC8c1SxrTF3aSteGk3THSTbS7MYfNLsYKqUsKn9NpeHQ4mVuTB4w4NHKp4qGFH71vXXSFTbJgjDGvyyS3zAtMwjyy33WVtALJW52Z",
"signing_addr" : "RpiDC8c1SxrTF3aSteGk3THSTbS7MYfNLsYKqUsKn9NpeHQ4mVuTB4w4NHKp4qGFH71vXXSFTbJgjDGvyyS3zAtMwjyy33WVtALJW52Z",
"node_addr" : "F2F1::AC00::0000::0001",
"params" : "add parameters"
}, {
"type" : "sign",
"wallet" : "myk",
}, {
"type" : "sign",
"cert" : "mypvt"
} ]
}