This document defines the functions and request/response parameters of the interface between FinP2P-Core and FinP2P-Network.

FinP2P-Network is not aware of FinP2P-Core business logic or FinP2P-Application logic, but defines a set of interfaces that helps on the implementation of distributed FinP2P algorithms.

Table of Contents

Interface Message Formats

This section defines the messages contracts between FinP2P-Core and FinP2P-Network.

FinP2P core interacts with multiple modules and messages are transported from API to network to Distributed Ledger implementations.

Terminology

Definition of terms used in the spec

ClusterID

This ID identifies a “cluster” of FinP2P nodes. A shard is defined as a group of organizations sharing the same distributed ledger.

In the following diagram we have 2 clusters: Cluster_A and Cluster_B:

Organization 1, Organization 2 and Organization 3 belongs to Cluster_A, and Organization 3 and 4 belong to Cluster_B. In this example Organization_3 belong to more than one cluster.

ResourceID

A resource ID identifies the resource type and its location. For location we understand as the Organization responsible to manage the resource.

The resource ID resembles a URI/URL.

ResourceID format

<organization id>:<resource type>:<resource>

Asset Transaction Signature Template (ATST)

Not all the clusters participating in the FinP2P network implements the same Distributed Ledger Technology (DLT) to record asset transactions. Therefore, the transaction signature requirements for each are different and specified by the particular DTL in place.

When Org A wants to transact with an asset managed by Org B, Org A must send a signed transaction that conforms with Org B’s underlying DLT specification.
We define the Asset Transaction Signature Template to provide a signature scheme that Organizations not sharing the same cluster can create complaint signature and messages.

In general, a signature is applied to the hash of the message that we want to transmit. The message is a concatenation of several fields in a particular order, with or without delimiters between them.

ATST v0.1

For this preliminary version we require that the ATST includes ONLY fields and field types that can be provided by the signing organization internally. Further revisions may include more sophisticated implementation of ATST such as libraries to do the actual calculation, or API’s definition to retrieve message values from the executing Organization.

atst: {
  alg: {
    signature: "ecdsa",
    hash: "sha3-256"
  },
  fields:[
    nonce: {
      type: < nonce value type >
    },
    sender:{
      type: < id type>
    },
    recipient:{
      type: < id type >
    },
    quantity: {
      type: < value type >
    },
    asset: {
      type: < asset id type >
    }
  ]
}

Supported types:

Network interface

FinP2P-Core uses the network interface to send and receive messages from the network, broadcast queries and receive broadcast response, for Pub/Sub communication, discovery, advertising resource, etc.

The implementation of the underlying network technology is not aware of FinP2P-Core business logic. Messages are structure in a way that each layer understands a specific part of the message and only the final consumer can open and read the message payload.

With this “onion” like structure, each layer removes or consumes what it's important to it, forwarding the rest of the message to the next layers.

Send Message

With the send message interface, FinP2P-Core sends P2P and Broadcast messages through the FinP2P Network. The message delivery method can be specified during the API call, or may be guessed by the FinP2P-Network by looking at the envelope:to field.

Message Structure

request: {
  envelope: { ... }
  payload: { ... }
  signature: { ... }
}

Envelope

The envelope includes routing information.

envelope:{
  // request identifier
  requestid: < random generated id > // this ID is generated by the sender and 
                                     // returned by the responder.
                                     // It uniquely identify a request/response pair
  // routing
  from: < sender resource id >
  to: < recipient resource id > \\  optional on Broadcast messages
}

Payload

The payload of the message defines the function and parameters that will become the body of the task. The function is defined as the ‘task’ of the message. Different tasks requires different parameters encoded in the payload.

payload: {
  task: < Task identifier + Task Version >
  params: < Encoded pramaters relevant for this task >
}

The task is a combination of the task identifier and the version. To support multiple versions of the same task the version identifier is part of the field.

The params for a specific task are only relevant for the task itself. The structure is define by the task.

Signature

The signature field includes the cryptographic signature of the sender using its FinID private key.

The message to sign is defined as: sig_alg(hash(envelope, payload)). The result of the signature is then encoded in basexxx and added to the message.

signature: {
  algorithm: ecdsca-sha3_256
  signature: < signature bytes >
}

