payment-network-btc-address-based-0.1.0.md

Payment Network - Bitcoin - Address based

You can be interested in this document if:

• you want to create your own implementation of the Request protocol
• you are curious enough to dive and see what is under the hood of the Request protocol

Prerequisite: Having read the advanced logic specification (see here).

Description

This extension allows the payments and the refunds to be made on the Bitcoin blockchain. One address for the payment and one for the refund must be created and used exclusively for one and only one request.

As a payment network, this extension allows to deduce a payment balance for the request. (see Interpretation)

Properties

Property	Type	Description	Requirement
id	String	constant value: "pn-btc-address-based"	Mandatory
type	String	constant value: "paymentNetwork"	Mandatory
version	String	constant value: "0.1.0"	Mandatory
events	Array	List of the actions performed by the extension	Mandatory
values	Object
values.paymentAddress	String	Bitcoin address for the payment	Optional
values.refundAddress	String	Bitcoin address for the refund	Optional

Note: to use the bitcoin testnet just replace the id by "pn-testnet-bitcoin-address-based"

---

Actions

Creation

Parameters

	Type	Description	Requirement
id	String	constant value: "pn-btc-address-based"	Mandatory
type	String	constant value: "paymentNetwork"	Mandatory
version	String	constant value: "0.1.0"	Mandatory
parameters	Object
parameters.paymentAddress	String	Bitcoin address for the payment	Optional
parameters.refundAddress	String	Bitcoin address for the refund	Optional

Conditions

This action is valid, if:

• The request currency.type must be "BTC"

Warnings

This action must trigger the warnings:

Warning	Condition
"paymentAddress is given by the payer"	if signer is the payer and paymentAddress is given
"refundAddress is given by the payee"	if signer is the payee and refundAddress is given

Note: These warnings are necessary to highlight to avoid attempt of fake payments and refunds. For example, a payer could create a request given as the payment address one of his own address. A system could interpret a transaction to this address as payment while the payee does not receive anything.

Results

A extension state is created with the following properties:

Property	Value
id	"pn-btc-address-based"
type	"paymentNetwork"
version	"0.1.0"
values
values.paymentAddress	paymentAddress from parameters if given, undefined otherwise
values.refundAddress	refundAddress from parameters if given, undefined otherwise
events	Array with one 'create' event (see below)

the 'create' event:

Property	Value
name	'create'
parameters
parameters.paymentAddress	paymentAddress from parameters if given, undefined otherwise
parameters.refundAddress	refundAddress from parameters if given, undefined otherwise

---

Updates

addPaymentAddress

Parameters

	Type	Description	Requirement
id	String	constant value: "pn-btc-address-based"	Mandatory
action	String	constant value: "addPaymentAddress"	Mandatory
parameters	Object
parameters.paymentAddress	String	Bitcoin address for the payment	Mandatory

Conditions

This action is valid, if:

• The extension state with the id "pn-btc-address-based" exists
• The signer is the payee
• The extension property paymentAddress is undefined

Warnings

None.

Results

A extension state is updated with the following properties:

Property	Value
values.paymentAddress	paymentAddress from parameters
events	add an 'paymentAddress' event (see below) at its end

the 'addPaymentAddress' event:

Property	Value
name	constant value: "addPaymentAddress"
parameters
parameters.paymentAddress	paymentAddress from parameters

addRefundAddress

Parameters

	Type	Description	Requirement
id	String	constant value: "pn-btc-address-based"	Mandatory
action	String	constant value: "addRefundAddress"	Mandatory
parameters	Object
parameters.refundAddress	String	Bitcoin address for the refund	Mandatory

Conditions

This action is valid, if:

• The extension state with the id "pn-btc-address-based" exists
• The signer is the payer
• The extension property refundAddress is undefined

Warnings

None.

Results

A extension state is updated with the following properties:

Property	Value
values.refundAddress	refundAddress from parameters
events	add an 'addRefundAddress' event (see below) at its end

The 'addRefundAddress' event:

Property	Value
name	'addRefundAddress'
parameters
parameters.refundAddress	refundAddress from parameters

---

Interpretation

The balance starts from 0. Any bitcoin transaction reaching the address addPaymentAddress is considered as payment. The balance is increased by the amount of the transaction. Any bitcoin transaction reaching the address addRefundAddress is considered as a refund. The balance is reduced by the amount of the transaction.