README.md 5.43 KB
Newer Older
Lucas Betschart's avatar
Lucas Betschart committed
1
# Address Ownership Proof Protocol (AOPP)
Lucas Betschart's avatar
Lucas Betschart committed
2

3
4
## Mission Statement

Lucas Betschart's avatar
Lucas Betschart committed
5
The AOPP streamlines and automates address ownership proofs, which are required in interactions between private wallets and Virtual Asset Service Providers (VASPs), for example in virtual asset withdrawal.
6

Lucas Betschart's avatar
Lucas Betschart committed
7

8
9
## Specification

Lucas Betschart's avatar
Lucas Betschart committed
10
11
Link on the "Address Ownership Proof" web page of a VASP:

Lucas Betschart's avatar
Lucas Betschart committed
12
```
Lucas Betschart's avatar
Lucas Betschart committed
13
<a href="​aopp:?v=0&msg=vasp-chosen-msg&asset=btc&format=p2xxx&callback=https://vasp.com/proofs/vasp-chosen-token​">verify address</a>
Lucas Betschart's avatar
Lucas Betschart committed
14
15
16
17
18
```

Required parameters in version 0:

1. v: version number, always 0
Lucas Betschart's avatar
Lucas Betschart committed
19
1. msg: a vasp-chosen message up to 1024 ASCII characters;
Filip Gospodinov's avatar
Filip Gospodinov committed
20
   it is recommended to contain a ​nonce​ value
