WIP: onchain bitcoin payment method #283

asmo · 2025-08-25T23:28:23Z

gudnuf commented

2025-08-25 23:28:23 +00:00

(Migrated from github.com)

CDK https://github.com/cashubtc/cdk/pull/995
Nutshell
cashu-ts https://github.com/cashubtc/cashu-ts/pull/349
nutmix

- [ ] CDK https://github.com/cashubtc/cdk/pull/995 - [ ] Nutshell - [ ] cashu-ts https://github.com/cashubtc/cashu-ts/pull/349 - [ ] nutmix

🚀 1

gudnuf (Migrated from github.com) reviewed

2025-08-25 23:32:10 +00:00

26.md

					
				@ -0,0 +299,4 @@

				  "unit": "sat",

				  "fee": 5000,

				  "estimated_blocks": 1,

				  "state": "PENDING",

should a melt be considered PAID as soon as the mint broadcasts the transaction, or should PENDING mean the transaction was broadcast but not yet mined?

Also, what happens if fees spike and the transaction does not confirm? Is it the mint or wallet's responsibility?

It seems to me like the mint should pick a fee_reserve that it is comfortable with and then it is the mint's responsibility to make sure the transaction gets mined.

UPDATE:

after discussions with tsk I made some changes to this nut and now PENDING means that the transaction is being processed by the mint. Processing can either be waiting for a batched transaction to be broadcast or while the tx is in the mempool. COMPLETED means the transaction has been mined into a block.

On fees, the mint can return multiple melt quotes with absolute fees based on user's desired confirmation time. If fees spike the mint can choose to fail the melt quote and release the pending proofs, or the mint can dip into some fee reserve wallet to cover it's bad estimate

should a melt be considered PAID as soon as the mint broadcasts the transaction, or should PENDING mean the transaction was broadcast but not yet mined? Also, what happens if fees spike and the transaction does not confirm? Is it the mint or wallet's responsibility? It seems to me like the mint should pick a `fee_reserve` that it is comfortable with and then it is the mint's responsibility to make sure the transaction gets mined. UPDATE: after discussions with tsk I made some changes to this nut and now PENDING means that the transaction is being processed by the mint. Processing can either be waiting for a batched transaction to be broadcast or while the tx is in the mempool. COMPLETED means the transaction has been mined into a block. On fees, the mint can return multiple melt quotes with absolute fees based on user's desired confirmation time. If fees spike the mint can choose to fail the melt quote and release the pending proofs, or the mint can dip into some fee reserve wallet to cover it's bad estimate

asmo reviewed

2025-08-28 11:09:45 +00:00

26.md

					
				@ -0,0 +1,339 @@

				# NUT-26: Onchain

> **Note:** While a pubkey is optional as per [NUT-20][20] for [NUT-04][04], it is required in this NUT and the mint **MUST NOT** issue a mint quote if one is not included.

```suggestion > **Note:** While a pubkey is optional as per [NUT-20][20] for [NUT-04][04], it is required in this NUT and the mint **MUST NOT** issue a mint quote if one is not included. ```

- `amount_confirmed` is the total confirmed amount paid to the mint via the onchain address

```suggestion - `amount_confirmed` is the total confirmed amount paid to the mint via the onchain address ```

The unconfirmed amount should be optional, since it could be omitted by certain PaymentBackend implementations.

  "amount_unconfirmed": <int|null>

The unconfirmed amount should be optional, since it could be omitted by certain PaymentBackend implementations. ```suggestion "amount_unconfirmed": <int|null> ```

26.md

					
				@ -0,0 +32,4 @@

				  "unit": <str_enum[UNIT]>,

				  "expiry": <int|null>,

				  "pubkey": <str>,

				  "amount_paid": <int>,

Suggesting to rename amount_paid to amount_confirmed

  "amount_confirmed": <int>,

Suggesting to rename `amount_paid` to `amount_confirmed` ```suggestion "amount_confirmed": <int>, ```

gudnuf (Migrated from github.com) reviewed

2025-08-28 20:03:14 +00:00

26.md

					
				@ -0,0 +1,339 @@

				# NUT-26: Onchain

The nice thing about keeping this as amount_paid is its the same for bolt12 so the implementation is easier because for bolt12 and onchain quote you can compare amount_paid with amount_issued.

The nice thing about keeping this as `amount_paid` is its the same for bolt12 so the implementation is easier because for bolt12 and onchain quote you can compare `amount_paid` with `amount_issued`.

thesimplekid (Migrated from github.com) reviewed

2025-08-28 20:55:43 +00:00

