RFC-002-SWAP.adoc

SWAP message

Table of Contents

• 1. Description
• 2. Content
  • 2.1. Terminology
  • 2.2. Messages
  • 2.3. Examples
• 3. Registry extensions
  • 3.1. The type Ledger
  • 3.2. The type Asset
  • 3.3. The type SwapProtocol
  • 3.4. The type DeclineBody and the initial set of possible values

Note	RFC-Number: 002 Status: Draft + Created on: 2018-12-28

1. Description

This RFC serves two purposes:

1. Introduce terminology used to describe the exchange of assets.

2. Define a REQUEST/RESPONSE message pair for two parties to negotiate such an exchange via the COMIT messaging protocol.

2. Content

2.1. Terminology

To describe the elements of an exchange, we use the terms Ledger, Asset, Alpha and Beta.

2.1.1. Ledger

A ledger is anything that records ownership and allows transferal of that ownership.

2.1.2. Asset

An asset is anything whose ownership can be transferred on a [ledger](#ledger).

2.1.3. Alpha and Beta

The terms alpha and beta are used to unambiguously identify assets and ledgers in an exchange. Such an exchange can thus be described as:

• Transferring the ownership of the alpha-asset on the alpha-ledger from party A to party B.

• Transferring the ownership of the beta-asset on the beta-ledger from party B to party A.

This terminology has several advantages:

1. It does not imply an order (compared to a terminology like first/second).

2. It is not subjective to any of the parties (compared to terminology like source/target, incoming/outgoing or local/remote).

2.2. Messages

The messages to negotiate such an exchange consist of a REQUEST frame and a corresponding RESPONSE frame.

2.2.1. SWAP REQUEST frame

2.2.1.1. Definition

A SWAP REQUEST message is a FRAME of type REQUEST. As per definition in RFC001, a REQUEST FRAME has a type that defines its semantics. For the SWAP REQUEST message, this type is SWAP.

2.2.1.2. Headers

To express all the information for an exchange, a SWAP REQUEST MUST include the following headers:

Table 1. Valid headers with a SWAP request

Header	Value (Link to registry section)	Description
alpha_ledger	Ledger	The ledger the alpha-asset is tracked on.
beta_ledger	Ledger	The ledger the beta-asset is tracked on.
alpha_asset	Asset	The asset whose ownership will be transferred on the alpha_ledger.
beta_asset	Asset	The asset whose ownership will be transferred on the beta_ledger.
protocol	SWAP Protocol	The protocol that is used to transfer the ownership of the assets.

This RFC only defines these headers. The actual definition of ledgers, assets and protocols is not subject to this RFC.

2.2.1.3. Body

The body of a SWAP REQUEST depends on the chosen protocol. It is therefore subject to RFCs which define such protocols to also define which information is contained in the body of a SWAP REQUEST/RESPONSE frame.

2.2.2. SWAP RESPONSE frame

2.2.2.1. Definition

A frame of type REQUEST implies a RESPONSE. We will refer to the response of a SWAP REQUEST as SWAP RESPONSE.

A SWAP RESPONSE contains the decision made by the other peer.

2.2.2.2. Headers

The response MUST contain the decision header.

The decision header is defined as follows:

• value: accepted OR declined.

• parameters: None

2.2.2.3. Body

The content of the body depends on the values of the headers. The following diagram illustrates the process:

The DeclineBody is an object with two properties:

• reason: An identifying string that briefly describes why the request was declined.

• details: An object containing further, relevant details. The object-shape depends on the given reason.

See the Registry extensions-section for examples of a DeclineBody.

2.3. Examples

This section contains examples of SWAP REQUEST/RESPONSE frames. Elements not relevant for this RFC or which are subject to later definition are filled in with "…​".

2.3.1. SWAP REQUEST frame

{
  "type": "REQUEST",
  "id": 0,
  "payload": {
    "type": "SWAP",
    "headers": {
      "alpha_ledger": {
        "value": "...",
        "parameters": { ... }
      },
      "beta_ledger": {
        "value": "...",
        "parameters": { ... }
      },
      "alpha_asset": {
        "value": "...",
        "parameters": { ... }
      },
      "beta_asset": {
        "value": "...",
        "parameters": { ... }
      },
      "protocol": "...",
    },
    "body": { ... },
  }
}

2.3.2. SWAP RESPONSE frame

2.3.2.1. Accepted SWAP REQUEST

{
  "type": "RESPONSE",
  "id": 0,
  "payload": {
    "headers": {
      "decision": "accepted"
    },
    "body": { ... },
  }
}

2.3.2.2. Declined SWAP REQUEST

{
  "type": "RESPONSE",
  "id": 0,
  "payload": {
    "headers": {
      "decision": "declined"
    },
    "body": { ... },
  }
}

3. Registry extensions

This RFC extends the registry with the following elements:

3.1. The type Ledger

A section "Ledgers" is added to the registry which tracks all currently defined ledger types. Subsequent RFCs can refer to this type if they want to define a particular ledger.

3.2. The type Asset

A section "Assets" is added to the registry which tracks all currently defined asset types. Subsequent RFCs can refer to this type if they want to define a particular asset.

3.3. The type SwapProtocol

A section "SWAP Protocols" is added to the registry which tracks all currently defined protocols. Subsequent RFCs can refer to this type if they want to define a particular swap protocol.

3.4. The type DeclineBody and the initial set of possible values

A section "DeclineBody" is added to the registry which tracks all currently defined reasons. Subsequent RFCs can refer to this type if they want to define new reasons for declining SWAP REQUESTs.

The following DeclineBody`s are added to the list. Each heading represents a `reason.

3.4.1. unsatisfactory-rate

The rate of alpha_asset to beta_asset is not satisfactory to the receiver.

3.4.2. unsupported-protocol

The protocol specified in the protocol header is not known to the receiving party.

3.4.3. unsupported-swap

The ledger-asset combination specified in the SWAP request is not supported by the receiving party.

This can mean that: 1. The ledger is unknown 2. The asset is unknown 3. Ledger and asset are unknown

This error can be extended to a more complex unknown-asset and unknown-ledger in the future. The error cases for these variants have to be properly defined first.

3.4.4. missing-mandatory-header

A mandatory header expected by the receiving party is not properly specified by the sending party.

3.4.5. bad-json-field

The receiving party cannot properly deserialize the json header or body because of a bad json-field (e.g. a field that is not part of the specification or a wrongly typed field value).