Closed ShookLyngs closed 2 months ago
This draft PR doesn't look ready yet
This draft PR doesn't look ready yet
Yes, the PR is still in draft, and it's currently for API interface preview only. Some props can be modified during further tests, but the shape of it is relatively clear now.
Please help review 'full RBF' test analysis. https://www.notion.so/full-RBF-Test-Case-f198159a01f045748605b9249bc0c649 @ShookLyngs @Flouse @duanyytop
The PR is now ready for review/test, please update your status here @Dawn-githup, thanks.
If we have an unconfirmed transaction chain:
And if we wish to construct an RBF transaction of the TX_A, let's call it TX_AR. When constructing the TX_AR, we should exclude O2 and O3 from being included in the inputs, preventing circular reference error since our goal is to replace TX_A and deduct its children (TX_B) from the blockchain. Kinda like the grandfather paradox.
Here's the question: how do we know that O3 should be excluded?
To address it, we may need to use this kind of API to help identify which transaction should be excluded in the RBF: https://mempool.space/docs/api/rest#get-transaction-outspends
The basic logic:
txid
of the resultstxid
should be excluded when constructing an RBF transaction of A, avoiding circular referencingWhat's more, things can get much more complicated if we're constructing an RBF of an RBF of a transaction. Another solution is to expose the excludeUtxos: BaseOutput[]
option and leave it to the users. But obviously it's not a user-friendly solution.
On second thought, maybe just set onlyConfirmedUtxos=true
and skipInputsValidation=true
when construting RBF transactions, allowing the original inputs to be unconfirmed UTXOs, while only collecting confirmed UTXOs for paying fee.
txHex
The hex of the original transaction.
changeIndex
Optional, default to undefined.
By default, all the inputs and outputs from the original transaction remains the same in the RBF transaction, but if you wish to charge fee from or return change satoshi to the change output of the original transaction, you can specify the option.
requireValidOutputsValue
Optional, default to false.
Require the value of each output in the RBF transaction to be greater or equals to
minUtxoSatoshi
.requireGreaterFeeAndRate
Optional, default to false.
Require the fee rate and the fee amount of the RBF transaction to be greater than the original transaction.
inputsPubkey
[EXPERIMENTAL] Optional, default to undefined.
A Map of addresses and public keys. It's useful when the original transaction contains multi-origin P2TR inputs. This option is currently unstable and can be updated, also note that in you won't need it most cases.
What about adding these descriptions to the README or code comments?
New options
skipInputsValidation
Previously, when the
onlyConfirmedUtxos
istrue
, all inputs will be validated and an error will be thrown if any input is unconfirmed. With theskipInputsValidation
option, you can skip validation of theprops.inputs
, while still apply theonlyConfirmedUtxos
rule to the satoshi collector.Which means if
onlyConfirmedUtxos = true
andskipInputsValidation = true
:
- UTXOs passed from the
props.inputs
option can be unconfirmed UTXOs- Only confirmed UTXOs will be collected during the pay fee process
In the
sendRbf()
API, this option is always set totrue
, allowing transaction chains to be RBF.excludeUtxos
This option is a list of UTXO[] to be excluded from the satoshi collection process when paying fee.
In the
sendRbf()
API, this option is used to exclude the outputs from the original transaction, preventing errors related to circular references (the RBF may uses outputs of the original transaction as the inputs if they're not excluded).New return type
changeIndex
All BTC Builder APIs now return a new property
changeIndex
, which indicates the specific output in the generated transaction to be the change output. Note that the value of thechangeIndex
can be-1
, meaning the transaction has no change output.
Same recommendation as above
What about adding these descriptions to the README or code comments?
I was thinking of maybe creating Markdown docs for each API, like this: packages/btc/docs/send-rbf.md
.
Adding comments to the props interface may also work; I'll try it in another PR.
Conflicts have been resolved, and the history commits are squashed into 8ce3593.
Additionally, all changes are documented in the changeset: https://github.com/ckb-cell/rgbpp-sdk/blob/08200c974ef336661723cc7556a003932babda9a/.changeset/spicy-cups-cheat.md
Changes
sendRbf()
andcreateSendRbfBuilder()
APIs to support Full-RBF of BTC transactionsexcludeUtxos
,skipInputsValidation
options in thesendUtxos()
API to support the RBF featureonlyProvableUtxos
option in thesendRgbppUtxos()
API for future update supportschangeIndex
in the return type of the BTC Builder APIsRelated issues
Reference
New APIs
The
sendRbf()
andcreateSendRbfBuilder()
APIs are design for constructing BTC Full-RBF transactions.txHex
The hex of the original transaction.
changeIndex
By default, all the inputs and outputs from the original transaction remains the same in the RBF transaction, but if you wish to charge fee from or return change satoshi to the change output of the original transaction, you can specify the option.
requireValidOutputsValue
Require the value of each output in the RBF transaction to be greater or equals to
minUtxoSatoshi
.requireGreaterFeeAndRate
Require the fee rate and the fee amount of the RBF transaction to be greater than the original transaction.
inputsPubkey
A Map of addresses and public keys. It's useful when the original transaction contains multi-origin P2TR inputs. This option is currently unstable and can be updated, also note that in you won't need it most cases.
New options
skipInputsValidation
Previously, when the
onlyConfirmedUtxos
istrue
, all inputs will be validated and an error will be thrown if any input is unconfirmed. With theskipInputsValidation
option, you can skip validation of theprops.inputs
, while still apply theonlyConfirmedUtxos
rule to the satoshi collector.Which means if
onlyConfirmedUtxos = true
andskipInputsValidation = true
:props.inputs
option can be unconfirmed UTXOsIn the
sendRbf()
API, this option is always set totrue
, allowing transaction chains to be RBF.excludeUtxos
This option is a list of UTXO[] to be excluded from the satoshi collection process when paying fee.
In the
sendRbf()
API, this option is used to exclude the outputs from the original transaction, preventing errors related to circular references (the RBF may uses outputs of the original transaction as the inputs if they're not excluded).onlyProvableUtxos
In the
sendRgbppUtxos()
API, this option is set totrue
by default, and it checks if each input's address is the same as thefrom
address. If set tofalse
, the address of the inputs can be different from thefrom
address.New return type
changeIndex
All BTC Builder APIs now return a new property
changeIndex
, which indicates the specific output in the generated transaction to be the change output. Note that the value of thechangeIndex
can be-1
, meaning the transaction has no change output.