26.md

					
				@ -0,0 +1,339 @@

				# NUT-26: Onchain

The nice thing about keeping this as amount_paid is its the same for bolt12 so the implementation is easier because for bolt12 and onchain quote you can compare amount_paid with amount_issued.

I would prefer to keep it for this reason as well.

> The nice thing about keeping this as amount_paid is its the same for bolt12 so the implementation is easier because for bolt12 and onchain quote you can compare amount_paid with amount_issued. I would prefer to keep it for this reason as well.

thesimplekid (Migrated from github.com) reviewed

2025-08-28 20:58:42 +00:00

26.md

					
				@ -0,0 +285,4 @@

				**Melt request**:

				```bash

				curl -X POST https://mint.host:3338/v1/melt/onchain -d \

I think we need to revist this for onchain and we should just do it for all of them while were at it. https://github.com/cashubtc/nuts/issues/37.

But for onchain specifically it make no sense to wait for the melt to confirm and request should return okay once it is received.

I think we need to revist this for onchain and we should just do it for all of them while were at it. https://github.com/cashubtc/nuts/issues/37. But for onchain specifically it make no sense to wait for the melt to confirm and request should return okay once it is received.

gudnuf (Migrated from github.com) reviewed

2025-08-28 22:30:13 +00:00

26.md

					
				@ -0,0 +285,4 @@

				**Melt request**:

				```bash

				curl -X POST https://mint.host:3338/v1/melt/onchain -d \

If we are going to say that a melt quote does not complete until the transaction is confirmed, then yeah. If a completed melt quote means the transaction was broadcast, then it seems fine to wait.

Was that the consensus that the quote stays pending until the transaction is confirmed?

If we are going to say that a melt quote does not complete until the transaction is confirmed, then yeah. If a completed melt quote means the transaction was broadcast, then it seems fine to wait. Was that the consensus that the quote stays pending until the transaction is confirmed?

thesimplekid (Migrated from github.com) reviewed

2025-08-28 23:14:03 +00:00

26.md

					
				@ -0,0 +285,4 @@

				**Melt request**:

				```bash

				curl -X POST https://mint.host:3338/v1/melt/onchain -d \

If we are going to say that a melt quote does not complete until the transaction is confirmed, then yeah. If a completed > melt quote means the transaction was broadcast, then it seems fine to wait.

What if a mint wants to batch then it doesn't work for broadcast even.

> If we are going to say that a melt quote does not complete until the transaction is confirmed, then yeah. If a completed > melt quote means the transaction was broadcast, then it seems fine to wait. What if a mint wants to batch then it doesn't work for broadcast even.

thesimplekid (Migrated from github.com) reviewed

2025-08-30 12:09:30 +00:00

26.md

					
				@ -0,0 +1,339 @@

				# NUT-26: Onchain

This should be outpoint not just txid. txid:vout

This should be outpoint not just txid. `txid:vout`

thesimplekid (Migrated from github.com) reviewed

2025-08-31 07:59:16 +00:00

26.md

					
				@ -0,0 +241,4 @@

				**Melt quote response**:

				```json

  "outpoint: <str>,

```suggestion "outpoint: <str>, ```

gudnuf (Migrated from github.com) reviewed

2025-09-02 23:28:55 +00:00

26.md

					
				@ -0,0 +241,4 @@

				**Melt quote response**:

				```json

oh duh, thanks I updated it

gudnuf (Migrated from github.com) reviewed

2025-09-02 23:44:43 +00:00

26.md

					
				@ -0,0 +285,4 @@

				**Melt request**:

				```bash

				curl -X POST https://mint.host:3338/v1/melt/onchain -d \

I think we need to revist this for onchain and we should just do it for all of them while were at it.

Is there a change you suggest I make here? In NUT-05 it says:

"For methods that involve external payments (like Lightning), this call may block until the payment either succeeds or fails. This can take a long time. Make sure to use no (or a very long) timeout when making this call!"

The way this nut is now seems fine as it shows that a "successful melt response" returns the quote as PENDING and NUT-05 is pretty open-ended in that it says, "this call may block".

> I think we need to revist this for onchain and we should just do it for all of them while were at it. Is there a change you suggest I make here? In NUT-05 it says: "For methods that involve external payments (like Lightning), this call may block until the payment either succeeds or fails. This can take a long time. Make sure to use no (or a very long) timeout when making this call!" The way this nut is now seems fine as it shows that a "successful melt response" returns the quote as PENDING and NUT-05 is pretty open-ended in that it says, "this call may block".