GRIN/grin-node
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d3dbafa80bd34e6b8564c27ffd18dfd2bac9e0de
grin-node/doc/api/wallet_owner_api.md
T

734 lines
31 KiB
Markdown
Raw Blame History

# Wallet Owner API Documentation
## Table of Contents
1. [Wallet Owner Endpoint](#wallet-owner-endpoint)
1. [GET Retrieve Outputs](#get-retrieve-outputs)
1. [GET Retrieve Summary Info](#get-retrieve-summary-info)
1. [GET Node Height](#get-node-height)
1. [GET Retrieve Txs](#get-retrieve-txs)
1. [GET Retrieve Stored Tx](#get-retrieve-stored-tx)
1. [POST Issue Send Tx](#post-issue-send-tx)
1. [POST Finalize Tx](#post-finalize-tx)
1. [POST Cancel Tx](#post-cancel-tx)
1. [POST Post Tx](#post-post-tx)
1. [POST Repost Tx](#post-repost-tx)
1. [POST Issue Burn Tx](#post-issue-burn-tx)
1. [Adding Foreign API Endpoints](#add-foreign-api-endpoints)
## Wallet Owner Endpoint
### GET Retrieve Outputs
Attempt to update and retrieve outputs.
* **URL**
* /v1/wallet/owner/retrieve_outputs
* /v1/wallet/owner/retrieve_outputs?refresh&show_spent&tx_id=x&tx_id=y
* **Method:**
`GET`
* **URL Params**
**Optional:**
`refresh` to refresh from node
`show_spent` to show spent outputs
`tx_id=[number]` to retrieve only the specified output
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Content:** Array of
| Field | Type | Description |
|:---------------------|:---------|:---------------------------------------------------------------|
| | bool | Whether it was refreshed from node |
| - | []object | Array |
| - - | []object | Array of Output Data |
| - - - | object | Output Data |
| - - - - root_key_id | string | Root key_id that the key for this output is derived from |
| - - - - key_id | string | Derived key for this output |
| - - - - n_child | number | How many derivations down from the root key |
| - - - - value | number | Value of the output, necessary to rebuild the commitment |
| - - - - status | string | Current status of the output |
| - - - - height | number | Height of the output |
| - - - - lock_height | number | Height we are locked until |
| - - - - is_coinbase | bool | Is this a coinbase output? Is it subject to coinbase locktime? |
| - - - - tx_log_entry | number | Optional corresponding internal entry in tx entry log |
| - - - | []number | Pedersen Commitment |
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/retrieve_outputs?refresh&id=3",
dataType: "json",
type : "GET",
success : function(r) {
console.log(r);
}
});
```
### GET Retrieve Summary Info
Retrieve summary info for wallet.
* **URL**
* /v1/wallet/owner/retrieve_summary_info
* /v1/wallet/owner/retrieve_summary_info?refresh
* **Method:**
`GET`
* **URL Params**
**Optional:**
`refresh` to refresh from node
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Content:** All listed amounts in nanogrin. Array of
| Field | Type | Description |
|:----------------------------------|:---------|:----------------------------------------|
| | bool | Whether it was refreshed from node |
| - | object | Wallet information |
| - - last_confirmed_height | number | Height from which info was taken |
| - - total | number | Total amount in the wallet |
| - - amount_awaiting_confirmation | number | Amount awaiting confirmation |
| - - amount_immature | number | Coinbases waiting for lock height |
| - - amount_currently_spendable | number | Amount currently spendable |
| - - amount_locked | number | Amount locked via previous transactions |
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/retrieve_summary_info",
dataType: "json",
type : "GET",
success : function(r) {
console.log(r);
}
});
```
### GET Node Height
Retrieve current height from node.
* **URL**
/v1/wallet/owner/node_height
* **Method:**
`GET`
* **URL Params**
None
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Content:** Array of
| Field | Type | Description |
|:-------|:---------|:-------------------------------------------|
| | number | Node height |
| | bool | Wether the update from node was successful |
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/node_height",
dataType: "json",
type : "GET",
success : function(r) {
console.log(r);
}
});
```
### GET Retrieve Txs
Attempt to update outputs and retrieve transactions.
Return whether the outputs were validated against a node and an array of TxLogEntry.
* **URL**
* /v1/wallet/owner/retrieve_txs
* /v1/wallet/owner/retrieve_txs?refresh&id=x
* /v1/wallet/owner/retrieve_txs?tx_id=x
* **Method:**
`GET`
* **URL Params**
**Optional:**
* `refresh` to refresh from node
* `id=[number]` to retrieve only the specified output by id
* `tx_id=[string]` to retrieve only the specified output by tx id
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Content:** Array of
| Field | Type | Description |
|:----------------------|:---------|:----------------------------------------------------------------------------|
| | bool | Whether it was refreshed from node |
| - | []object | Array of transactions |
| - - | object | TxLogEntry |
| - - - id | number | Local id for this transaction (distinct from a slate transaction id) |
| - - - tx_slate_id | string | Slate transaction this entry is associated with, if any |
| - - - tx_type | string | Transaction type |
| - - - creation_ts | string | Time this tx entry was created |
| - - - confirmation_ts | string | Time this tx was confirmed (by this wallet) |
| - - - confirmed | bool | Whether the inputs+outputs involved in this transaction have been confirmed |
| - - - num_inputs | number | number of inputs involved in TX |
| - - - num_outputs | number | number of outputs involved in TX |
| - - - amount_credited | number | Amount credited via this transaction |
| - - - amount_debited | number | Amount debited via this transaction |
| - - - fee | number | Fee |
| - - - tx_hex | string | The transaction json itself, stored for reference or resending |
*Note on transaction type*: transaction type can be either `ConfirmedCoinbase`, `TxReceived`, `TxSent`, `TxReceivedCancelled` and `TxSentCancelled`.
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/foreign/retrieve_txs",
dataType: "json",
type : "GET",
success : function(r) {
console.log(r);
}
});
```
### GET Retrieve Stored Tx
Retrieves a given transaction.
* **URL**
/v1/wallet/owner/retrieve_stored_tx?id=x
* **Method:**
`GET`
* **URL Params**
**Required:**
`id=[number]`
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Content:** A deserialized transaction.
| Field | Type | Description |
|:----------------------|:---------|:--------------------------------------------------------------------------|
| | object | The core transaction data (inputs, outputs, kernels and kernel offset) |
| - offset | []number | The kernel "offset" k2, excess is k1G after splitting the key k = k1 + k2 |
| - body | object | The transaction body - inputs/outputs/kernels |
| - - inputs | []object | List of inputs spent by the transaction |
| - - - features | object | The features of the output being spent |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The commit referencing the output being spent |
| - - outputs | []object | List of outputs the transaction produces |
| - - - features | object | Options for an output's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The homomorphic commitment representing the output amount |
| - - - proof | []number | A proof that the commitment is in the right range |
| - - kernels | []object | List of kernels that make up this transaction (usually a single kernel) |
| - - - features | object | Options for a kernel's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - fee | number | Fee originally included in the transaction this proof is for |
| - - - lock_height | number | The max lock_height of all inputs to this transaction |
| - - - excess | []number | Remainder of the sum of all transaction commitments |
| - - - excess_sig | []number | The signature proving the excess is a valid public key (signs the tx fee) |
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/retrieve_stored_tx?id=13",
dataType: "json",
type : "GET",
success : function(r) {
console.log(r);
}
});
```
### POST Issue Send Tx
Send a transaction either directly by http or file (then display the slate)
* **URL**
/v1/wallet/owner/issue_send_tx
* **Method:**
`POST`
* **URL Params**
None
* **Data Params**
**Required:**
| Field | Type | Description |
|:------------------------------|:---------|:-------------------------------------|
| amount | number | Amount to send (in nanogrin) |
| minimum_confirmations | number | Minimum confirmations |
| method | string | Payment method |
| dest | string | Destination url |
| max_outputs | number | Max number of outputs |
| num_change_outputs | number | Number of change outputs to generate |
| selection_strategy_is_use_all | bool | Whether to use all outputs (combine) |
* **Success Response:**
* **Code:** 200
* **Content:** A new transaction slate in JSON.
| Field | Type | Description |
|:----------------------|:---------|:--------------------------------------------------------------------------|
| num_participants | number | The number of participants intended to take part in this transaction |
| id | number | Unique transaction ID, selected by sender |
| tx | object | The core transaction data (inputs, outputs, kernels and kernel offset) |
| - offset | []number | The kernel "offset" k2, excess is k1G after splitting the key k = k1 + k2 |
| - body | object | The transaction body - inputs/outputs/kernels |
| - - inputs | []object | List of inputs spent by the transaction |
| - - - features | object | The features of the output being spent |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The commit referencing the output being spent |
| - - outputs | []object | List of outputs the transaction produces |
| - - - features | object | Options for an output's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The homomorphic commitment representing the output amount |
| - - - proof | []number | A proof that the commitment is in the right range |
| - - kernels | []object | List of kernels that make up this transaction (usually a single kernel) |
| - - - features | object | Options for a kernel's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - fee | number | Fee originally included in the transaction this proof is for |
| - - - lock_height | number | The max lock_height of all inputs to this transaction |
| - - - excess | []number | Remainder of the sum of all transaction commitments |
| - - - excess_sig | []number | The signature proving the excess is a valid public key (signs the tx fee) |
| amount | number | Base amount (excluding fee) |
| fee | number | Fee amount |
| height | number | Block height for the transaction |
| lock_height | number | Lock height |
| participant_data | object | Participant data |
| - id | number | Id of participant in the transaction. (For now, 0=sender, 1=rec) |
| - public_blind_excess | []number | Public key corresponding to private blinding factor |
| - public_nonce | []number | Public key corresponding to private nonce |
| - part_sig | []number | Public partial signature |
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/issue_send_tx",
dataType: "json",
type : "POST",
success : function(r) {
console.log(r);
},
data: {
file: tx_args.json
},
});
```
### POST Finalize Tx
Sender finalization of the transaction. Takes the slate returned by the sender as well as the private file generate on the first send step.
Builds the complete transaction but will **not** sends it to a grin node for propagation. Use [POST Post Tx](#post-post-tx) for that.
* **URL**
/v1/wallet/owner/finalize_tx
* **Method:**
`POST`
* **URL Params**
None
* **Data Params**
**Required:** A transaction slate in JSON.
| Field | Type | Description |
|:----------------------|:---------|:--------------------------------------------------------------------------|
| num_participants | number | The number of participants intended to take part in this transaction |
| id | number | Unique transaction ID, selected by sender |
| tx | object | The core transaction data (inputs, outputs, kernels and kernel offset) |
| - offset | []number | The kernel "offset" k2, excess is k1G after splitting the key k = k1 + k2 |
| - body | object | The transaction body - inputs/outputs/kernels |
| - - inputs | []object | List of inputs spent by the transaction |
| - - - features | object | The features of the output being spent |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The commit referencing the output being spent |
| - - outputs | []object | List of outputs the transaction produces |
| - - - features | object | Options for an output's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The homomorphic commitment representing the output amount |
| - - - proof | []number | A proof that the commitment is in the right range |
| - - kernels | []object | List of kernels that make up this transaction (usually a single kernel) |
| - - - features | object | Options for a kernel's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - fee | number | Fee originally included in the transaction this proof is for |
| - - - lock_height | number | The max lock_height of all inputs to this transaction |
| - - - excess | []number | Remainder of the sum of all transaction commitments |
| - - - excess_sig | []number | The signature proving the excess is a valid public key (signs the tx fee) |
| amount | number | Base amount (excluding fee) |
| fee | number | Fee amount |
| height | number | Block height for the transaction |
| lock_height | number | Lock height |
| participant_data | object | Participant data |
| - id | number | Id of participant in the transaction. (For now, 0=sender, 1=rec) |
| - public_blind_excess | []number | Public key corresponding to private blinding factor |
| - public_nonce | []number | Public key corresponding to private nonce |
| - part_sig | []number | Public partial signature |
* **Success Response:**
* **Code:** 200
* **Content:** A new transaction slate in JSON.
| Field | Type | Description |
|:----------------------|:---------|:--------------------------------------------------------------------------|
| num_participants | number | The number of participants intended to take part in this transaction |
| id | number | Unique transaction ID, selected by sender |
| tx | object | The core transaction data (inputs, outputs, kernels and kernel offset) |
| - offset | []number | The kernel "offset" k2, excess is k1G after splitting the key k = k1 + k2 |
| - body | object | The transaction body - inputs/outputs/kernels |
| - - inputs | []object | List of inputs spent by the transaction |
| - - - features | object | The features of the output being spent |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The commit referencing the output being spent |
| - - outputs | []object | List of outputs the transaction produces |
| - - - features | object | Options for an output's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The homomorphic commitment representing the output amount |
| - - - proof | []number | A proof that the commitment is in the right range |
| - - kernels | []object | List of kernels that make up this transaction (usually a single kernel) |
| - - - features | object | Options for a kernel's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - fee | number | Fee originally included in the transaction this proof is for |
| - - - lock_height | number | The max lock_height of all inputs to this transaction |
| - - - excess | []number | Remainder of the sum of all transaction commitments |
| - - - excess_sig | []number | The signature proving the excess is a valid public key (signs the tx fee) |
| amount | number | Base amount (excluding fee) |
| fee | number | Fee amount |
| height | number | Block height for the transaction |
| lock_height | number | Lock height |
| participant_data | object | Participant data |
| - id | number | Id of participant in the transaction. (For now, 0=sender, 1=rec) |
| - public_blind_excess | []number | Public key corresponding to private blinding factor |
| - public_nonce | []number | Public key corresponding to private nonce |
| - part_sig | []number | Public partial signature |
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/finalize_tx",
dataType: "json",
type : "POST",
success : function(r) {
console.log(r);
},
data: {
file: tx.json
},
});
```
### POST Cancel Tx
Roll back a transaction and all associated outputs with a given transaction id This means delete all change outputs, (or recipient output if you're recipient), and unlock all locked outputs associated with the transaction used when a transaction is created but never posted.
* **URL**
* /v1/wallet/owner/cancel_tx?id=x
* /v1/wallet/owner/cancel_tx?tx_id=x
* **Method:**
`POST`
* **URL Params**
**Required:**
* `id=[number]` the transaction id
* `tx_id=[string]`the transaction slate id
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/cancel_tx?id=3",
dataType: "json",
type : "POST",
success : function(r) {
console.log(r);
}
});
```
### POST Post Tx
Push new transaction to the connected node transaction pool. Add `?fluff` at the end of the URL to bypass Dandelion relay.
* **URL**
* /v1/wallet/owner/post_tx
* /v1/wallet/owner/post_tx?fluff
* **Method:**
`POST`
* **URL Params**
**Optional:**
`fluff` to bypass Dandelion relay
* **Data Params**
**Required:** A transaction slate in JSON.
| Field | Type | Description |
|:----------------------|:---------|:--------------------------------------------------------------------------|
| num_participants | number | The number of participants intended to take part in this transaction |
| id | number | Unique transaction ID, selected by sender |
| tx | object | The core transaction data (inputs, outputs, kernels and kernel offset) |
| - offset | []number | The kernel "offset" k2, excess is k1G after splitting the key k = k1 + k2 |
| - body | object | The transaction body - inputs/outputs/kernels |
| - - inputs | []object | List of inputs spent by the transaction |
| - - - features | object | The features of the output being spent |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The commit referencing the output being spent |
| - - outputs | []object | List of outputs the transaction produces |
| - - - features | object | Options for an output's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The homomorphic commitment representing the output amount |
| - - - proof | []number | A proof that the commitment is in the right range |
| - - kernels | []object | List of kernels that make up this transaction (usually a single kernel) |
| - - - features | object | Options for a kernel's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - fee | number | Fee originally included in the transaction this proof is for |
| - - - lock_height | number | The max lock_height of all inputs to this transaction |
| - - - excess | []number | Remainder of the sum of all transaction commitments |
| - - - excess_sig | []number | The signature proving the excess is a valid public key (signs the tx fee) |
| amount | number | Base amount (excluding fee) |
| fee | number | Fee amount |
| height | number | Block height for the transaction |
| lock_height | number | Lock height |
| participant_data | object | Participant data |
| - id | number | Id of participant in the transaction. (For now, 0=sender, 1=rec) |
| - public_blind_excess | []number | Public key corresponding to private blinding factor |
| - public_nonce | []number | Public key corresponding to private nonce |
| - part_sig | []number | Public partial signature |
* **Success Response:**
* **Code:** 200
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/post_tx",
dataType: "json",
type : "POST",
success : function(r) {
console.log(r);
},
data: {
file: tx.json
},
});
```
### POST Repost Tx
Repost a `sending` transaction to the connected node transaction pool with a given transaction id. Add `?fluff` at the end of the URL to bypass Dandelion relay . This could be used for retry posting when a `sending` transaction is created but somehow failed on posting.
* **URL**
* /v1/wallet/owner/repost?id=x
* /v1/wallet/owner/repost?tx_id=x
* /v1/wallet/owner/repost?fluff&tx_id=x
* **Method:**
`POST`
* **URL Params**
**Required:**
* `id=[number]` the transaction id
* `tx_id=[string]`the transaction slate id
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/repost?id=3",
dataType: "json",
type : "POST",
success : function(r) {
console.log(r);
}
});
```
### POST Issue Burn Tx
Issue a burn TX.
* **URL**
/v1/wallet/owner/issue_burn_tx
* **Method:**
`POST`
* **URL Params**
None
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/issue_burn_tx",
dataType: "json",
type : "POST",
success : function(r) {
console.log(r);
}
});
```
### Add Foreign API Endpoints
For some environments it may be convenient to have the [wallet foreign API](wallet_foreign_api.md) available on the same port as the owner API. You can do so by setting the `owner_api_include_foreign` configuration setting to `true`.
Reference in New Issue View Git Blame Copy Permalink