Lucas Betschart's avatar
Lucas Betschart committed
21
1. asset: a virtual asset identifier (as defined in [​SLIP-0044​]((https://github.com/satoshilabs/slips/blob/master/slip-0044.md)))
Lucas Betschart's avatar
Lucas Betschart committed
22
1. format: specifies a wallet address type the VASP expects
23
24
25
26
27
28
29
30
31
32
33
34
35
   in a callback;

    1. for "btc" asset it is:

        - p2pkh
        - p2wpkh
        - p2sh
        - p2tr
        - any

    1. for "eth" asset it is:
        - standard

Lucas Betschart's avatar
Lucas Betschart committed
36
1. callback: a VASP chosen URL endpoint where the client wallet sends the response to.
Lucas Betschart's avatar
Lucas Betschart committed
37

Filip Gospodinov's avatar
Filip Gospodinov committed
38
When a wallet encounters an unknown version number or other
Lucas Betschart's avatar
Lucas Betschart committed
39
unrecognised or invalid values in required parameters, it
Filip Gospodinov's avatar
Filip Gospodinov committed
40
41
should display an error and abort signing. Wallets should
ignore parameters not listed above.
Lucas Betschart's avatar
Lucas Betschart committed
42

Filip Gospodinov's avatar
Filip Gospodinov committed
43
44
On click, a desktop app shows up. The user confirms the
message. The app sends a response to the server:
Lucas Betschart's avatar
Lucas Betschart committed
45
46

**Response:**
47

Lucas Betschart's avatar
Lucas Betschart committed
48
49
50
51
```
POST <callback URL>
Content-Type: application/json; utf-8
{
Dominik Spicher's avatar
Dominik Spicher committed
52
    "version": 0,
Lucas Betschart's avatar
Lucas Betschart committed
53
54
55
56
57
58
    "address": "bc1000000000000000000000000",
    "signature": "​<Bitcoin Signed Message Signature>​"
}
```

**Response from the Server:**
59

60
1. HTTP 204: Signature is valid.
Lucas Betschart's avatar
Lucas Betschart committed
61
1. HTTP 400: Bad Request.
Lucas Betschart's avatar
Lucas Betschart committed
62
1. HTTP 404: The `vasp-chosen-token` in the callback URL doesn't exist.
Lucas Betschart's avatar
Lucas Betschart committed
63

64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
### Compressed Keys Only

Uncompressed keys are considered legacy and are not supported.

### Bitcoin Message Signatures

For bitcoin, the signatures are constructed following the
[algorithm](https://github.com/bitcoin/bitcoin/blob/13d27b452d4b60010c54d4f80757dea9805076be/src/util/message.cpp)
in bitcoin core. Special attention should be brought to the
encoding of the
[recovery byte](https://github.com/bitcoin/bitcoin/blob/a12962ca894075ae203ab808db4ba5dab23346d1/src/key.cpp#L257)
that _does not_ indicate information about witness addresses
in its encoding. This is the main difference between bitcoin
core's message signatures and other, less popular ones.

Please refer to the [wallet guide](./wallet_guide.md) for
further implementation hints.

82
83
84
85
86
87
88
### Ethereum Message Signatures

For ethereum, the signatures are constructed following the
same [algorithm](https://github.com/bitcoin/bitcoin/blob/13d27b452d4b60010c54d4f80757dea9805076be/src/util/message.cpp)
as in bitcoin core with the notable exception that the recovery
byte is _appended_ to the signature instead of prepended.

89
## Recommendations
90

91
92
93
94
1. Choose `any` for the address format if your VASP supports
   all possible address formats. Certain wallets (e.g.
   electrum) have a fixed address format and therefore letting
   them pick the address format will increase interoperability.
95
96
97
98
1. Choose a small message to improve UX using hardware wallets
   (small screens). Also, URIs have an implementation-defined
   limit so smaller URIs will have better interoperability in
   general.
Lucas Betschart's avatar
Lucas Betschart committed
99
1. [Add SRO approved message style here]
100
101
102
103
104
105
106
107
108

## FAQ

1. Why is there a format specifier?

    A format specifier allows a VASP to hint to a wallet what
    address format it can accept. Historically, certain VASPs
    have had poor support for various address formats.

Lucas Betschart's avatar
Lucas Betschart committed
109
1. How to deal with p2sh addresses?
110

Lucas Betschart's avatar
Lucas Betschart committed
111
    For p2sh addresses we need to presume that it's a p2wpkh
112
113
    address wrapped in a p2sh.

114
115
116
1. Why is the wallet choosing the address?

    Certain wallet types, such as hardware wallets, are limited
Lucas Betschart's avatar
Lucas Betschart committed
117
118
    in how they can handle specific workflows. To facilitate the
    adoption in all kinds of wallets, the protocol lets the
119
    wallet choose the address.
Dominik Spicher's avatar
Dominik Spicher committed
120

121
122
123
124
125
126
127
1. Why is there a limit on the `msg` parameter?

    [Some](https://github.com/digitalbitbox/bitbox02-firmware/blob/master/src/rust/bitbox02-rust/src/hww/api/bitcoin/signmsg.rs#L32)
    [wallets](https://github.com/trezor/trezor-firmware/blob/f93a8514e8e25b17b02360d9955c0a30999adf68/legacy/firmware/protob/messages-bitcoin.options#L15)
    have a hard limit on the size of the message, hence the 1024 character limit in AOPP.


Dominik Spicher's avatar
Dominik Spicher committed
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
## Test vectors

### Bitcoin

 - p2pkh
   - private key: L4MSJRS7EZNoinjUXJAKrtSgvA6epQDAmwgo5B2LJdVCcjEapPE1
   - address: 13LiZwTMfowMo5KsWHf5TNLmK78WSxVQCG
   - message: hello
   - signature: IFwh9XVPb8vvNUsbuuQU1Xk1jT652JD/6HN3cqnFn/MMBDziPbM8cOi83D29LRGSwMF3ZcjytD7nfNdn5dI0/50=
 - p2sh (wrapped SegWit)
   - private key: L5fETAwYWGRA1eWCHk8AgH2FX2rxLp64winwoAoRGpz1aQMp3Rai
   - address: 3JvVkfeKrrJstF66haNpFepfhxzQuBB78h
   - message: hello
   - signature: H1oYVmDaWxZBPEk2ou4myn1SRC20ycBUPPD5fLS+SmQ1e04Bi1J9mIJ5fNhe3khDhJRUX2fU+VHGKlJdAjYIvBU=
 - p2wpkh
   - private key: L5fETAwYWGRA1eWCHk8AgH2FX2rxLp64winwoAoRGpz1aQMp3Rai
   - address: bc1qnshsvhrfl28g03k0vxdez6vua56r0c72xy9e93
   - message: hello
   - signature: H1oYVmDaWxZBPEk2ou4myn1SRC20ycBUPPD5fLS+SmQ1e04Bi1J9mIJ5fNhe3khDhJRUX2fU+VHGKlJdAjYIvBU=

### Ethereum

Dominik Spicher's avatar
Dominik Spicher committed
150
151
152
153
 - private key: 4142e80a872531fd1055f52ccab713d4c7f1eee28c33415558e74faeb516de2b
 - address: 0x270402aeB8f4dAc8203915fC26F0768feA61b532
 - message: hello
 - signature: vbyudz7PM/tUdVjlL0wEtCnvn3PVYv8eCqCf/aLeVj8JwAsUVuyMMwbIInXAj7EtmZIUwlem7AOH0da8ygXmQBs=