5. WEB3 API

API description

This API is designed for provide following interaction:

Request is just a usual GET request on localhost:8045

Contents:

Request types

Request structure:

Request Name
function (parameters)
request description

1. Connect

Connect () connect to Cellframe Wallet

After successful connection you will receive a unique ID, which will be used in any request.

Important

ID is given during the GUI or Wallet session. Upon restarting one of these, you have to execute “Connect()” again for work with WEB API.

2. GetNetworks

GetNetworks (id) get network list

3. GetWallets

GetWallets (id) get wallets list

Request example on 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)
      }
    }

4. GetDataWallet

GetDataWallet (id,walletName) get data (balance, networks, addresses, token tickers) from the specified wallet

walletName - name of the wallet

5. SendTransaction

SendTransaction (id, net, walletName, toAddr, tokenName, value) execute transaction

net - name of the network
walletName - name of the wallet
toAddr - address of the wallet for coin transfer
tokenName - name of the token
value - quantity of coins in datoshi (token *10^18)

6. GetTransactions

GetTransactions (id, addr, net) get transaction history for every wallet in the specified network

 addr - address of the wallet
 net - name of the network

7. TxCreateJson

TxCreateJson (id, json) create custom transaction from JSON.file with arbitrary parameters

JSON file is created corresponding to JSON structure in the Application

8. GetLedgerTxHash

GetLedgerTxHash (id, hashTx, net) get information about specified transaction in the ledger

hashTx- hash of the transaction
net - name of the network

9. GetCertificates

GetCertificates(id, categoryCert) get certificates list

categoryCert - private\public\all

10. CreateCertificate

CreateCertificate(id, certType, certName, categoryCert) create certificate with specified name and type

certType - sig_dil\sig_bliss\sig_picnic (sig_dil is by default)
categoryCert - private\public

11. StakeLockTake

StakeLockTake(id, walletName, net, hashTx) get stacked coins

walletName - name of the wallet
net - name of the network
hashTx - hash of the transaction

12. StakeLockHold

StakeLockHold(id, tokenName, walletName, timeStaking,net, value, reinvest, stakeNoBaseFlag) create staking transaction

tokenName - name of the token
timeStaking - time until unstaking (YYMMDD) 
value - coins value for staking 
reinvest - percent of reward reinvesting
stakeNoBaseFlag - without base transaction - "1", with base transaction - ""

13. GetMempoolList

GetMempoolList (net) get Mempool list on the specified network

net - name of the network
addr - datums in the mempool which are connected to specified wallet (optional)
chain - name of the chain - main\zerochain (optional)

14. GetMempoolTxHash

