This document defines the interfaces exposed by FinP2P-Network. The interface is implemented as a set of gRPC services with the respective protobuf3 messages.

Implementation of FinP2P Network MUST comply with this specification and supports ALL the mandatory services and functions.

These interfaces are designed to create an abstraction layer between FinP2P Network and FinP2P Core.

1 Interface Message Format
- 1.1 Terminology
  - 1.1.1 FinID Token
    - 1.1.1.1 Token Claims
  - 1.1.2 ClusterID
  - 1.1.3 ResourceID
    - 1.1.3.1 ResourceID format
    - 1.1.3.2 ResourceID Proto3 Representation
  - 1.1.4 Asset Transaction Signature Template (ATST)
    - 1.1.4.1 ATST v0.1
- 1.2 Network interface
  - 1.2.1 Request Message Structure
    - 1.2.1.1 Request Message Structure proto3
      - 1.2.1.1.1 Envelope
      - 1.2.1.1.2 Payload
      - 1.2.1.1.3 Signature
  - 1.2.2 Response Message Structure
    - 1.2.2.1 Envelope
    - 1.2.2.2 Status
    - 1.2.2.3 Payload
    - 1.2.2.4 Signature
  - 1.2.3 Accounts
- 1.3 Service specifications
  - 1.3.1 Advertise Service
    - 1.3.1.1 Request Message
      - 1.3.1.1.1 Common
      - 1.3.1.1.2 Address
      - 1.3.1.1.3 Resources
      - 1.3.1.1.4 Capabilities

Interface Message Format

The protobuf3 messages defined in this section are the building blocks of the inter FinP2P node communication.

Terminology

Definition of terms used in the spec

FinID Token

The FinID token is a JWT generated by a Governance node. It provides proof that the owner Node identity was verified and certified by the Governance node.

The Token includes critical Node information that is used and validated during FinP2P protocol. This information is signed by the Governance node.

Token Claims

As part of the claims, this token includes:

Cluster ID. the cluster ID for this Organization ID. And Organization can belong to different cluster. For each cluster, an organization registers a different, system wide unique, Org ID.
Organization Public FinID. By adding the Organization FinID, we can always verify that the Node presenting the FinID Token is in fact the real owner of the token by verifying signatures.
Organization Information details: Name, email address, etc.

The JWT token must be signed by a Governance Node.

header:{
  "alg": "ES256",
  "kid": < Id of the key used to sing this token >,
  "typ": "JWT"
},
payload:{
  // JWT Claims
  "iss": < Governance issuer >,
  // OrgID alwasy start witht he prefix "ORG:"
  "sub": < Org Resource ID >,
  "aud":["randezvous", < others >],
  "iat": < time this token was generated >
  "exp": < Expiration Time for this FinID Token >,
  "jti": < FinID Token Unique Identifier >
  
  // FinID Token Claims
  // ClusterID always starts with the prefix "CLR:"
  "clusterid": < Cluster ID for this Org ID >,
  "finid":{
  },
  "orginfo":{
    "createdAt": < time this organization was created >
    "name": < Organization Name >,
    "email": < Organization Admin email address>,
    <other info>
  }
}

ClusterID

This ID identifies a Cluster of FinP2P nodes. A Cluster 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.

The cluster ID has a prefix of CLR:<id>, i.e.: CLR:MyCluster1234

ResourceID

A resource ID identifies the resource type and its location. The location of a resource is defined as the location of the Organization managing that resource.

The hierarchy of a resource ID resembles a URI/URL to the exact location of the desired resource.

ResourceID format

Field	Description	Notes

Field

Description

Notes

organization id

The identifier of the organization responsible to manage the resource

An OrgID has always a prefix of ORG:<id>,
i.e. ORG:MyOrgID

resource type

The type of the resource. Resource type is specified with an ID. The specification reserves the following IDs range:

0-99: unused
100-999: reserved for FinP2P
1000- : Undefined

In this specification we define:

101: user. A resource identifying a user of the system
102: asset. A resource identifying an asset.

