FinP2P Network Interface Specification

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.

Table of Contents

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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 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

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

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 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

1 2 3 4 message <Request> { // The actual message name is defined per service Envelope envelope = 1; <PayloadRequest> payload = 2; // Each service defines its request payload }

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

1 2 3 4 message <SignedRequest> { // The actual message name is defined per service Request request =1; // Original plain request Signature signature = 2; // The signature }
Envelope

The envelope includes routing information.

1 2 3 4 5 6 7 8 9 10 11 message Envelope { // request identifier string requestid = 1; //< random generated id > // this ID is generated by the sender and // returned by the responder. // It uniquely identify a request/response pair // routing string from = 2; // < sender Org id > string to = 3; // < recipient Org id / Cluster ID > // optional on Broadcast messages }

 

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.

1 2 3 4 5 6 7 8 message Signature { Algorithm alg = 1; bytes payload = 3; } message Algorithm { string type = 1; }

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.

1 2 3 4 5 message <Respose> { // The actual message name is defined per service Envelope envelope = 1; Status status = 2; <PayloadResponse> payload = 3; // Each service defines the response payload }

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

1 2 3 4 message <SignedResponse> { // The actual message name is defined per service Response response = 1; Signature signature = 2; }

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.

1 2 3 4 5 6 7 8 9 10 message Envelope { // request identifier string requestid = 1; // Copy from request message // this ID is generated by the sender and // returned by the responder. // It uniquely identify a request/response pair // routing string from = 2; // The actual responder ( if the message was sent to ) string to = 3; // This is the "from" from the request }

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

1 2 3 4 message Status: { uint32 code = 1; // A status code representing success|warning|error string message = 2; // 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.

1 2 3 4 5 6 7 8 message Signature { Algorithm alg = 1; bytes payload = 3; } message Algorithm { string type = 1; }

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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 message Asset { enum Type { Unknown = 0; FinP2PAsset = 1; Fiat = 2; Cryptocurrency = 3; } string code = 1; // code uniquely identifying the asset (e.g ISO-4217 for Fiat type, ResourceID for FinP2PAsset etc..) Type assetType = 2; } // Account is composed of an asset which is backed by in the account // and account unique identifier for that type of account message Account { Asset asset = 1; AccountIdentifier identifier = 2; } message AccountIdentifier { oneof identifier { CryptocurrencyWallet wallet = 1; Iban account = 2; common.FinID finId = 3; Escrow escrowAccount = 4; } } message CryptocurrencyWallet { bytes address = 1; } message Iban { string code = 1; } message Escrow { common.ResourceID escrowAccount = 1; }

 

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.

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.

1 2 3 service AdvertiseService { rpc Advertise(SignedAdvertiseRequest) returns (SignedAdvertiseResponse) {} }

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.

1 2 3 4 5 6 7 8 9 10 message AdvertisementRequest { Enveloper envelope = 1; AdvertisementPayload payload = 2; } message AdvertisementPayload { FinIDToken token= 1; // Required repeated Address address = 2; repeated Resources resources = 3; repeated Capability capability = 4; }

Every advertisement message includes the Organization FinID Token:

Common
1 2 3 message FinIDToken { bytes token = 1; // Serialized FinID JWT }
Address

Network Address of this Node.

1 2 3 4 message Address { string address = 1; // ip address | name // Name is a DNS resolvable name uint32 port = 2; // listen port }
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.

1 2 3 4 5 6 7 8 message ACL { repeated ResourceID resources = 1; // List of Org ID that can access a resource. } message Resource { ACL acl = 1 RecourceID resource = 2; // Advertised resource. }
Capabilities

The capability structure enumerate the supported capabilities of this node.

1 2 3 4 message Capability { Version finp2pVersion = 1; (TBD) }