grin/doc/api/wallet_owner_api.md

Wallet Owner API Documentation

Table of Contents

1. Wallet Owner Endpoint
   1. GET Retrieve Outputs
   2. GET Retrieve Summary Info
   3. GET Node Height
   4. GET Retrieve Txs
   5. GET Retrieve Stored Tx
   6. POST Issue Send Tx
   7. POST Finalize Tx
   8. POST Cancel Tx
   9. POST Post Tx
   10. POST Repost Tx
   11. POST Issue Burn Tx
   12. Adding 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:

    $.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: 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:

    $.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:

    $.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:

    $.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:

    $.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
  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:

    $.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 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:

    $.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:

    $.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:

    $.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:

    $.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:

    $.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 available on the same port as the owner API. You can do so by setting the owner_api_include_foreign configuration setting to true.