mirror of
https://github.com/jwinterm/grin-wallet.git
synced 2026-10-17 07:11:36 +02:00
65 lines
3.4 KiB
Markdown
65 lines
3.4 KiB
Markdown
# Wallet contracts
|
|
|
|
Contracts use the same flow for standard sends and invoice transactions. Signing is kept
|
|
as an explicit step, so both sides can check the transaction before they sign it.
|
|
|
|
A two-party contract is `new`, `sign`, `sign`. A self-spend is `new`, `sign`. There is no
|
|
separate `setup` command. Setup is done by `new`, or by the first `sign` when needed.
|
|
|
|
The owner API provides all four commands. The Rust foreign API also provides `new` and
|
|
`sign` for receiving contracts, but they are not exposed by the foreign JSON-RPC API. The
|
|
API does not require manual confirmation, so a wallet using it still needs to show the
|
|
transaction and ask the user before signing. The reference CLI does not show the full
|
|
inputs, outputs, fees and balance changes yet.
|
|
|
|
The CLI exchanges Slatepacks. The last `sign` broadcasts the transaction unless
|
|
`--no-broadcast` is used.
|
|
|
|
## Amounts and fees
|
|
|
|
`--send` and `--receive` are the amount being transferred, before each side pays its own
|
|
fee. The sender spends the amount plus its fee. The receiver gets the amount minus its
|
|
fee. Each side pays for the inputs and outputs it adds, plus its rounded-up share of the
|
|
kernel fee.
|
|
|
|
CLI amounts are human readable. Values passed to the API, including `make_outputs`, are in
|
|
nanogrin. Outputs requested with `make_outputs` are added together with the output needed
|
|
to balance that side of the transaction.
|
|
|
|
Payjoin is used by default. A receiver adds an input when one is available. An empty wallet
|
|
can still receive; the fee is then taken from the received output. `--no-payjoin` prevents
|
|
the receiver from adding an input and cannot be used together with `--use-inputs`.
|
|
|
|
Inputs and outputs are normally picked when signing. `--add-outputs` picks and locks them
|
|
during `new`, but they are still only added to the slate when signing. `--use-inputs` and
|
|
`--make-outputs` limit the selection but do not lock anything early. Open contracts do not
|
|
reserve funds against each other, so a late-locked contract can fail when another
|
|
transaction has spent the available outputs first.
|
|
|
|
## View and revoke
|
|
|
|
`view` reads a slate or Slatepack and shows the participants, signatures, suggested or
|
|
agreed amount change, and whether the local transaction is confirmed. It does not show all
|
|
inputs, outputs and fees, and it cannot find a contract by id.
|
|
|
|
`revoke` cancels the local transaction. When the wallet added an input, it returns a
|
|
self-spend of that input. The caller still has to post it, and either transaction can win
|
|
if the original is already in the mempool. When the wallet added no input there is no
|
|
replacement transaction. The replacement does not use a higher fee. An interrupted
|
|
`revoke` can be run again.
|
|
|
|
## Current limitations
|
|
|
|
* Only one or two participants are supported
|
|
* A returned slate is not yet checked against every input and output saved during setup
|
|
* Early invoice payment proofs are only available through the API and require the
|
|
experimental Slate V5 format. Other proof types are not supported
|
|
* Custom fee rates and contract TTLs are not supported
|
|
* There are no contract-specific history, lookup or transport commands. Payment proof
|
|
memos cannot be set through the contract API or CLI
|
|
* If writing the signed transaction file fails, the wallet state has already been saved.
|
|
Cancelling the transaction releases the locked inputs
|
|
|
|
Implementation notes and remaining work are kept in
|
|
[`libwallet/src/contract/actions/README.md`](../libwallet/src/contract/actions/README.md).
|