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.

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>

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.

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

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

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:

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.

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
}

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.

message Signature {
  Algorithm alg =1;
  bytes payload =2;
}

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.

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:

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.

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:

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.

message Signature {
  Algorithm alg =1;
  byte payload =2;
}

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)

Service specifications

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

A task can be defined as Peer-To-Peer, Broadcast or Subscribe/Publish message. Some tasks can be invoked in multiple ways: P2P and Subscribe/Publish. A client can verify the exact methods supported by the Nodes using Discovery mechanisms.

Following, the preliminary list of 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.

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.

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

message FinIDToken {
  bytes token = 1; // Serialized FinID JWT
}

Address

Network Address of this Node.

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.

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.

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

Resource Service

This service groups the requests associated with remote Resource access and verification.

service ResourceService {
  rpc Get(SignedGetRequest) returns (SignedGetResponse) {}
  rpc Push(SignedPushResourceRequest) returns (SignedPushResourceResponse) {}
  rpc Verify(SignedVerifyRequest) return (SignedVerifyResponse) {}
}

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.

Request Message

The message 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.

message GetRequest {
  Envelope envelope = 1;
  repeated GetRequestPayload payload = 2;
}
message GetRequestPayload {
  ResourceID resource = 1;
  string type = 2; // Supported content-type. A Hint to the Resource owner.
}

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

message GetResponse {
  Envelope envelope = 1;
  Status status =2;
  repeated GetResponsePayload payload = 3;
}
message GetResponsePayload {
  ResosurceID resource = 1;
  unit32 code = 2;   // status code for this specific resource id
  string message = 3; // Status message if relevant
  string type = 4; // Content-Type for the resource payload.
  bytes payload = 5; // Resource payload if request was successful
}

Push Resource

An Organization can Push resources updates to other Organizations. This is an another method which the Organization can use to distribute its resources information.

Request Message

The message includes the resource ID and resource payload in the default content-type

message PushResourceRequest {
  Envelope envelope = 1;
  repeated PushResourceRequestPayload payload = 2;
}
message PushResourceRequestPayload {
  ResourceID resource = 1;
  string type = 2; // Resource payload default content-type
  bytes payload = 3; // Resource payload
}

Response Message

The response code reflects if the recipient got the Resource Payload or if there was an error.

message PushResourceResponse {
  Envelope envelope = 1;
  Status status =2;
}

Verify Resource

To verify that a resource data received its authentic and current, an Organization can send a Broadcast request to receive the current hash of resource ID. The sender will then verify the received hashes from the responders with its own calculated hash. 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.

Request Message

message VerifyRequest {
  Envelope envelope = 1; // target the cluster
  VerifyRequestPayload = 2;
}
message VerifyRequestPayload {
  ResourceID resource = 1;
}

Response Message

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

mesage VerifyResponse {
  Envelope envelope = 1;
  Status status = 2;
  VerifyResponsePayload = 3;
}
message VerifyResponsePayload {
  ResourceID resource = 1;
  bytes hash = 2; // the hash viewd by other members of the cluster
}

Asset Service

The Asset Service defines an asset transaction service and a balance request.

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

service AssetService {
  rpc Transfer(SignedTransferRequest) returns (stream SignedTransferResponse) {}
  rpc Balance(SignedBalanceRequest) returns (SignedBalanceResponse) {}
}

Asset Transfer Message

The Transfer message defines the transfer transaction and includes the senders signature. In order to sign a message that can be verified by the destination Ledger, an 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.

message SignedTransferRequest {
  Envelope envelope = 1;
  Signature signature = 2;
  TransferRequest payload = 3;
}

message TransferRequest {
  enum Operation {
    UNKNOWN = 0;
    ISSUE = 1;
    TRANSFER = 2;
    REDEEM = 3;
  }
  Operation operation = 1;
  TransferRequestPayload payload = 2;
  oneof condition {
    SignedEscrowPayload escrow = 10;
  }
}

  message Investor {
    ResourceID resource = 1;
    FinID finID = 2;
  }

message TransferRequestPayload {
  Investor buyer = 1;
  Investor seller = 2;
  ResourceID asset = 3;
  uint64 amount = 4;
  bytes data = 5; // Arbitrary data
  bytes signature = 6; // Based on ATST
}

message EscrowPayload {
  google.protobuf.Timestamp timestamp = 1; // Time in the future when this
  // transaction is no longer valid.
}

message SignedEscrowPayload {
  EscrowPayload payload = 1;
  common.Signature signature = 2;
}

Response Message

An asset transaction may have multiple messages. We will define a set of messages that can be received from the Primary Node running the transaction

message SignedTransferResponse {
  common.Envelope envelope = 1;
  common.Signature signature = 2;
  oneof payload {
    Acknowledgement ack = 10;
    TransferResponse transferResponse = 11;
  }
}

message Acknowledgement {
  string cid = 1; // correlation id for the response stream
}

message TransferResponse {
  bytes nonce = 1;
  string txid = 2;      // the transaction id
  uint32 code = 3;      // represents the outcome of the Tx
  string message = 4;   // Printable status message
  bytes chainpoint = 5; // If the Tx was succesful, this field holds the ChainPoint where the transaction was recorded
  Receipt receipt = 6;
}
message Receipt {
  string transactionId = 1;
  string assetId = 2;
  string recipientPublicKey = 3;
  string sourcePublicKey = 4;
  string quantity = 5;
  string settlementRef = 6;
  TransactionDetails transactionDetails = 7;
  int64 timestamp = 8;
  string intentId = 9;
}

message TransactionDetails {

  message Inputs {
    string transactionId = 1;
    string quantity = 2;
    uint32 index = 3;
  }

  message Outputs {
    string quantity = 1;
    string publicKey = 2;
    uint32 index = 3;
  }
  repeated Inputs inputs = 1;
  repeated Outputs outputs = 2;
}

Balance

In the balance request is broadcast to the members of the cluster.

Request message

message BalanceRequest {
  Envelope envelope = 1; // To fields is set to clusterID
  BalanceRequestPayload = 2;
}
message BalanceRequestPayload {
  FinID finid = 1; // owner of the account
  ResourceID asset = 2;
}

Response Message

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

message BalanceResponse {
  Envelope envelope = 1;
  Status status = 2;
  BalanceResponsePayload payload = 3;
}
message BalanceResponsePayload {
  FinID finID = 1; // Account Owner
  ResourceID asset = 2; // the requested asset
  uint64 ammount = 2; // Balance
}