github.com/status-im/status-go@v1.1.0/services/wallet/README.md (about)

     1  # Wallet service API
     2  
     3  Wallet service provides RPC API for checking transfers history and other methods related to wallet functionality. To enable service two values need to be changed in the config:
     4  
     5  1. Set Enable to true in WalletConfig
     6  
     7  ```json
     8  {
     9    "WalletConfig": {
    10      "Enabled": true,
    11    }
    12  }
    13  ```
    14  
    15  2. And expose wallet API with APIModules
    16  
    17  ```
    18  {
    19    APIModules: "eth,net,web3,peer,wallet",
    20  }
    21  ```
    22  
    23  ## API
    24  
    25  ### wallet_getTransfersByAddress
    26  
    27  Returns avaiable transfers in a given range.
    28  
    29  #### Parameters
    30  
    31  - `address`: `HEX` - ethereum address encoded in hex
    32  - `toBlock`: `BIGINT` - end of the range. if nil query will return last transfers.
    33  - `limit`: `BIGINT` - limit of returned transfers.
    34  - `fetchMore`: `BOOLEAN` - if `true`, there are less than `limit` fetched transfers in the database, and zero block is not reached yet, history will be scanned for more transfers. If `false` only transfers which are already fetched to the app's database will be returned.
    35  
    36  #### Examples
    37  
    38  ```json
    39  {
    40    "jsonrpc":"2.0",
    41    "id":7,
    42    "method":"wallet_getTransfersByAddress",
    43    "params":[
    44      "0xb81a6845649fa8c042dfaceb3f7a684873406993",
    45      "0x0",
    46      "0x5",
    47      true
    48    ]
    49  }
    50  ```
    51  
    52  #### Returns
    53  
    54  ```json
    55  [
    56    {
    57      "id":"0xb1a8adeaa0e6727bf01d6d8431b6238bdefa915e19ae7e8ceb16886c9f5e",
    58      "type":"eth",
    59      "address":"0xd65f3cb52605a54a833ae118fb13",
    60      "blockNumber":"0xb7190",
    61      "blockhash":"0x8d98aa2297fe322d0093b24372e2ead98414959093b479baf670",
    62      "timestamp":"0x6048ec6",
    63      "gasPrice":"0x346308a00",
    64      "gasLimit":"0x508",
    65      "gasUsed":"0x520",
    66      "nonce":"0x13",
    67      "txStatus":"0x1",
    68      "input":"0x",
    69      "txHash":"0x1adeaa0e672d7e67bf01d8431b6238bdef15e19ae7e8ceb16886c",
    70      "value":"0x1",
    71      "from":"0x2f865fb5dfdf0dfdf54a833ae118fb1363aaasd",
    72      "to":"0xaaaaaaf3cb52605a54a833ae118fb1363a123123",
    73      "contract":"0x0000000000000000000000000000000000000000",
    74      "NetworkID":1
    75    },...
    76  ]
    77  ```
    78  
    79  ### GetTransfersByAddressAndChainID
    80  
    81  Returns avaiable transfers in a given range.
    82  
    83  #### Parameters
    84  
    85  - `chainID`: `INT` - ethereum chain ID
    86  - `address`: `HEX` - ethereum address encoded in hex
    87  - `toBlock`: `BIGINT` - end of the range. if nil query will return last transfers.
    88  - `limit`: `BIGINT` - limit of returned transfers.
    89  - `fetchMore`: `BOOLEAN` - if `true`, there are less than `limit` fetched transfers in the database, and zero block is not reached yet, history will be scanned for more transfers. If `false` only transfers which are already fetched to the app's database will be returned.
    90  
    91  #### Examples
    92  
    93  ```json
    94  {
    95    "jsonrpc":"2.0",
    96    "id":7,
    97    "method":"wallet_getTransfersByAddressAndChainID",
    98    "params":[
    99      1,
   100      "0xb81a6845649fa8c042dfaceb3f7a684873406993",
   101      "0x0",
   102      "0x5",
   103      true
   104    ]
   105  }
   106  ```
   107  
   108  #### Returns
   109  
   110  ```json
   111  [
   112    {
   113      "id":"0xb1a8adeaa0e6727bf01d6d8431b6238bdefa915e19ae7e8ceb16886c9f5e",
   114      "type":"eth",
   115      "address":"0xd65f3cb52605a54a833ae118fb13",
   116      "blockNumber":"0xb7190",
   117      "blockhash":"0x8d98aa2297fe322d0093b24372e2ead98414959093b479baf670",
   118      "timestamp":"0x6048ec6",
   119      "gasPrice":"0x346308a00",
   120      "gasLimit":"0x508",
   121      "gasUsed":"0x520",
   122      "nonce":"0x13",
   123      "txStatus":"0x1",
   124      "input":"0x",
   125      "txHash":"0x1adeaa0e672d7e67bf01d8431b6238bdef15e19ae7e8ceb16886c",
   126      "value":"0x1",
   127      "from":"0x2f865fb5dfdf0dfdf54a833ae118fb1363aaasd",
   128      "to":"0xaaaaaaf3cb52605a54a833ae118fb1363a123123",
   129      "contract":"0x0000000000000000000000000000000000000000",
   130      "NetworkID":1
   131    },...
   132  ]
   133  ```
   134  
   135  ### wallet_watchTransaction
   136  
   137  Starts watching for transaction confirmation/rejection. If transaction was not confirmed/rejected in 10 minutes the call is timed out with error.
   138  
   139  #### Parameters
   140  
   141  - `tx-id`: `HEX` - transaction hash
   142  
   143  #### Example
   144  
   145  ```json
   146  {
   147    "jsonrpc":"2.0",
   148    "id":7,
   149    "method":"wallet_watchTransaction",
   150    "params":[
   151      "0xaaaaaaaa11111112222233333333"
   152    ]
   153  }
   154  ```
   155  
   156  ### wallet_watchTransactionByChainID
   157  
   158  Starts watching for transaction confirmation/rejection. If transaction was not confirmed/rejected in 10 minutes the call is timed out with error.
   159  
   160  #### Parameters
   161  
   162  - `chainID`: `HEX` - ethereum chain id
   163  - `tx-id`: `HEX` - transaction hash
   164  
   165  #### Example
   166  
   167  ```json
   168  {
   169    "jsonrpc":"2.0",
   170    "id":7,
   171    "method":"wallet_watchTransactionByChainID",
   172    "params":[
   173      1,
   174      "0xaaaaaaaa11111112222233333333"
   175    ]
   176  }
   177  ```
   178  
   179  ### `wallet_checkRecentHistory`
   180  
   181  #### Parameters
   182  
   183  - `addresses`: `[]HEX` - array of addresses to be checked
   184  
   185  #### Example
   186  
   187  ```json
   188  {
   189    "jsonrpc":"2.0",
   190    "id":1,
   191    "method":"wallet_checkRecentHistory",
   192    "params":[
   193      [
   194        "0x23458d65f3cB52605a54AaA833ae118fb1111aaa",
   195        "0x24568B4166D11aaa1194097C60Cdc714F7e11111"
   196      ]
   197    ]
   198  }
   199  ```
   200  
   201  ### `wallet_checkRecentHistoryForChainIDs`
   202  
   203  #### Parameters
   204  
   205  - `chainIDs`: `[]INT` - array of ethereum chain ID to be checked
   206  - `addresses`: `[]HEX` - array of addresses to be checked
   207  
   208  #### Example
   209  
   210  ```json
   211  {
   212    "jsonrpc":"2.0",
   213    "id":1,
   214    "method":"wallet_checkRecentHistoryForChainIDs",
   215    "params":[
   216      [1, 2],
   217      [
   218        "0x23458d65f3cB52605a54AaA833ae118fb1111aaa",
   219        "0x24568B4166D11aaa1194097C60Cdc714F7e11111"
   220      ]
   221    ]
   222  }
   223  ```
   224  
   225  ### `wallet_getTokensBalancesForChainIDs`
   226  
   227  Returns tokens balances mapping for every account. See section below for the response example.
   228  
   229  #### Parameters
   230  
   231  - `chainIDs`: `[]INT` - array of ethereum chain ID
   232  - `accounts` `HEX` - list of ethereum addresses encoded in hex
   233  - `tokens` `HEX` - list of ethereum addresses encoded in hex
   234  
   235  #### Request
   236  
   237  ```json
   238  {"jsonrpc":"2.0","id":11,"method":"wallet_getTokensBalancesForChainIDs","params":[
   239    [1, 2]
   240    ["0x066ed5c2ed45d70ad72f40de0b4dd97bd67d84de", "0x0ed535be4c0aa276942a1a782669790547ad8768"], 
   241    ["0x5e4bbdc178684478a615354d83c748a4393b20f0", "0x5e4bbdc178684478a615354d83c748a4393b20f0"]]
   242  }
   243  ```
   244  
   245  #### Returns
   246  
   247  First level keys accounts, second level keys are tokens.
   248  
   249  ```json
   250  {
   251    "0x066ed5c2ed45d70ad72f40de0b4dd97bd67d84de": {
   252      "0x1dfb2099f936b3e98bfc9b7059a8fb04edcce5b3": 12,
   253      "0x5e4bbdc178684478a615354d83c748a4393b20f0": 12
   254    },
   255    "0x0ed535be4c0aa276942a1a782669790547ad8768": {
   256      "0x1dfb2099f936b3e98bfc9b7059a8fb04edcce5b3": 14,
   257      "0x5e4bbdc178684478a615354d83c748a4393b20f0": 14
   258    }
   259  }
   260  ```
   261  
   262  ### `wallet_getTokensBalances`
   263  
   264  Returns tokens balances mapping for every account. See section below for the response example.
   265  
   266  #### Parameters
   267  
   268  - `accounts` `HEX` - list of ethereum addresses encoded in hex
   269  - `tokens` `HEX` - list of ethereum addresses encoded in hex
   270  
   271  #### Request
   272  
   273  ```json
   274  {"jsonrpc":"2.0","id":11,"method":"wallet_getTokensBalances","params":[["0x066ed5c2ed45d70ad72f40de0b4dd97bd67d84de", "0x0ed535be4c0aa276942a1a782669790547ad8768"], ["0x5e4bbdc178684478a615354d83c748a4393b20f0", "0x5e4bbdc178684478a615354d83c748a4393b20f0"]]}
   275  ```
   276  
   277  #### Returns
   278  
   279  First level keys accounts, second level keys are tokens.
   280  
   281  ```json
   282  {
   283    "0x066ed5c2ed45d70ad72f40de0b4dd97bd67d84de": {
   284      "0x1dfb2099f936b3e98bfc9b7059a8fb04edcce5b3": 12,
   285      "0x5e4bbdc178684478a615354d83c748a4393b20f0": 12
   286    },
   287    "0x0ed535be4c0aa276942a1a782669790547ad8768": {
   288      "0x1dfb2099f936b3e98bfc9b7059a8fb04edcce5b3": 14,
   289      "0x5e4bbdc178684478a615354d83c748a4393b20f0": 14
   290    }
   291  }
   292  ```
   293  
   294  ### `wallet_storePendingTransaction`
   295  
   296  Stores pending transation in the database.
   297  
   298  #### Parameters
   299  
   300  - `transaction` `OBJECT` - list of ethereum addresses encoded in hex
   301  
   302  ##### Transaction
   303  
   304  - `hash` `HEX`
   305  - `timestamp` ``INT`
   306  - `from` `HEX`
   307  - `to` `HEX`
   308  - `symbol` `VARCHAR` - `"ETH"` for ethereum, otherwise ERC20 tokaen name, `null` for contract call 
   309  - `gasPrice` `BIGINT`
   310  - `gasLimit` `BIGINT`
   311  - `value` `BIGINT`
   312  - `data` `TEXT` - transaction's `data` field
   313  - `type` `VARCHAR`
   314  - `additionalData` `TEXT` - arbitrary additional data
   315  - `network_id` `INT` - an optional network id
   316  
   317  #### Request example
   318  
   319  ```json
   320  {
   321    "jsonrpc":"2.0",
   322    "id":1,
   323    "method":"wallet_storePendingTransaction",
   324    "params":[
   325      {
   326        "hash":"0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e",
   327        "symbol":"ETH",
   328        "gasPrice":"2000000000",
   329        "value":"1000000000000000",
   330        "from":"0xaaaad65f3cB52605433ae118fb1363aaaaad2",
   331        "timestamp":1618584138787,
   332        "gasLimit":"21000",
   333        "to":"0x237f8B4166D64a2b94097C60Cdc714F7eC3aa079",
   334        "data":null
   335      }
   336    ]
   337  }
   338  ```
   339  
   340  ### `wallet_getPendingTransactions`
   341  
   342  Returns all stored pending transactions.
   343  
   344  #### Request
   345  
   346  ```json
   347  {"jsonrpc":"2.0","id":1,"method":"wallet_getPendingTransactions","params":[]}
   348  ```
   349  
   350  #### Returns
   351  
   352  First level keys accounts, second level keys are tokens.
   353  
   354  ```json
   355  {
   356    "jsonrpc":"2.0",
   357    "id":1,
   358    "result":[
   359      {
   360        "hash":"0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e",
   361        "timestamp":1618584138787,
   362        "value":"1000000000000000",
   363        "from":"0xaaaaaaaa605a54a833ae118fb1aaaaaaaaaaa",
   364        "to":"0x237f8b4166d64a2b94097c60cdc714f7ec3aa079",
   365        "data":"",
   366        "symbol":"ETH",
   367        "gasPrice":"2000000000",
   368        "gasLimit":"21000",
   369        "type":"",
   370        "additionalData":""
   371      },
   372      ...
   373    ]
   374  }
   375  ```
   376  
   377  ### `wallet_getPendingTransactionsByChainID`
   378  
   379  Returns all stored pending transactions.
   380  
   381  #### Parameters
   382  
   383  - `chainID` `INT` - ethereum chain ID
   384  
   385  #### Request
   386  
   387  ```json
   388  {"jsonrpc":"2.0","id":1,"method":"wallet_getPendingTransactions","params":[1]}
   389  ```
   390  
   391  #### Returns
   392  
   393  First level keys accounts, second level keys are tokens.
   394  
   395  ```json
   396  {
   397    "jsonrpc":"2.0",
   398    "id":1,
   399    "result":[
   400      {
   401        "hash":"0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e",
   402        "timestamp":1618584138787,
   403        "value":"1000000000000000",
   404        "from":"0xaaaaaaaa605a54a833ae118fb1aaaaaaaaaaa",
   405        "to":"0x237f8b4166d64a2b94097c60cdc714f7ec3aa079",
   406        "data":"",
   407        "symbol":"ETH",
   408        "gasPrice":"2000000000",
   409        "gasLimit":"21000",
   410        "type":"",
   411        "additionalData":"",
   412        "network_id": 1
   413      },
   414      ...
   415    ]
   416  }
   417  ```
   418  
   419  ### `wallet_getPendingOutboundTransactionsByAddress`
   420  
   421  Returns all stored pending transaction sent from `address`.
   422  
   423  #### Parameters
   424  
   425  - `address` `HEX` 
   426  
   427  #### Request
   428  
   429  ```json
   430  {
   431    "jsonrpc":"2.0",
   432    "id":1,
   433    "method":"wallet_getPendingOutboundTransactionsByAddress",
   434    "params":[
   435      "0xaaaaaaaa605a54a833ae118fb1aaaaaaaaaaa"
   436    ]
   437  }
   438  ```
   439  
   440  #### Returns
   441  
   442  First level keys accounts, second level keys are tokens.
   443  
   444  ```json
   445  {
   446    "jsonrpc":"2.0",
   447    "id":1,
   448    "result":[
   449      {
   450        "hash":"0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e",
   451        "timestamp":1618584138787,
   452        "value":"1000000000000000",
   453        "from":"0xaaaaaaaa605a54a833ae118fb1aaaaaaaaaaa",
   454        "to":"0x237f8b4166d64a2b94097c60cdc714f7ec3aa079",
   455        "data":"",
   456        "symbol":"ETH",
   457        "gasPrice":"2000000000",
   458        "gasLimit":"21000",
   459        "type":"",
   460        "additionalData":""
   461      },
   462      ...
   463    ]
   464  }
   465  ```
   466  
   467  ### `wallet_getPendingOutboundTransactionsByAddressAndChainID`
   468  
   469  Returns all stored pending transaction sent from `address`.
   470  
   471  #### Parameters
   472  
   473  - `chainID` `INT` 
   474  - `address` `HEX` 
   475  
   476  #### Request
   477  
   478  ```json
   479  {
   480    "jsonrpc":"2.0",
   481    "id":1,
   482    "method":"wallet_getPendingOutboundTransactionsByAddress",
   483    "params":[
   484      1,
   485      "0xaaaaaaaa605a54a833ae118fb1aaaaaaaaaaa"
   486    ]
   487  }
   488  ```
   489  
   490  #### Returns
   491  
   492  First level keys accounts, second level keys are tokens.
   493  
   494  ```json
   495  {
   496    "jsonrpc":"2.0",
   497    "id":1,
   498    "result":[
   499      {
   500        "hash":"0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e",
   501        "timestamp":1618584138787,
   502        "value":"1000000000000000",
   503        "from":"0xaaaaaaaa605a54a833ae118fb1aaaaaaaaaaa",
   504        "to":"0x237f8b4166d64a2b94097c60cdc714f7ec3aa079",
   505        "data":"",
   506        "symbol":"ETH",
   507        "gasPrice":"2000000000",
   508        "gasLimit":"21000",
   509        "type":"",
   510        "additionalData":"",
   511        "network_id": 1
   512      },
   513      ...
   514    ]
   515  }
   516  ```
   517  
   518  ### `wallet_deletePendingTransaction`
   519  
   520  Deletes pending transaction from the database by `hash`.
   521  
   522  #### Parameters
   523  
   524  - `hash` `HEX` 
   525  
   526  #### Request
   527  
   528  ```json
   529  {
   530    "jsonrpc":"2.0",
   531    "id":1,
   532    "method":"wallet_deletePendingTransaction",
   533    "params":[
   534      "0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e"
   535    ]
   536  }
   537  ```
   538  
   539  ### `wallet_deletePendingTransactionByChainID`
   540  
   541  Deletes pending transaction from the database by `hash`.
   542  
   543  #### Parameters
   544  
   545  - `chainID` `INT` 
   546  - `hash` `HEX` 
   547  
   548  #### Request
   549  
   550  ```json
   551  {
   552    "jsonrpc":"2.0",
   553    "id":1,
   554    "method":"wallet_deletePendingTransaction",
   555    "params":[
   556      1,
   557      "0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e"
   558    ]
   559  }
   560  ```
   561  
   562  ## Signals
   563  -------
   564  
   565  All events are of the same format:
   566  
   567  ```json
   568  {
   569    "type": "wallet",
   570    "event": {
   571      "type": "event-type",
   572      "blockNumber": 0,
   573      "accounts": [
   574        "0x42c8f505b4006d417dd4e0ba0e880692986adbd8",
   575        "0x3129mdasmeo132128391fml1130410k312312mll"
   576      ],
   577      "message": "something might be here"
   578    }
   579  }
   580  ```
   581  
   582  1. `new-transfers`
   583  
   584  Emitted when transfers are detected. In this case block number is a block number of the latest found transfer.
   585  Client expected to request transfers starting from received block.
   586  
   587  2. `recent-history-fetching`
   588  
   589  Emitted when history scanning is started.
   590  
   591  3. `recent-history-ready`
   592  
   593  Emitted when history scanning is ended.
   594  
   595  4. `fetching-history-error`
   596  
   597  Emitted when when history can't be fetched because some error. Error's decritption can be found in `message` field.
   598  
   599  5. `non-archival-node-detected`
   600  
   601  Emitted when the application is connected to a non-archival node.
   602  
   603  ## Flows
   604  
   605  ### Account creation
   606  
   607  When a new multiaccount is created corresponding address will not contain any transaction. Thus no point in checking history, it will be empty.
   608  
   609  1. Call `wallet_checkRecentHistory`
   610  2. On `recent-history-ready` request transactions via `wallet_getTransfersByAddress`
   611  3. Repeat `wallet_checkRecentHistory` in N minutes (currently 20 minutes in `status-mobile` for upstream RPC node. If a custom node is used interval can be arbitrary)
   612  
   613  ### Logging into application
   614  1. Call `wallet_checkRecentHistory`
   615  2. On `recent-history-ready` request transactions via `wallet_getTransfersByAddress`
   616  3. Repeat `wallet_checkRecentHistory` in N minutes (currently 20 minutes in `status-mobile` for upstream RPC node. If a custom node is used interval can be arbitrary)
   617  
   618  ### Watching transaction
   619  1. Call `wallet_watchTransaction`
   620  2. On success call `wallet_checkRecentHistory`
   621  3. On `recent-history-ready` request transactions via `wallet_getTransfersByAddress`