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
- 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.1.1 FinID Token
- 1.2 Network interface
- 1.2.1 Request Message Structure
- 1.2.1.1 Request Message Structure proto3
- 1.2.2 Response Message Structure
- 1.2.3 Accounts
- 1.2.1 Request Message Structure
- 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
- 1.3.1.1 Request Message
- 1.3.1 Advertise Service
- 1.1 Terminology
Interface Message Format
The protobuf3 messages defined in this section are the building blocks of the inter FinP2P Router communication.
Terminology
Definition of terms used in the spec
FinID Token
The FinID token is a JWT generated by a Governance Router. It provides proof that the owner Router identity was verified and certified by the Governance Router.
The Token includes critical Router information that is used and validated during FinP2P protocol. This information is signed by the Governance Router.
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 Router 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 Router.
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 Routers. 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 |
---|---|---|
organization id | The identifier of the organization responsible to manage the resource | An OrgID has always a prefix of ORG:<id>, |
resource type | The type of the resource. Resource type is specified with an ID. The specification reserves the following IDs range:
In this specification we define:
| 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 |
---|---|---|
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 Routers 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 |
---|---|---|
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 request
message, 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 Router 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 Routers.
Following FinP2P Services for detailed description about the network functional services.
Advertise Service
A Router use this task to advertise to the network the Router capabilities, supported resources, new address, etc
The Advertise message has always the Rendezvous
cluster as destination. Other FinP2P Routers 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 Router can send this packet to update its information.
Every advertisement message includes the Organization FinID Token:
Common
Address
Network Address of this Router.
Resources
A FinP2P Router 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 Router.
Â