647 lines
14 KiB
Markdown
647 lines
14 KiB
Markdown
# Wallet service API
|
|
|
|
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:
|
|
|
|
1. Set Enable to true in WalletConfig
|
|
|
|
```json
|
|
{
|
|
"WalletConfig": {
|
|
"Enabled": true,
|
|
}
|
|
}
|
|
```
|
|
|
|
2. And expose wallet API with APIModules
|
|
|
|
```
|
|
{
|
|
APIModules: "eth,net,web3,peer,wallet",
|
|
}
|
|
```
|
|
|
|
## API
|
|
|
|
### wallet_getTransfersByAddress
|
|
|
|
Returns avaiable transfers in a given range.
|
|
|
|
#### Parameters
|
|
|
|
- `address`: `HEX` - ethereum address encoded in hex
|
|
- `toBlock`: `BIGINT` - end of the range. if nil query will return last transfers.
|
|
- `limit`: `BIGINT` - limit of returned transfers.
|
|
- `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.
|
|
|
|
#### Examples
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":7,
|
|
"method":"wallet_getTransfersByAddress",
|
|
"params":[
|
|
"0xb81a6845649fa8c042dfaceb3f7a684873406993",
|
|
"0x0",
|
|
"0x5",
|
|
true
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Returns
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id":"0xb1a8adeaa0e6727bf01d6d8431b6238bdefa915e19ae7e8ceb16886c9f5e",
|
|
"type":"eth",
|
|
"address":"0xd65f3cb52605a54a833ae118fb13",
|
|
"blockNumber":"0xb7190",
|
|
"blockhash":"0x8d98aa2297fe322d0093b24372e2ead98414959093b479baf670",
|
|
"timestamp":"0x6048ec6",
|
|
"gasPrice":"0x346308a00",
|
|
"gasLimit":"0x508",
|
|
"gasUsed":"0x520",
|
|
"nonce":"0x13",
|
|
"txStatus":"0x1",
|
|
"input":"0x",
|
|
"txHash":"0x1adeaa0e672d7e67bf01d8431b6238bdef15e19ae7e8ceb16886c",
|
|
"value":"0x1",
|
|
"from":"0x2f865fb5dfdf0dfdf54a833ae118fb1363aaasd",
|
|
"to":"0xaaaaaaf3cb52605a54a833ae118fb1363a123123",
|
|
"contract":"0x0000000000000000000000000000000000000000",
|
|
"NetworkID":1
|
|
},...
|
|
]
|
|
```
|
|
|
|
### GetTransfersByAddressAndChainID
|
|
|
|
Returns avaiable transfers in a given range.
|
|
|
|
#### Parameters
|
|
|
|
- `chainID`: `INT` - ethereum chain ID
|
|
- `address`: `HEX` - ethereum address encoded in hex
|
|
- `toBlock`: `BIGINT` - end of the range. if nil query will return last transfers.
|
|
- `limit`: `BIGINT` - limit of returned transfers.
|
|
- `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.
|
|
|
|
#### Examples
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":7,
|
|
"method":"wallet_getTransfersByAddressAndChainID",
|
|
"params":[
|
|
1,
|
|
"0xb81a6845649fa8c042dfaceb3f7a684873406993",
|
|
"0x0",
|
|
"0x5",
|
|
true
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Returns
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id":"0xb1a8adeaa0e6727bf01d6d8431b6238bdefa915e19ae7e8ceb16886c9f5e",
|
|
"type":"eth",
|
|
"address":"0xd65f3cb52605a54a833ae118fb13",
|
|
"blockNumber":"0xb7190",
|
|
"blockhash":"0x8d98aa2297fe322d0093b24372e2ead98414959093b479baf670",
|
|
"timestamp":"0x6048ec6",
|
|
"gasPrice":"0x346308a00",
|
|
"gasLimit":"0x508",
|
|
"gasUsed":"0x520",
|
|
"nonce":"0x13",
|
|
"txStatus":"0x1",
|
|
"input":"0x",
|
|
"txHash":"0x1adeaa0e672d7e67bf01d8431b6238bdef15e19ae7e8ceb16886c",
|
|
"value":"0x1",
|
|
"from":"0x2f865fb5dfdf0dfdf54a833ae118fb1363aaasd",
|
|
"to":"0xaaaaaaf3cb52605a54a833ae118fb1363a123123",
|
|
"contract":"0x0000000000000000000000000000000000000000",
|
|
"NetworkID":1
|
|
},...
|
|
]
|
|
```
|
|
|
|
### wallet_setInitialBlocksRange
|
|
|
|
Sets `zero block - latest block` range as scanned for an account. It is used when a new multiaccount is generated to avoid scanning transfers history.
|
|
|
|
#### Example
|
|
|
|
```json
|
|
{"jsonrpc":"2.0","id":7,"method":"wallet_setInitialBlocksRange","params":[]}
|
|
```
|
|
|
|
### setInitialBlocksRangeForChainIDs
|
|
|
|
Sets `zero block - latest block` range as scanned for an account. It is used when a new multiaccount is generated to avoid scanning transfers history.
|
|
|
|
#### Parameters
|
|
|
|
- `chainIDs`: `[]INT` - array of ethereum chain ID to be initialized
|
|
|
|
#### Example
|
|
|
|
```json
|
|
{"jsonrpc":"2.0","id":7,"method":"wallet_setInitialBlocksRangeForChainIDs","params":[[1, 2]]}
|
|
```
|
|
|
|
### wallet_watchTransaction
|
|
|
|
Starts watching for transaction confirmation/rejection. If transaction was not confirmed/rejected in 10 minutes the call is timed out with error.
|
|
|
|
#### Parameters
|
|
|
|
- `tx-id`: `HEX` - transaction hash
|
|
|
|
#### Example
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":7,
|
|
"method":"wallet_watchTransaction",
|
|
"params":[
|
|
"0xaaaaaaaa11111112222233333333"
|
|
]
|
|
}
|
|
```
|
|
|
|
### wallet_watchTransactionByChainID
|
|
|
|
Starts watching for transaction confirmation/rejection. If transaction was not confirmed/rejected in 10 minutes the call is timed out with error.
|
|
|
|
#### Parameters
|
|
|
|
- `chainID`: `HEX` - ethereum chain id
|
|
- `tx-id`: `HEX` - transaction hash
|
|
|
|
#### Example
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":7,
|
|
"method":"wallet_watchTransactionByChainID",
|
|
"params":[
|
|
1,
|
|
"0xaaaaaaaa11111112222233333333"
|
|
]
|
|
}
|
|
```
|
|
|
|
### `wallet_checkRecentHistory`
|
|
|
|
#### Parameters
|
|
|
|
- `addresses`: `[]HEX` - array of addresses to be checked
|
|
|
|
#### Example
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":1,
|
|
"method":"wallet_checkRecentHistory",
|
|
"params":[
|
|
[
|
|
"0x23458d65f3cB52605a54AaA833ae118fb1111aaa",
|
|
"0x24568B4166D11aaa1194097C60Cdc714F7e11111"
|
|
]
|
|
]
|
|
}
|
|
```
|
|
|
|
### `wallet_checkRecentHistoryForChainIDs`
|
|
|
|
#### Parameters
|
|
|
|
- `chainIDs`: `[]INT` - array of ethereum chain ID to be checked
|
|
- `addresses`: `[]HEX` - array of addresses to be checked
|
|
|
|
#### Example
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":1,
|
|
"method":"wallet_checkRecentHistoryForChainIDs",
|
|
"params":[
|
|
[1, 2],
|
|
[
|
|
"0x23458d65f3cB52605a54AaA833ae118fb1111aaa",
|
|
"0x24568B4166D11aaa1194097C60Cdc714F7e11111"
|
|
]
|
|
]
|
|
}
|
|
```
|
|
|
|
### `wallet_getTokensBalancesForChainIDs`
|
|
|
|
Returns tokens balances mapping for every account. See section below for the response example.
|
|
|
|
#### Parameters
|
|
|
|
- `chainIDs`: `[]INT` - array of ethereum chain ID
|
|
- `accounts` `HEX` - list of ethereum addresses encoded in hex
|
|
- `tokens` `HEX` - list of ethereum addresses encoded in hex
|
|
|
|
#### Request
|
|
|
|
```json
|
|
{"jsonrpc":"2.0","id":11,"method":"wallet_getTokensBalancesForChainIDs","params":[
|
|
[1, 2]
|
|
["0x066ed5c2ed45d70ad72f40de0b4dd97bd67d84de", "0x0ed535be4c0aa276942a1a782669790547ad8768"],
|
|
["0x5e4bbdc178684478a615354d83c748a4393b20f0", "0x5e4bbdc178684478a615354d83c748a4393b20f0"]]
|
|
}
|
|
```
|
|
|
|
#### Returns
|
|
|
|
First level keys accounts, second level keys are tokens.
|
|
|
|
```json
|
|
{
|
|
"0x066ed5c2ed45d70ad72f40de0b4dd97bd67d84de": {
|
|
"0x1dfb2099f936b3e98bfc9b7059a8fb04edcce5b3": 12,
|
|
"0x5e4bbdc178684478a615354d83c748a4393b20f0": 12
|
|
},
|
|
"0x0ed535be4c0aa276942a1a782669790547ad8768": {
|
|
"0x1dfb2099f936b3e98bfc9b7059a8fb04edcce5b3": 14,
|
|
"0x5e4bbdc178684478a615354d83c748a4393b20f0": 14
|
|
}
|
|
}
|
|
```
|
|
|
|
### `wallet_getTokensBalances`
|
|
|
|
Returns tokens balances mapping for every account. See section below for the response example.
|
|
|
|
#### Parameters
|
|
|
|
- `accounts` `HEX` - list of ethereum addresses encoded in hex
|
|
- `tokens` `HEX` - list of ethereum addresses encoded in hex
|
|
|
|
#### Request
|
|
|
|
```json
|
|
{"jsonrpc":"2.0","id":11,"method":"wallet_getTokensBalances","params":[["0x066ed5c2ed45d70ad72f40de0b4dd97bd67d84de", "0x0ed535be4c0aa276942a1a782669790547ad8768"], ["0x5e4bbdc178684478a615354d83c748a4393b20f0", "0x5e4bbdc178684478a615354d83c748a4393b20f0"]]}
|
|
```
|
|
|
|
#### Returns
|
|
|
|
First level keys accounts, second level keys are tokens.
|
|
|
|
```json
|
|
{
|
|
"0x066ed5c2ed45d70ad72f40de0b4dd97bd67d84de": {
|
|
"0x1dfb2099f936b3e98bfc9b7059a8fb04edcce5b3": 12,
|
|
"0x5e4bbdc178684478a615354d83c748a4393b20f0": 12
|
|
},
|
|
"0x0ed535be4c0aa276942a1a782669790547ad8768": {
|
|
"0x1dfb2099f936b3e98bfc9b7059a8fb04edcce5b3": 14,
|
|
"0x5e4bbdc178684478a615354d83c748a4393b20f0": 14
|
|
}
|
|
}
|
|
```
|
|
|
|
### `wallet_storePendingTransaction`
|
|
|
|
Stores pending transation in the database.
|
|
|
|
#### Parameters
|
|
|
|
- `transaction` `OBJECT` - list of ethereum addresses encoded in hex
|
|
|
|
##### Transaction
|
|
|
|
- `hash` `HEX`
|
|
- `timestamp` ``INT`
|
|
- `from` `HEX`
|
|
- `to` `HEX`
|
|
- `symbol` `VARCHAR` - `"ETH"` for ethereum, otherwise ERC20 tokaen name, `null` for contract call
|
|
- `gasPrice` `BIGINT`
|
|
- `gasLimit` `BIGINT`
|
|
- `value` `BIGINT`
|
|
- `data` `TEXT` - transaction's `data` field
|
|
- `type` `VARCHAR`
|
|
- `additionalData` `TEXT` - arbitrary additional data
|
|
- `network_id` `INT` - an optional network id
|
|
|
|
#### Request example
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":1,
|
|
"method":"wallet_storePendingTransaction",
|
|
"params":[
|
|
{
|
|
"hash":"0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e",
|
|
"symbol":"ETH",
|
|
"gasPrice":"2000000000",
|
|
"value":"1000000000000000",
|
|
"from":"0xaaaad65f3cB52605433ae118fb1363aaaaad2",
|
|
"timestamp":1618584138787,
|
|
"gasLimit":"21000",
|
|
"to":"0x237f8B4166D64a2b94097C60Cdc714F7eC3aa079",
|
|
"data":null
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### `wallet_getPendingTransactions`
|
|
|
|
Returns all stored pending transactions.
|
|
|
|
#### Request
|
|
|
|
```json
|
|
{"jsonrpc":"2.0","id":1,"method":"wallet_getPendingTransactions","params":[]}
|
|
```
|
|
|
|
#### Returns
|
|
|
|
First level keys accounts, second level keys are tokens.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":1,
|
|
"result":[
|
|
{
|
|
"hash":"0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e",
|
|
"timestamp":1618584138787,
|
|
"value":"1000000000000000",
|
|
"from":"0xaaaaaaaa605a54a833ae118fb1aaaaaaaaaaa",
|
|
"to":"0x237f8b4166d64a2b94097c60cdc714f7ec3aa079",
|
|
"data":"",
|
|
"symbol":"ETH",
|
|
"gasPrice":"2000000000",
|
|
"gasLimit":"21000",
|
|
"type":"",
|
|
"additionalData":""
|
|
},
|
|
...
|
|
]
|
|
}
|
|
```
|
|
|
|
### `wallet_getPendingTransactionsByChainID`
|
|
|
|
Returns all stored pending transactions.
|
|
|
|
#### Parameters
|
|
|
|
- `chainID` `INT` - ethereum chain ID
|
|
|
|
#### Request
|
|
|
|
```json
|
|
{"jsonrpc":"2.0","id":1,"method":"wallet_getPendingTransactions","params":[1]}
|
|
```
|
|
|
|
#### Returns
|
|
|
|
First level keys accounts, second level keys are tokens.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":1,
|
|
"result":[
|
|
{
|
|
"hash":"0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e",
|
|
"timestamp":1618584138787,
|
|
"value":"1000000000000000",
|
|
"from":"0xaaaaaaaa605a54a833ae118fb1aaaaaaaaaaa",
|
|
"to":"0x237f8b4166d64a2b94097c60cdc714f7ec3aa079",
|
|
"data":"",
|
|
"symbol":"ETH",
|
|
"gasPrice":"2000000000",
|
|
"gasLimit":"21000",
|
|
"type":"",
|
|
"additionalData":"",
|
|
"network_id": 1
|
|
},
|
|
...
|
|
]
|
|
}
|
|
```
|
|
|
|
### `wallet_getPendingOutboundTransactionsByAddress`
|
|
|
|
Returns all stored pending transaction sent from `address`.
|
|
|
|
#### Parameters
|
|
|
|
- `address` `HEX`
|
|
|
|
#### Request
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":1,
|
|
"method":"wallet_getPendingOutboundTransactionsByAddress",
|
|
"params":[
|
|
"0xaaaaaaaa605a54a833ae118fb1aaaaaaaaaaa"
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Returns
|
|
|
|
First level keys accounts, second level keys are tokens.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":1,
|
|
"result":[
|
|
{
|
|
"hash":"0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e",
|
|
"timestamp":1618584138787,
|
|
"value":"1000000000000000",
|
|
"from":"0xaaaaaaaa605a54a833ae118fb1aaaaaaaaaaa",
|
|
"to":"0x237f8b4166d64a2b94097c60cdc714f7ec3aa079",
|
|
"data":"",
|
|
"symbol":"ETH",
|
|
"gasPrice":"2000000000",
|
|
"gasLimit":"21000",
|
|
"type":"",
|
|
"additionalData":""
|
|
},
|
|
...
|
|
]
|
|
}
|
|
```
|
|
|
|
### `wallet_getPendingOutboundTransactionsByAddressAndChainID`
|
|
|
|
Returns all stored pending transaction sent from `address`.
|
|
|
|
#### Parameters
|
|
|
|
- `chainID` `INT`
|
|
- `address` `HEX`
|
|
|
|
#### Request
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":1,
|
|
"method":"wallet_getPendingOutboundTransactionsByAddress",
|
|
"params":[
|
|
1,
|
|
"0xaaaaaaaa605a54a833ae118fb1aaaaaaaaaaa"
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Returns
|
|
|
|
First level keys accounts, second level keys are tokens.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":1,
|
|
"result":[
|
|
{
|
|
"hash":"0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e",
|
|
"timestamp":1618584138787,
|
|
"value":"1000000000000000",
|
|
"from":"0xaaaaaaaa605a54a833ae118fb1aaaaaaaaaaa",
|
|
"to":"0x237f8b4166d64a2b94097c60cdc714f7ec3aa079",
|
|
"data":"",
|
|
"symbol":"ETH",
|
|
"gasPrice":"2000000000",
|
|
"gasLimit":"21000",
|
|
"type":"",
|
|
"additionalData":"",
|
|
"network_id": 1
|
|
},
|
|
...
|
|
]
|
|
}
|
|
```
|
|
|
|
### `wallet_deletePendingTransaction`
|
|
|
|
Deletes pending transaction from the database by `hash`.
|
|
|
|
#### Parameters
|
|
|
|
- `hash` `HEX`
|
|
|
|
#### Request
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":1,
|
|
"method":"wallet_deletePendingTransaction",
|
|
"params":[
|
|
"0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e"
|
|
]
|
|
}
|
|
```
|
|
|
|
### `wallet_deletePendingTransactionByChainID`
|
|
|
|
Deletes pending transaction from the database by `hash`.
|
|
|
|
#### Parameters
|
|
|
|
- `chainID` `INT`
|
|
- `hash` `HEX`
|
|
|
|
#### Request
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"id":1,
|
|
"method":"wallet_deletePendingTransaction",
|
|
"params":[
|
|
1,
|
|
"0x3bce2c2d0fffbd2862ef3ec61a62872e54954551585fa0072d8e5c2f6be3523e"
|
|
]
|
|
}
|
|
```
|
|
|
|
## Signals
|
|
-------
|
|
|
|
All events are of the same format:
|
|
|
|
```json
|
|
{
|
|
"type": "wallet",
|
|
"event": {
|
|
"type": "event-type",
|
|
"blockNumber": 0,
|
|
"accounts": [
|
|
"0x42c8f505b4006d417dd4e0ba0e880692986adbd8",
|
|
"0x3129mdasmeo132128391fml1130410k312312mll"
|
|
],
|
|
"message": "something might be here"
|
|
}
|
|
}
|
|
```
|
|
|
|
1. `new-transfers`
|
|
|
|
Emitted when transfers are detected. In this case block number is a block number of the latest found transfer.
|
|
Client expected to request transfers starting from received block.
|
|
|
|
2. `recent-history-fetching`
|
|
|
|
Emitted when history scanning is started.
|
|
|
|
3. `recent-history-ready`
|
|
|
|
Emitted when history scanning is ended.
|
|
|
|
4. `fetching-history-error`
|
|
|
|
Emitted when when history can't be fetched because some error. Error's decritption can be found in `message` field.
|
|
|
|
5. `non-archival-node-detected`
|
|
|
|
Emitted when the application is connected to a non-archival node.
|
|
|
|
## Flows
|
|
|
|
### Account creation
|
|
|
|
When a new multiaccount is created corresponding address will not contain any transaction. Thus no point in checking history, it will be empty.
|
|
|
|
1. Call `wallet_setInitialRange`
|
|
2. Call `wallet_checkRecentHistory`
|
|
3. On `recent-history-ready` request transactions via `wallet_getTransfersByAddress`
|
|
4. 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)
|
|
|
|
### Logging into application
|
|
1. Call `wallet_checkRecentHistory`
|
|
2. On `recent-history-ready` request transactions via `wallet_getTransfersByAddress`
|
|
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)
|
|
|
|
### Watching transaction
|
|
1. Call `wallet_watchTransaction`
|
|
2. On success call `wallet_checkRecentHistory`
|
|
3. On `recent-history-ready` request transactions via `wallet_getTransfersByAddress`
|