Skip to content

Latest commit

 

History

History
145 lines (93 loc) · 6.79 KB

ovip-0002.md

File metadata and controls

145 lines (93 loc) · 6.79 KB
Raw
OVIP: 2
Title: Virtual Assets Account Number (VAAN)
Author: David Riegelnig <david.riegelnig@bitcoinsuisse.com>
Discussions-To: https://community.openvasp.org/#narrow/stream/21-protocol-.2F.20ovip
Status: Accepted
Type: Standard
Created: 2020-05-04

Abstract

This OVIP specifies format and processing requirements for the Virtual Assets Account Number (VAAN), which is used as a customer identifier in the OpenVASP protocol. It is a revision of the initial VAAN specification proposed in the OpenVASP White Paper.

Specification

1. General Description

The Virtual Assets Account Number is a customer identifier as part of the OpenVASP protocol. It is abbreviated as VAAN.

Virtual Assets Service Providers (VASPs) assign VAANs to their customers in order to facilitate virtual asset transfers between VASPs.

More information can be found in section 4. Usage Scenarios.

2. Format

2.1. Structure

The VAAN consists of 24 hexadecimal characters and has the following parts:

tt | rr | vvvvvvvv | cccccccccc | xx

t = VASP Code Type      (2 characters, 8 bit)
r = Reserved bits       (2 characters, 8 bit)
v = VASP Code           (8 characters, 32 bit)
c = Internal Identifier (10 characters, 40 bit)
x = Check Digits        (2 characters, 8 bit)

Example: 10 | 00 | bb528777 | e33b078520 | 9e

2.1.1. VASP Code Type

The VASP Code Type specifies how the VASP Code used in this VAAN was defined. It consists of 2 hexadecimal characters. VASP Code Types starting with an alphabetical character ([a-f]) are reserved to indicate testnet VAANs.

List of VASP Code Types (continuously updated):

Mainnet:
10: VASP Code assigned by standardized OpenVASP Ethereum Mainnet smart contract with address 0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX (TBD).
Testnet:
f0: Testnet VASP Code assigned by OpenVASP Ethereum Mainnet smart contract with address 0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX (TBD).
2.1.2. Reserved Bits

Two hexadecimal characters reserved for future use. Must be zero ('00').

2.1.3. VASP Code

Unique identifier for the Virtual Assets Service Provider (VASP) given a specific VASP Code Type, who has assigned the VAAN to one of its customers. The VASP Code consists of 8 hexadecimal characters.

2.1.4. Internal Identifier

Internal customer identifier assigned by the VASP, consisting of 10 hexadecimal characters.

2.1.5. Check Digits

Two hexadecimal characters representing an 8-bit CRC-8/WCDMA. The generic CRC algorithm is well described at https://www.autosar.org/fileadmin/user_upload/standards/classic/4-3/AUTOSAR_SWS_CRCLibrary.pdf, the parameters for CRC-8/WCDMA can be found at https://users.ece.cmu.edu/~koopman/crc/crc8.html. The input for the checksum must be interpreted as a hex encoded byte array, not as a ASCII encoded string.

2.1.6. VASP Identifier

The VASP Identfier is the implicit combination of the VASP Code Type, the two Reserved Bits and the VASP Code. It uniquely, globally identifies a VASP. It is, in other words, the first 12 hexadecimal characters of a VAAN.

Example: 1000bb528777

3. Processing Requirements

3.1. Print and Display

When printed or displayed, the VAAN should be expressed in groups of four characters separated by a single space and using lowercase letters for hexadecimal digits from a to f. This representation is called human-readable format.

Example: 1000 bb52 8777 e33b 0785 209e

3.2. Transmission and Storage

The VAAN must be transmitted or stored without spaces and using lowercase letters for hexadecimal digits from a to f. This representation is the canonical format with strings matching the regular expression:

^[a-f0-9]{24}$

Example: 1000bb528777e33b0785209e

3.3. Reception

Besides the canonical format, implementations must accept spaces and uppercase letters for hexadecimal digits from a to f when receiving a VAAN string from other systems.

Examples:

1000 bb52 8777 e33b 0785 209e

1 0 0 0 b b 5 2 8 7 7 7 e 3 3 b 0 7 8 5 2 0 9 e

1000 BB528777 E33B078520 9E

1000BB52 8777e33b0785209e

4. Usage Requirements

4.1 Unique Assignment to One Client

Each VAAN must be uniquely assigned to exactly one customer and must never be reassigned.

Besides this requirement, VASPs can freely assign VAANs to their customers within the boundaries of the format.

4.2. Multiple VAANs per Customer

VASPs can assign as many VAANs to one customer as they wish. Furthermore, VASPs are free to decide on their concurrent use.

Motivation

  1. Future adaptability -- The initial VAAN specification proposed in the OpenVASP White Paper has no ability to adapt to future requirements. One particular area is the VASP identity, which is represented by the VASP Code. This OVIP implements a proposal by Lewin Boehnke (Crypto Storage AG) to include a VASP Code Type that allows for other identity directories then the standardized OpenVASP Ethereum smart contracts.
  2. Ambiguity -- The OpenVASP White Paper does not specify requirements for processing and usage with the level of precision necessary for interoperability between different implementations.
  3. Weak check digits -- The initially specified simple checksum of all bytes modulo 256 is vulnerable to swapped bytes, which might be exploited for deceptive purposes. For example if the first and the second four characters of the VASP Code are swapped in a VAAN, the checksum would be the same. A better approach is therefore proposed.

Rationale

  • Minimal adjustment -- Requirements are close to the VAAN specification outlined in the OpenVASP White Paper.
  • Broad applicability -- The proposed VAAN format is available in almost any system and can be easily encoded, e.g. in smart contracts.
  • Error prevention -- VAANs are expected to be communicated between users in many different ways including error-prone channels such as email, in writing or verbally. The limited set of hex characters reduces the risk of confusion between similar characters along with the check digits.
  • Chosen length -- Given the importance of human-processing the VAAN should not be too long. The proposed length of 24 characters is similar to that of the International Bank Account Number (IBAN), while maintaining enough space for both the number of VASPs (4.3E9) as well as the number of VAANs per VASP (1.1E12).
  • Check digits -- The proposed CRC-8 algorithm is widely used. It is guarantueed to find all burst errors of length 8 (<=> single hex charachter) and has a Hemming Distance of 4 for the given message length.It only produces a single byte output that is strongly dependent on every byte of the input, also see https://en.wikipedia.org/wiki/Cyclic_redundancy_check.

Backwards Compatibility

The VAAN specification proposed in this OVIP is not backwards compatible.