The algorithm filed is used to represent other signature and hash combinations. The default for this specification is: ECDSA and SHA3-256

Received Message

FinP2P-Core receives messages from the network through this interface. The messages structure is identical to the send message because it is actual a “send message”.

Flows and Interactions

FinP2P-Network execute basic flows validation before forwarding the message to FinP2P-Core:

1. Check if the current node is a valid destination.

2. Verify signature: To verify the signature, FinP2P-Network retrieves the FinID of the sender using its resource id from the envelope.

3. Parse Task and forward: The task is parsed and the message is processed by:

   1. FinP2P-Network: If the Task is a network task. Advertisement messages are usually consumed by the Network layer.

   2. FinP2P-Core: If the task is not recognized as a Network Task, the message is forwarded to FinP2P-Core for further process.

Response Message

Every message sent to the network, either P2P or Broadcast, eventually will produce a single response or multiple responses.

The response message has a common structure that is shared among all task, and a task custom section.

respose: {
  envelope:{}
  status:{}
  payload:{}
  signature:{}
}

Envelope

The envelope section is almost identical to the request envelope but the to and from are swapped. And in a broadcast request, the From is filled with the actual responder ID.

envelope:{
  // request identifier
  requestid: < random generated id >  // this ID is generated by the sender and 
                                      // returned by the responder.
                                      // It uniquely identify a request/response pair
  // routing
  from: < responder resource id >
  to: < sender resource id >
}

Status

The status object notifies the receiver about the outcome of the request. Status code and message may have special meaning per each task.

For this specification we define:

status: {
  code: < A status code representing success|warning|error >
  message: < message or sructure adding more information about the status code >
}

Payload

The payload is the response from the Organization taking the request. The payload format and structure is defined per task.

Signature

The signature section is the same as for the requestmessage, but in this case the signer is the Organization responding to the request.

signature: {
  algorithm: ecdsca-sha3_256
  signature: < signature bytes >
}

The receiver can verify if the signature is valid by verifying it with the FinID of the response sender. The FinID can be retrieved using the Sender’s ( From field ) resourceID as the index.

Note: During advertising, Each node advertise its resource ID and FinID ( see below Advertise)

Task specifications

Tasks are the function defined on the messages FinP2P-Network shares with other nodes.

A task can be defined as Peer-To-Peer or as a Broadcast message. Custom tasks, not defined by this specification, specifically define if P2P or Broadcast has to be used. This is also true for defined tasks that can be executed in both ways.

Following, the preliminary list of defined tasks:

Advertise

A node use this task to advertise to the network the Node capabilities, supported resources, new address, etc

Task Definition

Request Parameters

The advertisement packet includes multiple units that can be sent one by one or all in a single packet

Every advertisement packet has these common parameters

Common

{
TBD; // Common parameters to all advertisement messages
}

Identity

The identity and resource id of this node.

{
  cluster: [ // An array of clulster IDs. an Organization can belong to multiple clusters
    clusterid: < cluster id> // Cluster Identifier. Each Org belongs to a cluster 
                             // of Orgnaizations sharing a common undelying Ledger.
  ]
  resource: < resource id > // This is the resource ID of this organization / Node
  finid: {
    // Global FinP2P Identifier
  }
}

Address

Network Address/es of this Node.

{
  port: < listent port > // The default listen port
  hosts: [ // an array of hosts. A host is an IP:PORT 
    {
      scheme: <protocol: [UDP/TCP/QUIC/others]>
      address: ip address | name // Name is a DNS resolvable name
      port: listen port // Optional if default port is defined. 
                        // Mandatory if its differnt than the default port
    }
  ]
}

Resources

This is a list of resource identifiers this Node supports and share.

resources: [
  {
    resourceid: < resource URI >
  },
  {
    resourceid: < resource URI >
  }
]

Capabilities

The capability structure enumerate the supported capabilities of tis node.

capabilities: {
  finp2p_version: < supported finP2P_versions >,
  protocols:[ // supported protocols
  ],
  (TBD)
}

Get Resource

The Get Resource task is a request to read (Get) a resource data from a remote Node. The requested resource is identified in the params field.

Task Definition

Request Parameters

