Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Payment Channels review #1

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Payment Channels review #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9abdc3b
Add payment channels
BitcoinFiles Jul 20, 2020
b320269
Add sse
BitcoinFiles Jul 20, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
232 changes: 232 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1542,6 +1542,238 @@ data: {

```

## Payment Channels

Nakamoto style transaction replacement channels are supported in TXQ.

https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2013-April/002417.html

Use payment channels when you wish to coordinate actions amongst 2 or more parties, but do not wish to settle the transaction until
nLockTime and the final state of the data is acceptable

Note: Payment "Channels" have nothing directly related to the queue channel name used in the TXQ api. The name 'paymentChannelId' is used to distinguish the usage. In context below 'paymentChannelId' is a global identifier (preferred random uuid) that can be used by the client
to create, update, and manage the Nakamoto replacement payment channel.

### Create Payment Channel

Choose a globally unique identifier for `paymentChannel` and create it. Optionally provide a `rawtx` for the initial transaction statte.
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

statte

state

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will, fix thank you


Once a payment channel is initialized with the first transaction, then all subsequent updates must use the same inputs and adhere to the rules
regarding nSequence, nLockTime. See: https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2013-April/002417.html

`POST /api/v1/paymentchannel/:paymentChannelId`

```javascript
{
"rawtx": '003222...' // Optional initial rawtx to initialize with. If left empty then use "Updates" to change
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to confirm, so if I initialize a payment channel with TXQ and the server is restarted before the channel is closed, I would need to re-initialize the payment channel with rawtx of the original initiation and this would work. Is that correct?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. The payment channel will be persisted to DB, so if TXQ reboots you can continue where you left off.

I haven't updated the database schema yet, as this is just a proposal first to make sure it's the correct thing to build.

}

```

### Add Transaction to Payment Channel

`POST /api/v1/paymentchannel/:paymentChannelId/tx`

```javascript
{
"rawtx": '003222...' // Optional initial rawtx to initialize with. If left empty then use "Updates" to change
}

```

Response:

```javascript
{
"status": 200,
"errors": [],
"result": {
"closed": false, // Whether the channel is closed manually or one of the inputs was spent by an actual tx broadcasted
"state": {
"id": 135,
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What exactly is id here? A random int?

Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only asking because we already have paymentchannelid

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

id is the primary key of the tx (rawtx) in the database. The number is always guaranteed to be unique and increasing (but not necessarily consecutive, in other words it is monotonically increasing)

The purpose is an alternate id that you know is unique and chronologically ordered. It let's you know if a state is newer than another one by mere virtue of the fact that the latest state has a higher id.

It's not necessarily to expose to the client, perhaps I can hide it here. It may be useful to keep this in the sse updates because then it's easy to see when a state is newer.

"txid": "...",
"rawtx": "000022...",
"paymentchannelid": "my-id-payment-channel",
"updated_at": 1114554332,
"created_at": 1114554332
}
}
}
```

### Get Payment Channel State

`GET /api/v1/paymentchannel/:paymentchannelid`

Response:

```javascript
{
"status": 200,
"errors": [],
"result":
{
"closed": false, // Whether the channel is closed manually or one of the inputs was spent by an actual tx broadcasted
"state": {
"id": 135,
"txid": "...",
"rawtx": "000022...",
"paymentchannelid": "my-id-payment-channel",
"updated_at": 1114554332,
"created_at": 1114554332
}
}
}
```

### Get Payment Channel History

`GET /api/v1/paymentchannel/:paymentchannelid/history?limit=1000&offset=0`

Return the chronological history of transactions posted to the payment channel.

Response:

```javascript
{
"status": 200,
"errors": [],
"result": [
{
"id": 135,
"txid": "...",
"rawtx": "000022...",
"paymentchannelid": "my-id-payment-channel",
"updated_at": 1114554332,
"created_at": 1114554332,
},
{
"id": 125,
"txid": "...",
"rawtx": "000022...",
"paymentchannelid": "my-id-payment-channel",
"updated_at": 1114554332,
"created_at": 1114554332,
}
]
}
```

### Close Payment Channel

`POST /api/v1/paymentchannel/:paymentchannelid/close`

**Note:** The payment channel will automatically be closed if a transaction is broadcast via `/mapi` or `/tx`
when one of the inputs being spent collide with any transactions associated with a payment channel.

Client may forcefully close payment channel without broadcasting a transaction. No further additional transactions may be added
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When the channel is closed and the tx is not broadcasted, just save the rawtx locally and can broadcast whenever.

Q: Are payment channels pruned from TXQ? Or will all payment channels always exist in the database?

Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking at the SQL file I noticed that we don't store in the database whether the channel was closed and the transaction was broadcasted. Would this be valuable to add?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When the channel is closed and the tx is not broadcasted, just save the rawtx locally and can broadcast whenever.

Good point! The client can fetch the rawtx/latest state of the channel and broadcast, perfect!

Looking at the SQL file I noticed that we don't store in the database whether the channel was closed and the transaction was broadcasted. Would this be valuable to add?

I haven't really finished the schema. But very good points, I'll add them both in :)

to a payment channel when it is `closed: true`

Response:

```javascript
{
"status": 200,
"errors": [],
"result":
{
"closed": true, // Force set to true
"state": { // Return latest state if available
"id": 135,
"txid": "...",
"rawtx": "000022...",
"paymentchannelid": "my-id-payment-channel",
"updated_at": 1114554332,
"created_at": 1114554332
}
}
}
```

### Payment Channel Address Updates Stream

Stream all newly created payment outputs (For new transactions) by address.

`GET /sse/paymentchannel/address/:address` (SSE)

Example: <a href='https://public.txq-app.com/sse/paymentchannel/address/131xY3twRUJ1Y9Z9jJFKGLUa4SAdRJppcW' target="_blank">Payment Channel Address Stream</a>

```javascript

id: -1
data: ["connected"]

id: 2
data: {
"entity":{
"txid":"10ad1739b568d2060831b91771d9b836e0f4efcb113d3a866732bbb9b8ca7ae2",
"index":1,
"address":"131xY3twRUJ1Y9Z9jJFKGLUa4SAdRJppcW",
"scripthash":"525d063bd0c861fddc4d4881cb495038652bf432c9e2586cc37d49e98a3cc60e",
"script":"76a914161e9c31fbec37d9ecb297bf4b814c6e189dbe5288ac",
"satoshis":284442
},
"eventType":"paymentchanneltxout"
}

```


### Payment Channel ScriptHash Updates Stream

Stream all newly created payment outputs (For new transactions) by scripthashes.

`GET /sse/paymentchannel/scripthash/:scripthash` (SSE)

Example: <a href='https://public.txq-app.com/sse/paymentchannel/scripthash/525d063bd0c861fddc4d4881cb495038652bf432c9e2586cc37d49e98a3cc60e' target="_blank">Payment Channel ScriptHash Stream</a>

```javascript

id: -1
data: ["connected"]

id: 2
data: {
"entity":{
"txid":"10ad1739b568d2060831b91771d9b836e0f4efcb113d3a866732bbb9b8ca7ae2",
"index":1,
"address":"131xY3twRUJ1Y9Z9jJFKGLUa4SAdRJppcW",
"scripthash":"525d063bd0c861fddc4d4881cb495038652bf432c9e2586cc37d49e98a3cc60e",
"script":"76a914161e9c31fbec37d9ecb297bf4b814c6e189dbe5288ac",
"satoshis":284442
},
"eventType":"paymentchanneltxout"
}

```

### Payment Channel By Output Group Updates Stream

Stream all newly created payment outputs (For new transactions) by groups (ie: Output Group scripthash or addresses)

`GET /sse/paymentchannel/group/:groupname` (SSE)

Example: <a href='https://public.txq-app.com/sse/paymentchannel/group/mygroupname' target="_blank">Payment Channel By Output Group Stream</a>

```javascript

id: -1
data: ["connected"]

id: 2
data: {
"entity":{
"txid":"10ad1739b568d2060831b91771d9b836e0f4efcb113d3a866732bbb9b8ca7ae2",
"index":1,
"address":"131xY3twRUJ1Y9Z9jJFKGLUa4SAdRJppcW",
"scripthash":"525d063bd0c861fddc4d4881cb495038652bf432c9e2586cc37d49e98a3cc60e",
"script":"76a914161e9c31fbec37d9ecb297bf4b814c6e189dbe5288ac",
"satoshis":284442
},
"eventType":"paymentchanneltxout"
}

```

## Merchant API Proxy (mapi)

Expand Down
23 changes: 23 additions & 0 deletions src/database/migrations/202007190000-add-payment-channels.sql
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
CREATE TABLE paymentchannel (
paymentchannelid varchar PRIMARY KEY,
closed boolean NOT NULL,
updated_at integer NOT NULL,
created_at integer NOT NULL
);

CREATE TABLE paymentchannel_tx (
id SERIAL PRIMARY KEY,
txid varchar NOT NULL,
rawtx text NULL,
paymentchannelid varchar NOT NULL,
updated_at integer NULL,
created_at integer NOT NULL
);

CREATE INDEX idx_paymentchannel_tx_txid ON paymentchannel_tx USING btree (txid);
CREATE INDEX idx_paymentchannel_tx_paymentchannelid ON paymentchannel_tx USING btree (paymentchannelid);

-- Insert versions bootstrap
INSERT INTO versions(version) VALUES ('202007190000');