AOPP integration guide

21 Travel Rule makes it easy for VASPs to integrate AOPP into their stack. This document outlines what is required from the VASP to successfully deploy AOPP support. The subsystem in 21 Travel Rule handling AOPP support is called aopd.

We define several entities:

  • User: this is the end-user of the VASP
  • VASP: this is the software with which the User interacts
  • 21 Travel Rule: the software licenced from 21 Analytics
  • Private Wallet: the User's private cryptocurrency wallet
  • Custody: the subsystem of the VASP responsible for onchain transactions, the interaction with this system can be automated or manual

Core flow

The VASP and 21 Travel Rule communicate via a single websocket. This socket is initiated by the VASP and a single message is send to 21 Travel Rule. 21 Travel Rule will put two messages on the socket. One immediate after the first message from the VASP and the other once the Private Wallet submitted the signed proof. One socket connection is used for one proof. Once the second message is received by the VASP the connection is closed by 21 Travel Rule. When a new proof is required a new connection should be opened.

The following sequence diagram depicts the core flow: Sequence diagram basic

1. Request AOPP URI

The VASP requests an AOPP URI from the 21 Travel Rule. It does this by opening a websocket. The socket is served at the root of the location where 21 Travel Rule is hosted. For example when the software is hosted on 21travel.<your-domain>.com the websocket URL is wss://21travel.<your-domain>.com/. After opening the socket a JSON document is sent on that socket with the format:

{
    "msg": "some message choosen by the VASP to be displayed in the user's wallet",
    "asset": "an asset identifier. Possible values are 'btc' or 'eth'",
    "format": "the required address format. Possible values are 'p2pkh', 'p2wpkh', 'p2sh', 'p2tr' or 'any'"
}

Depending on the Custody solution a value for format needs to be choosen. If possible any is preferred.

2. AOPP URI

A response is sent immediately by 21 Travel Rule. That looks like this:

aopp:?v=0&msg=vasp-chosen-msg&asset=btc&format=p2xxx&callback=https://vasp.com/xxxx

3. Address

Once a signed proof is received from the Private Wallet a single string containing an address is send to the VASP by 21 Travel Rule. An example message is "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa".

At this point the websocket is closed.

Full example scenario

In this scenario the User wants to withdraw a specific amount. On the withdraw page of the VASP the User enters the amount he wants to withdraw and after he submits the form is prompted to provide a verified address via the AOPP protocol.

A new address is requested from the user each time but the User interaction is kept at a minimum.

The withdraw flow is displayed in the following diagram, with the core flow as the dashed lines: Sequence diagram AOPP

1. Withdrawal request

The User is logged in on the VASP's website and initiates a withdrawal request. Critically the request contains an amount the User wants to withdraw and the amount is available to the User to actually withdraw. At this point, the VASP knows of the withdrawal request of that particular user and the amount.

2. Request AOPP URI

The VASP opens a websocket and requests an AOPP URI from the 21 Travel Rule. The msg parameter is chosen by the VASP and is suggested to contain a meaningful message as it is displayed to the User in his Private Wallet. A good example would be "I confirm that this Bitcoin (BTC) address is controlled by Jennifer Cox, Poststrasse 22, Zug, Switzerland. Unique Identifier: 2238833c7ff51f53". It contains a meaningful statement on what the User is about to do and an identifier for internal correlation.

3. AOPP URI

A response is sent immediately by 21 Travel Rule. That looks something like this:

aopp:?v=0&msg=I+confirm+that+this+Bitcoin+%28BTC%29+address+is+controlled+by+Jennifer+Cox%2C+Poststrasse+22%2C+Zug%2C+Switzerland.+Unique+Identifier%3A+2238833c7ff51f53&asset=btc&format=any&callback=https%3A%2F%2Fdemo.21analytics.ch%2Fproofs%2F1dade3e8-cd22-4a05-b96e-49bf3e2d5e34

4. Display AOPP URI

The VASP now displays the AOPP URI to the User. Either by encoding it in a QR code or by making it into a HTML link. The User is then expected to scan the QR with their supported wallet or click the link which will open a supported wallet.

5. Signed proof

The User then simply clicks or taps the pop up in his Private Wallet upon which the Private Wallet generates an address and sends a signed proof to 21 Travel Rule.

6. Address

Upon reception of the signed proof from the Users Private Wallet a new message is sent on the existing websocket connection to the VASP containing a single address.

7. Initiate withdrawal process

The VASP now has in hand the amount and the verified address and can proceed with the actual withdrawal process.