If an Implementation wants to specify a resource not defined in this specification it must use the undefined range. Undefined range is not part of the specification but it may be monitored to avoid overlapping.

id

The id field is the internal identification of the resource. Organizations may have different methods to identify their resource.

ResourceID Proto3 Representation

message ResourceID {
  string orgID = 1; // orgid always start with the prefix "ORG:"
  enum ResourceType {
    reserved 0 to 99;
    USER = 101;
    ASSET = 102;
    ESCROW_ACCOUNT = 103;
    SETTLEMENT_ASSET = 104;
    ASSET_TRANSACTION_INTENT = 105;
    reserved 106 to 999;
  }
  ResourceType type = 2;
  bytes resource = 3;
}

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.

message SignatureTemplate {
    repeated HashGroup hashGroups = 1;
    bytes hash = 2; // combined hash value of all hash groups
}

message HashGroup {
    bytes hash = 1;
    repeated HashField fields = 2;
}

message HashField {
    string name = 1;
    enum Type {
        UNKNOWN = 0;
        STRING  = 1;
        INT  = 2;
        BYTES  = 3;
    }
    Type type = 2;
    bytes value = 3;
}

Supported types:

Types	Format	Samples

Types	Format	Samples
String	UTF-8, UTF-16
INT	int64
UID	byte

Network interface

This specification defines 2 logical layers that interacts with each other. The first Layer is FinP2P-Core where al the Business logic is implemented and services defined. the second Layer is FinP2P-Netowrk. this network layer is actually the layer that implements the gRPC protocol as specified in this document.

Different implementation can define the interface between those layers in several ways. With this specification we do not mandate any particular interface between the layer. The only requirements is to support the gRPC services with he defined messages

Request Message Structure

The Request Message Structure defines the type of fields an gRPS request expects as input.

Request Message Structure proto3

If the services requires a signed Message a signed request is created:

Envelope

The envelope includes routing information.

Note on the To field:

On broadcast requests to the same cluster, the cluster ID must be specified. This will provide the FinP2P-Network a hint about the group of nodes to be addressed.

The Balance task shows an example

Payload

The payload of the message is defined by each service.

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 is stored in the payload field as a byte array.

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

Response Message Structure

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.

If the Response has to be signed a signed message is created:

Envelope

The envelope section is 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.

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:

Code	Description	Notes

Code	Description	Notes
0	The request was handled successfully
1-999	An error has occurred.	See task for error descriptions

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.

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)

Accounts

Accounts are a way to represent various Accounts and Asset types which may be available on the FinP2P network (e.g. FinID account, Escrow account, FinP2P Asset) or may be available outside of the FinP2P network (e.g Fiat asset, Cryptocurrency assets, crypto wallet account), those models are used as part of the intent definition and execution to indicate which asset are expected to participate in the operation and where those asset are located.

Service specifications

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

Following https://finp2p.atlassian.net/wiki/spaces/FINP2P/pages/1043628037 for detailed description about the network functional services.

Advertise Service

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

The Advertise message has always the Rendezvous cluster as destination. Other FinP2P nodes may also be targeted.

Request Message

The advertisement packet includes multiple units that can be sent one by one or all in a single packet. The only required field is the Identity field.

At any time a FinP2P Node can send this packet to update its information.

Every advertisement message includes the Organization FinID Token:

Common

Address

Network Address of this Node.

Resources

A FinP2P Node advertise its resources with an initial ACL list. This ACL list is used to protect the visibility of the resources and allow only Organizations on the ACL to be able to read.

Capabilities

The capability structure enumerate the supported capabilities of this node.

FinP2P

FinP2P Network Interface Specification

Table of Contents

Interface Message Format

Terminology

FinID Token

Token Claims

ClusterID

ResourceID

ResourceID format

ResourceID Proto3 Representation

Asset Transaction Signature Template (ATST)

ATST v0.1

Network interface

Request Message Structure

Request Message Structure proto3

Envelope

Payload

Signature

Response Message Structure

Envelope

Status

Payload

Signature

Accounts

Service specifications

Advertise Service

Request Message

Common

Address

Resources

Capabilities