Skip to main content

Building Epic transfers

Endpoint
http://127.0.0.1:3420/v3/owner
Credential
Token from open_wallet, inside the encrypted envelope. Loopback only
Methods here
7
Documented against
node 4.0.3, wallet 4.0.0

init_send_tx

Can move funds

Select inputs and build the first round of a slate.

Builds the slate but does not yet reserve anything. Nothing is released or committed until you call tx_lock_outputs or abandon the slate.

Surface
/v3/owner on port 3420
Parameters
2 named
Declared in
api/src/owner_rpc_s.rs:559
  • estimate_only is how to quote a fee safely: it returns the slate that would be built and reserves nothing.
  • selection_strategy_is_use_all true spends every output you hold, which consolidates dust and also links all of it together in one transaction. That is a privacy cost, not just a fee choice.
Parameters

Session token. Every method on this surface needs it.

Full argument object. estimate_only true quotes a fee without building anything.

19 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "init_send_tx",
  "params": {
    "token": "<token from open_wallet>",
    "args": {
      "src_acct_name": null,
      "amount": "100000000",
      "minimum_confirmations": 10,
      "max_outputs": 500,
      "num_change_outputs": 1,
      "selection_strategy_is_use_all": false,
      "target_slate_version": null,
      "ttl_blocks": null,
      "estimate_only": false
    }
  }
}
Response
N/A

tx_lock_outputs

Can move funds

Reserve the inputs the slate selected.

This is the call that makes your outputs unavailable. Nothing times out and restarting the wallet does not release them, because the lock is a local record. Only cancel_tx releases them.

Surface
/v3/owner on port 3420
Parameters
4 named
Declared in
api/src/owner_rpc_s.rs:897
  • Mandatory in any manual send. It is also the one method the previous published reference omitted entirely, which made that reference unusable for building a sender.
  • participant_id has no default. Leaving it out fails at the JSON-RPC boundary rather than in the wallet.
Parameters

Session token. Every method on this surface needs it.

The slate returned by init_send_tx.

Not optional. Zero for the sender.

Counterparty address, recorded in the log.

11 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tx_lock_outputs",
  "params": {
    "token": "<token from open_wallet>",
    "slate": {},
    "participant_id": 0,
    "addr_to": null
  }
}
Response
N/A

finalize_tx

Can move funds

Complete the aggregate signature once the counterparty has signed.

Produces a valid transaction. It does not broadcast: post_tx does that, and a finalised but unposted transaction still holds your outputs.

Surface
/v3/owner on port 3420
Parameters
2 named
Declared in
api/src/owner_rpc_s.rs:1072
Parameters

Session token. Every method on this surface needs it.

The countersigned slate.

9 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "finalize_tx",
  "params": {
    "token": "<token from open_wallet>",
    "slate": {}
  }
}
Response
N/A

post_tx

Can move funds

Broadcast a finalised transaction to the network.

Irreversible. Once accepted there is no unbroadcast and no fee replacement, and a transaction already in the mempool can no longer be cancelled.

Surface
/v3/owner on port 3420
Parameters
3 named
Declared in
api/src/owner_rpc_s.rs:1143
Parameters

Session token. Every method on this surface needs it.

The finalised transaction.

Skip the Dandelion stem phase and broadcast immediately.

10 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "post_tx",
  "params": {
    "token": "<token from open_wallet>",
    "tx": {},
    "fluff": false
  }
}
Response
N/A

cancel_tx

Changes state

Abandon an incomplete transfer and release its reserved outputs.

The only thing that releases a lock. It needs a reachable node, exactly one matching transaction, and a state that is not yet confirmed, so a transaction in the mempool cannot be cancelled at all.

Surface
/v3/owner on port 3420
Parameters
3 named
Declared in
api/src/owner_rpc_s.rs:1177
  • Cancel the transfer you actually mean. Passing neither id, or an id that matches more than one record, is an error rather than a guess.
Parameters

Session token. Every method on this surface needs it.

Transaction log id. Pass this or tx_slate_id.

Slate uuid.

10 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "cancel_tx",
  "params": {
    "token": "<token from open_wallet>",
    "tx_id": null,
    "tx_slate_id": null
  }
}
Response
N/A

issue_invoice_tx

Can move funds

Request an amount from someone else, reversing who starts the exchange.

Creates a slate that asks to be paid. It reserves nothing of yours, but the payer who funds it commits their outputs.

Surface
/v3/owner on port 3420
Parameters
2 named
Declared in
api/src/owner_rpc_s.rs:644
  • dest_acct_name is not passed on the CLI path, so an invoice created there credits the active account.
Parameters

Session token. Every method on this surface needs it.

Amount in freemen, and optionally which account to credit.

13 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "issue_invoice_tx",
  "params": {
    "token": "<token from open_wallet>",
    "args": {
      "dest_acct_name": null,
      "amount": "100000000",
      "target_slate_version": null
    }
  }
}
Response
N/A

process_invoice_tx

Can move funds

Fund somebody else's invoice.

This is the paying side of an invoice, so it selects your inputs. Treat it with the same care as init_send_tx followed by tx_lock_outputs.

Surface
/v3/owner on port 3420
Parameters
3 named
Declared in
api/src/owner_rpc_s.rs:805
Parameters

Session token. Every method on this surface needs it.

The invoice slate you were given.

Same argument object as init_send_tx. The amount comes from the slate.

17 lines
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "process_invoice_tx",
  "params": {
    "token": "<token from open_wallet>",
    "slate": {},
    "args": {
      "src_acct_name": null,
      "amount": "0",
      "minimum_confirmations": 10,
      "max_outputs": 500,
      "num_change_outputs": 1,
      "selection_strategy_is_use_all": false
    }
  }
}
Response
N/A

Next​

Send and receive in code

The full six-call sequence against a running wallet.

Diagnose a stuck transaction

Recovering the inputs a half-finished sequence reserved.

Interactive transactions

What each round of the slate exchange contributes.