Basic Address Resolution
Last updated
Was this helpful?
Last updated
Was this helpful?
759684b1a19a
bsvalias Payment Addressing (Basic Address Resolution)
andy (nChain), Ryan X. Charles (Money Button)
1
Given a sender and a receiver, where the sender knows the receiver's paymail handle <alias>@<domain>.<tld>, the sender can perform Service Discovery against the receiver and request a payment destination from the receiver's paymail service.
The payment destination request endpoint is described in the .well-known/bsvalias configuration file:
The template values {alias} and {domain.tld} refer to the components of the receiver's paymail handle <alias>@<domain>.<tld> and must be substituted by the client before issuing a request.
The sender will receive a Bitcoin output script, which should be used in the construction of the payment transaction to the receiver.
The capabilities.paymentDestination path returns a URI template. Senders should replace the {alias} and {domain.tld} template parameters with the values from the receiver's paymail handle and then make an HTTP POST request against this URI.
The body of the POST request MUST have a content type of application/json and MUST conform to the following schema:
senderName
Human-readable sender display name
senderHandle
✓
sender's paymail handle
dt
✓
amount
The amount, in Satoshis, that the sender intends to transfer to the receiver
purpose
Human-readable description of the purpose of the payment
signature
Compact Bitcoin message signature; see notes
The timestamp field should contain the ISO-8601 formatted current time at the point the receiver initiates a payment destination request. From JavaScript this can be constructed using JSON.stringify():
Which yields:
The Bitcoin client has long offered the ability to sign messages and verify message signatures. The Bitcoin functionality is essentially an implementation of standard ECDSA, however along with the (r, s) signature pair there is additional information to allow the Bitcoin client to verify a message signature against a P2PKH address (a hash of a public key) rather than directly against a public key.
In the original draft of this specification, the signature was the raw (r, s) fields, computed over a double-SHA256 hash of the message. However in order to leverage existing Bitcoin client libraries, such as MoneyButton's BSV library, it has been decided instead to follow the Bitcoin client's signing and verification protocol.
The MoneyButton BSV library's implementation is nominated as the standard message digest construction and signature encoding method for signatures included in payment destination requests. Usage and reference implementation are available from GitHub.
The message to be signed begins with the Bitcoin signature scheme's traditional preamble (as documented within the BSV library's source code) and is followed by the UTF8 string concatenation of senderHandle, dt, amount and purpose fields.
If amount is present, it is converted to a string (with no leading zeros)
If amount is not present, the string "0" is used
If purpose is not present, an empty string "" is used (effectively purpose is not included in the message)
Below are the responses that have meaning to this protocol. A server may return other status codes, for example 5xx indicating some sort of server failure. Clients should treat status codes not specified as part of this specification as some sort of transient error and may retry at their leisure.
Returned when a valid request for a known paymail handle has been received. The return message MUST have a content type of application/json. The response body MUST conform to the following schema:
The value of the output field MUST be a hex-encoded Bitcoin script, which the sender MUST use during the construction of a payment transaction.
It is beyond the scope of this specification to describe the various possible types of output script, however it is expected that paymail services will implement at a minimum P2PKH output scripts.
Wallet implementers have expressed a desire to standardise their approach to key management within paymail implementations; this desire extends beyond the scope of paymail and covers cross-wallet key and seed import/recovery processes.
It is suggested that wallet implementers agree upon a mechanism for generating P2PKH output scripts, and create a BRFC to describe that scheme. Such a scheme is advised to avoid address re-use (that is, each P2PKH script includes the hash of the public key of a newly created key pair) and that existing mechanisms such as Type 2 HD Wallet key derivation be used. One advantage to this suggestion is that paymail services can be implemented such that they derive new keys from only an
xpub. In this way, neither the wallet seed nor any private keys are held by the paymail service implementation.
To illustrate a typical output field value, a standard P2PKH output script is constructed and encoded below.
Given a key pair with the public key 027c1404c3ecb034053e6dd90bc68f7933284559c7d0763367584195a8796d9b0e, a P2PKH output script for the same would be hex-encoded as:
This can be broken down as follows:
The service response body would be:
The paymail handle was not found by this service.
Sender Validation which performs a reverse PKI lookup on the sender then verifies the message signature
Receiver Approvals extends the payment destination process with asynchronous approvals by the receiver before yielding a payment destination script
formatted timestamp; see notes