The parameters identify the resource this Node is requesting information for. Multiple resources can be requested from the same Organization. If an Organization receives a request to Get resource it does not manage, it ignores them returning only resource information it manages.

accept-types: [ // default for all resources
  <supported content type>,      
],
resources: [
  {
    accept-types: [ // specific for this resource
      <supported content type>,      
    ],
    < requested resource identifier + optional path >
  }
]

A user resource request in IVMS-101 format will look like:

accept-types:[
  "application/ivms-101"  // No standard yet
]
resources: [
  "orgid:100:userid_123456789"
]

The resource identifier can include a specific path to specify exactly the data portion of the resource required. For example, when requesting a specific document for an Asset the path should look similar to

orgid:assets:<asset id>[:docs:kya_version_xyz]

In the above case, [:docs:kya_version_xyz] is defined as the optional path for the resource.

Response Message

The response includes the requested data for each resource. If any of the requested resources cannot be retrieved, an error message is returned with a status code and status message

envelope:{ ... }
status:{ ... }
payload:{
  resources: [
    {
      response: {
        resource: < requested resource >
        status: < status code >
        error: { // if status code determine an error
          message: // error message
        },
        payload: { // Custom resource data if status code is not an error
        }
      }
    }
  ]
}
signature:{}

Verify Resource

To verify that a resource data received its authentic and current, an Organization can send a Broadcast request to verify a hash of the resource data. The hash of the data together with the resource ID is sent to the cluster for verification. the verification algorithm is not specified, but an Organization is expected to store a hash of the current resource data into its cluster underlying DLT.

Task Definition

Request Parameters

envelope {
  ...
  to: < cluster id> // Broadcast request to members of the cluster
}
... 
verify: {
  resourceid: < resource id to verify >
  hash: < hash resulting from aplying a hash function to the get resource payload response >
}

Response Message

The response is collected from all the members of the cluster.

envelope: { ... }
status: {
  // Error status are no considered as no match
}
payload: {
  resourceid: < as seen on the request >
  hash: < as seen on the request >
  match: < true | false > // The requested hash match the one store in the DLT for the resource id>
}
signature: { ... }

Asset Transactions

The Asset Task defines multiple subtask that can be performed to and asset. A Node may want to run a Transfer Transaction to sell or buy an asset, or query for the balance of one of its users.

Transfer transactions are delivered P2P and queries, like Balance, are Broadcasted to the nodes of a cluster.

Task Definition

The parameters are specified per asset subtask.

Transfer

Request Parameters

The Transfer parameters defines the transfer transaction and includes the senders signature. In order to sign a message that can be verified by the destination Ledger, a Asset Transaction Signature Template (ATST)is defined for each Asset. This template defines the cryptographic algorithms and the structure of the message to sign. The ATST is defined per Asset and is included when retrieving asset’s resource information.

// Transfer Parameters
transfer:{
  from: {
    id: < resource id of the sender >,
    finid: < finid of the sender >,
  }
  to: {
    id: < resorce id of the receiver >,
    finid: < finid of the receiver >
  }
  assetid: < asset id of the transaction >
  quantity: < quantity to transfer >
  
  signature:{
    alg: < signature algorithm based on ATST >
    payload: < payload of the signature >
  }
}

Response Message

envelope:{ ... }
status:{ ... }
payload:{
  txid: < Transaction identifier.> // This ID represents the 
                                   // Transfer Transaction on execution DLT
}
signature:{ ... }

Balance

In the balance subtask, the message is sent to all the known nodes of the cluster.

Request Parameters

// Send Message Envelope
envelope: {
  ...
  to: < clusterid > // The cluster ID where the asset is managed
}
// Balance Parameters
account:{ // acount to retrieve balance
  finid: < finid of the user requesting the balnce >
}
asset:{ // Asset identifier, from which the balance is requested
  id: < asset identifier >
}

Response Message

The response payload includes the user’s account and asset from the request and adds the balance quantity.

envelope:{ ... }
status:{ ... }
payload:{
  balance: <quantity>,
  account:{ // acount to retrieve balance
    finid: < finid of the user requesting the balnce >
  }
  asset:{ // Asset identifier, from which the balance is requested
    id: < asset identifier >
  }
}
signature:{ ... }