GetMempoolTxHash(net, hashTx get information about transaction presence in the mempool of the specified network

hashTx - hash of the transaction
net - name of the network

15. CondTxCreate

CondTxCreate(id,net, tokenName, walletName, certName, value, unit, srv_uid) create custom transaction for node services payment

net - name of the network 
tokenName - name of the token
walletName - name of the wallet which is used for payment
certName - name of the public certificate
value - quantity of coins for payment
unit - type of service unit - mb\kb\b\sec\day (mb is by default)
srv_uid - UID of the service (1 is for VPN service)

Request example:

http://127.0.0.1:8045/?method=CondTxCreate
&id=0x95480E0CDD1B6F64EEB858876E25352B10BE32258C38AC77BC8F06FBAA3E1EF1
&net=kelvpn-minkowski
&tokenName=tKEL
&walletName=mywallet
&certName=myCert_public
&value=1
&unit=day
&srv_uid=1

16. GetOrdersList

GetOrdersList(id, net, direction, srv_uid, unit, tokenName, price_min, price_max) get orders full list or using filtration by parameters

net - name of the network 
direction - type of exchange - sell\buy (optional)
price_min - minimum value of order in datoshi (optional)
price_max - maximum value of order in datoshi (optional)
tokenName - name of the token (optional)
 
unit - type of the service unit (optional):          
SERV_UNIT_UNDEFINED = 0 ,
SERV_UNIT_MB = 1, // megabytes
SERV_UNIT_SEC = 2, // seconds
SERV_UNIT_DAY = 3, // days
SERV_UNIT_KB = 10, // kilobytes
SERV_UNIT_B = 11, // bytes
SERV_UNIT_PCS = 22 // pieces
 
srv_uid - UID of the service (1 is for VPN service) (optional)

17. CreateOrder

CreateOrder(id, net, direction, srv_uid, value, unit, tokenName, certName, addr, hashTx, expires, ext, region, continent) create order for node services payment

net - name of the network
direction - type of exchange (sell \ buy)  
value - cost of order in datoshi
certName - name of the certificate
tokenName - name of the token
addr - address of the node (optional)
hashTx - hash of the conditional transaction applied to order (optional)
expires - Unix time which shows when order expires (in seconds) (optional)
ext - extended custom parameters (string) (optional)
 
region - region (country) (optional)
continent - name of the continent where node is located (None, Africa, Europe, North America, South America, Southeast Asia, Asia, Oceania, Antarctica) (optional)
 
unit - unit type ("MB", "SEC", "DAY", "KB", "B", "PCS", MB is by default) 
srv_uid - UID of the service (1 is for VPN service)

18. GetDexOrderList

GetDexOrderList(id) get list of DEX orders in all available networks

19. GetDexPairs

GetDexPairs(id) get list of DEX token pairs in all available networks

20. GetDexPairRate

GetDexPairRate(id, net, tokenFrom, tokenTo) get token rate (token buy/token sell)

net - name of the network
tokenFrom - token sell
tokenTo - token buy

21. DexOrderPurchase

DexOrderPurchase(id, hashTx, net, walletName, value) exchange token corresponding to specified order

hashTx - hash of the target order
net - name of the network
walletName - name of the wallet
value - amount of tokens are being exchanged

22. GetNodeStatus

GetNodeStatus(id) get actual node status using connection to notify socket

23. GetVersions

GetVersions(id) get version of wallet and node

24. NodeAdd

NodeAdd(id, net) add a node in the node list of the network

net - name of the network where node is registered

25. GetNodeIP

GetNodeIP(id, net, {addr | jsonArray}) get IP address of the node using its address in the network

net - name of the network where node is registered  
addr - address of the node in the network
jsonArray - addresses array represented as JsonArray structure

26. NodeDump

NodeDump(id, net) get node description

net - name of the network

27. GetNodeNetState

GetNodeNetState(id, net) get network information about node

net - name of the network

28. GetFee

GetFee(id, net) get information about fees in the network (network fee, validator’s fee, service fee)

net - name of the network

29. GetListKeys

GetListKeys(id, net) get list of delegated keys in the network

net - name of the network

30. GetNetId

GetNetId(id, net) get network ID

net - name of the network

31. VotingCreate

VotingCreate (net, walletName, question, voteOptions) create poll in the Cellframe network using voting transaction

net - name of the network
walletName - name of the wallet, from which fee will be paid
question - subject of voting (string in quotes)
voteOptions - answer options (strings in quotes, divided by commas)
expire - timestamp of poll expiration (optional, time format - RCF822)
maxVotesCount - maximum votes quantity counter (optional)
delegatedKeyRequired - allows to vote only users who have a delegated key (optional)
voteChangingAllowed - allows to change previously sent answer (optional)

Request example:

http://127.0.0.1:8045/method=VotingCreate
&id=0x15EDD69D7A11E1E265C72629947F5ED4CF24AC1E3A14BCC8DAF7F48E7C62B6A8
&net=riemann
&walletName=W1
&question="question?"
&voteOptions="answer1","answer2","answer3"

32. VotingVote

VotingVote(net, walletName, hashTx,optionIdx) vote for chosen answer

net - name of the network
walletName - name of the wallet, from which fee will be paid 
hashTx - hash of the voting transaction
optionIdx - index of answer option (counts from 0)
certName - name of the certificate for signing poll's result (optional)

Request example:

http://127.0.0.1:8045/method=VotingVote
&id=0xEDE916186BE739765402192B27E73159461AF33CC0788896D160CB9F349F1F77
&net=riemann
&walletName=W1
&hashTx=0x70920848EA94F08D60376775AEED233B64665B42DE1937FEA926513C1990E79D
&optionIdx=2

33. VotingList

VotingList (net) get list of actual polls in the network

net - name of the network

Request example:

http://127.0.0.1:8045/?method=VotingList
&id=0xEDE916186BE739765402192B27E73159461AF33CC0788896D160CB9F349F1F77
&net=riemann

34. VotingDump

VotingDump (net, hashTx) get dump about specified poll

net - name of the network
hashTx - hash of the voting transaction

Request example:

http://127.0.0.1:8045/?method=VotingDump
&id=0x31609198E0909B2F4E93AF48DACE87E8E088C905F92F20D204AFB92CEC1F2441
&net=riemann
&hashTx=0x70920848EA94F08D60376775AEED233B64665B42DE1937FEA926513C1990E79D

35. NodeList

NodeList(id, net) get node list of the network

net - name of the network

RemoveItemQueue(id, idQueue, net, walletName, addParam, type) - Удаляет одну или несколько транзакций из очереди.

36. RemoveItemQueue

RemoveItemQueue(id, net, idQueue, type, walletName, addParam) delete one or several transactions from the queue

net - name of the network
idQueue - ID of the transaction which is generated by queue for internal usage, this parameter is necessary for single transaction deletion, but it can not be deleted if it has null position in queue (for proper usage specify parameter type=single)
 
type - (=single/all) if "all" is chosen, then all transactions will be deleted except one which has null position in the queue
 
walletName - the name of the wallet
 
addParam - (=hard) this parameter allows to delete even null transaction (optional)

37. GetQueueHash

GetQueueHash(id, net, idQueue, walletName) get info about transaction in the queue

net - name of the network
idQueue - ID of the transaction which is generated by queue for internal usage
walletName - the name of the wallet

38. CreateOrderStaker

CreateOrderStaker(net, walletName, value, tax) create an order that allows the staker to transfer a certain amount of m-tokens to the owner of the master node. In return, the owner of the master node delegates his private key to the staker and must also send him a percentage of future profits

net - name of the network
walletName - the name of the wallet
value - amount of m-tokens
tax - percent of profite (for example, 20.0 is 20%)

39. CreateOrderValidator

CreateOrderValidator(net, valueMin, valueMax, tax, certName) create a validator order that allows a machine owner who does not have m-tokens to establish a master node

net - name of the network
valueMin - minimal stake value
valueMax - maximal stake value
tax - percent of profite (for example, 20.0 is 20%)
certName - the name of the private certificate which is used for sign blocks

JSON application

Description of a command which creates transaction using JSON-file.

Command syntax:

tx_create_json 
[-net <net name>] 
[-chain <chain name>] 
-json <json file path>

Options:

-net - name of the Cellframe Network. The list of networks can be found in the <Config_dir> \ etc \ network folder or received by The Cellframe-Node-CLI using command - net list
-chain - the name of Chain. The list of chains can be found in the directory <Config_dir> \ etc \ network \ <network_name> or by the Cellframe-Node-CLI using command - net list chains
-json - path to json file (file.json can be situated in any folder you want)

Note

If the network isn’t specified, it must be in a json file. If the chain isn’t specified, then the transaction will be created in the “main” chain by default.

JSON file contains all information about transactions being created.

Example:

Command:

cellframe-node-cli tx_create_json 
-net foobar 
-chain main 
-json /root/tx.json

Response:

Transaction 0x1CF55991C6B14B30484BCE6B2E0CBFBD4A22D6000AD725213F3E5135E1FDBB95 with 4 items created and added to mempool successfully

JSON file

Format example:

{
    "chain": "main",
    "items": [
        {
            "addr_from": "Rj7J7MiX2bWy8sNybTStGPaBEJLjxMnyXJinDezXE8D5LGUmkQZSPfXHATXePY9PXi5qWo4NLRUWu89AjQ5QmEWCH1C9H7zYqceKHrTF",
            "token": "CELL",
            "type": "in"
        },
        {
            "addr": "Rj7J7MiX2bWy8sNya4sPJaQsAqhULtVZi51JFSpXKKx7B5JDjbGtXPjN943iLFJuaHe3PukbBWzUM5VSo6HQZ6DkLUvnKUQVQVjLAnum",
            "type": "out",
            "value": "1000000000000000000"
        },
        {
            "type": "sign",
            "wallet": "testwallet"
        },
        {
            "subtype": "fee",
            "type": "out_cond",
            "value": "500000000000000000"
        }
    ],
    "net": "Backbone"
}

Description

Parameters net and chain define the network and the chain where transactions will be put (net and chain have priority in the command line).

Parameter items is an array and it contains a list of transaction’s items.

type [string] defines the type of the item 
values: in, out, out_ext, sign, in_cond, out_cond, receipt

There can be many items of one type. Every item has its own additional parameters.

TYPE IN:

INPUT
 
token[string] - name of the token
 
addr_from[string] - address of the sender (is not required if there prev_hash and out_prev_idx are specified) 
 
or
 
prev_hash [string] - hash of the previous transaction 
 
and
 
out_prev_idx [int] - sequence number of output in the previous transaction 
 
If an address was specified, then hash and number are found automatically, and output item with unspent sum is created

TYPE OUT:

OUTPUT

value[string] - number of datoshi for transfer

addr[string] - address of the receiver

TYPE OUT_EXT:

OUTPUT EXTENDED

value[string] - number of datoshi for transfer

addr[string] - address of the receiver

token[string] - name of the token

TYPE SIGN:

SIGNATURE

wallet - wallet for transaction signing

cert - certificate for transaction signing

Must be specified one of the parameters, if there both wallet and certificate names are specified, then the wallet will be used

TYPE RECEIPT:

RECEIPT

value[string] - value in datoshi

unit[int] - quantity of spent units

price_unit[string] - units type (mb or sec)

service_id[int] - ID of the service

service[string] - name of the service (fee, srv_vpn, srv_xchange, srv_stake)

params[string] - additional parameters (optional)

TYPE IN_COND:

CONDITIONAL INPUT
 
token[string] - name of the token
 
receipt_idx [int] - sequence number of receipt in the transaction (is not specified if there is only one receipt in the transaction)
 
addr_from[string] - sender address (is not required if there prev_hash, out_prev_idx and receipt_idx are specified)
 
subtype [string] - subtype of the conditional output (fee, srv_pay, srv_xchange, srv_vpn)
 
prev_hash [string] - hash of the previous transaction (is not required if there address and subtype are specified)
 
out_prev_idx [int] - sequence number of the output in the previous transaction (is not required if there address and subtype are specified)
 
If address and subtype were specified, then hash and number are found automatically, and output item with unspent sum is created

TYPE OUT_COND:

CONDITIONAL OUTPUT
 
subtype [string] - defines subtype of conditional out
values: fee, srv_pay, srv_xchange, srv_stake

SUBTYPE FEE:

FEE FOR TRANSACTION PROVIDING

value[string] - fee value in datoshi

SUBTYPE SRV_PAY:

PAY 
currently, is used only for VPN service payment 

value[string] - payment value in datoshi

value_max_per_unit[string] - maximum price per one unit in datoshi

price_unit[string] - type of the unit (mb or sec)

service_id[int] - ID of the service used (if not specified, then the name of the service is being found)

service[string] - name of the service used (srv_vpn, srv_xchange, srv_stake_pos, srv_take_lock)

If the service was not specified, then srv_vpn is used by default

params[string] - additional parameters (optional)

SUBTYPE SRV_XCHANGE:

XCHANGE
currently, is used in the DEX

value[string] - payment value in datoshi

token[string] - name of the token

net[string] - name of the network

service_id[int] - ID of the service used (if not specified, then the name of the service is being found)

service[string] - name of the service used (srv_vpn, srv_xchange, srv_stake_pos, srv_take_lock)

If the service was not specified, then srv_xchange is used by default

params[string] - additional parameters (optional)

SUBTYPE SRV_STAKE_POS_DELEGATE:

DELEGATED STAKE
currently is used in the staking service

value[string] - payment value in datoshi

fee[string] - staker's fee

fee_addr[string] - address of the fee receiver

hldr_addr[string] - address of the node holder

signing_addr[string] - address of the one, who signs transaction

service_id[int] - ID of the service used (if not specified, then the name of the service is being found)

service[string] - name of the service used (srv_vpn, srv_xchange, srv_stake_pos, srv_take_lock)

If the service was not specified, then srv_stake is used by default

params[string] - additional parameters (optional)

SUBTYPE SRV_STAKE_LOCK:

STAKING LOCK
currently is used in the staking service

value[string] - payment value in datoshi

time_unlock[int] - time for the tokens to be locked on the wallet

reinvest percent[int] - percent of reinvesting funds from the staking profit

service_id[int] - ID of the service used (if not specified, then the name of the service is being found)

service[string] - name of the service used (srv_vpn, srv_xchange, srv_stake_pos, srv_take_lock)

params[string] - additional parameters (optional)

JSON file example with several items

{
  "net" : "kelvin-testnet",
  "chain" : "zerochain",
  "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"
  } ]
}

Cellframe Wiki

Navigation

5. WEB3 API

API description

Request types

1. Connect

2. GetNetworks

3. GetWallets

4. GetDataWallet

5. SendTransaction

6. GetTransactions

7. TxCreateJson

8. GetLedgerTxHash

9. GetCertificates

10. CreateCertificate

11. StakeLockTake

12. StakeLockHold

13. GetMempoolList

14. GetMempoolTxHash

15. CondTxCreate

16. GetOrdersList

17. CreateOrder

18. GetDexOrderList

19. GetDexPairs

20. GetDexPairRate

21. DexOrderPurchase

22. GetNodeStatus

23. GetVersions

24. NodeAdd

25. GetNodeIP

26. NodeDump

27. GetNodeNetState

28. GetFee

29. GetListKeys

30. GetNetId

31. VotingCreate

32. VotingVote

33. VotingList

34. VotingDump

35. NodeList

36. RemoveItemQueue

37. GetQueueHash

38. CreateOrderStaker

39. CreateOrderValidator

JSON application

JSON file

Description

JSON file example with several items

Graph View

Table of Contents

Backlinks