FinP2P Network

Owned by Yuval Carmel
Last updated: Jul 10, 2024 by Yuval Carmel
9 min read

This section describes the network protocol between FinP2P Routers, and the digital securities API calls that each Router must be able to generate and respond to.

Securities API calls

The specific API calls will be published in the coming weeks, the main API calls will cover:

  • Sending/Receiving transactions to be executed on the primary Router of an asset.

  • Sending/Receiving information about current token status, transactions, confirmations and hashes.

  • Sending/Receiving private information (about users or assets) as authorized by the ACLs.

If a Router is implementing the network protocol, and able to send/receive those APIs, they will be technically able to join the network.

Overview of FinP2P Network Protocol

The FinP2P Network interface abstracts the communication between multiple distributed FinP2P Routers by exposing a set of primitives and flow specifications.

FinP2P Network is layered on top of open source and widely used state of the art application protocols like HTTP/2, TLS 1.2 and 1.3, gRPC and distributed K/V storage systems. By building on top of those widely used and supported protocols, we gain a massive amount of community support and open-source project that can provide immediate enhancements to the FinP2P Network.

Governance

FinP2P is a decentralized network with a trusted Identity system. For this identity to be trusted by all members of the network, a governance function is defined.

The first Governance Routers will be the decided at the launch of the network (the Genesis), those Governance Routers will be referred to as the Founding Routers, and will be able to authorize both regular new Routers and also add new Governance Routers:

  • Every Router in the network has to be certified by one of the Governance Routers.

  • Every Governance Router has to be certified by one of the Founding Routers.

Governance Functions

  • Generate Organization Identities: The Governance Router is responsible to validate Organizations and generated their FinID ( FinP2P Global Identity )

  • Rendezvous Services: Governance Routers are located at well known addresses. New Organizations joining the network will contact those Routers for bootstrapping and join the FinP2P network

  • Trusted source of Peers: Governance Routers keep a registrar of Network members to answer to Discovery requests.

Other function will be added in the future.

Primitives

FinP2P is built on top of a set of extensible primitives:

Identity

Each profile in the network is identified by a unique ID called FinID. The network uses FinIDs to execute various actions across the platform.

For more information on identities, see FinP2P Data Model

The identity is generated when a new profile is created on the network. For organisations, the identity is generated by the Governance Router that adds them to the network. For all other profiles, the identity is generated by their Primary Router.

Advertisements and Discovery

FinP2P Routers use Advertising messages to notify the network about services and capabilities of the Router. Capabilities includes critical information such as:

  • Router Identity

  • Router Address

  • Supported Service

  • Version

 

Joining the FinP2P network

After receiving an Identity, participating Organizations join the network dynamically. 

The first step is to acquire information about other Routers in the network. The standard bootstrap is done communicating with the Rendezvous FinP2P Bootstrap Router. This Router has a well known IP Address / DNS Name and is distributed in several geo-locations.

This specification will define the mandatory steps for an organization to join the network.

The preliminary steps are:

Registration

At join time, the organization has to register its cluster to the FinP2P network. The registration is done by advertising the Organization Identity, Router Address and Capabilities.

 

Address

The Router address has to be a public resolvable DNS name, or a set of public IPs addresses. Advertising a private address will prevent other Routers from communicating with the Router.

Capabilities

The capabilities information lists supported FinP2P protocols and communication details.

This specification will list the set of mandatory and optional protocols an implementation has to support.

Advertisements

Each organization MUST advertise its capabilities and resources it wants to share. Failing to do so will prevent other organizations from communicating with it.

 

Capabilities

Capability advertisement is fundamental for FinP2P protocol. Any change of version, address and supported protocols must be announced to the network as soon as possible. FinP2P modules are well aware of most of the capabilities changes and this update can happen automatically.

An Organization MUST at least advertise the mandatory protocols supported by its Routers.

Resources

Each resource defined in the system has a resourceid attached to it. The resource ID is a unique identifier that aims to provide the exact location of the resource in the network.

The approach is to use a a standard URI/URL structure to define a resourceid. Using this approach,

For illustration, a resourceid would have the following sections:

  • Owner Organization: This is the organization that owns and manage the resource. We can see the org section as the “host” in an http URL. FinP2P-Network maintain a mapping cache between organizations and their routable IP addresses.

  • Resource Type: The resource type is defined as multiple namespaces to allow for custom types but avoiding coalitions. The default namespace will define the resource type in this specification and must be implemented by all vendors.

  • Resource identifier: This is the actual identifier specific to the resource type domain.

Other sections may be added when the spec is finalized.

Therefore, defining a resourceid as a URL establish the routing path for the resource in the network.

A resource ID is advertised by an Organization Router if it is willing to share the resource data with others. The advertisement package will be defined in this specification. The following structure is a preliminary draft of what the event should contain:

{     Advertisement: { // Defines the Payload of the event “resourceid”: < resource identifier base on namespace and defined sheme>, “topic”: < The topic is provided if the Organization supports the Pub/Sub mechanism for this resource”    },     Identity: { // Organization Identity and signature    } }

The specification recommends that resource visibility be controlled by the Privacy Layer ACL. By allowing access to the resource data to Organizations that can present a known Identity. Other means of validation can also be implemented but are out of the scope of this specification and may not work between all organizations in the network.

This specification will enumerate a list of supported resources identifiers. Different namespaces will be defined to avoid collision for self defined resources.

An example of a resource is an Asset managed by an Organization:

 

Managed Assets

Assets managed by an organization are resources that an organization can share with others.

When an Organization wants to share the assets it announces a new resource with the assets information.

This announcement can be sent to all the participating Routers, or to a controlled set.

The organization can opt to use the provided FinP2P Pub/Sub mechanism to keep allowed organizations up to date with resource changes.

With the resource ID, allowed Organizations can send direct ( P2P ) requests to get the resources up to date information.

Advertise / Subscribe / Publish Flow

 

Subscribe to Topic
Publish Topic Data

P2P and Broadcast requests

Organization Routers rely on the FinP2P API to communicate with the network. Internlay, the FInP2P abstractions translate the API to network requests.

This specification defines 2 types of requests: Peer-to-peer and Broadcast requests.

Peer-to-peer Requests

The most common case of a P2P communication is when a request has to be executed by a specific Organization. 

Some of the uses cases of P2P requests are:

Asset Transaction

One of the flows for P2P is when Organization A wants to transact with assets managed by Organization B. In this case Org A MUST directly contact the Primary Router of Organization B. Using the data collected from the Discovery protocol and the Assets advertised by Org B, the FinP2P layer has all the information to send the asset transaction request to the Primary Router Address of Org B.

A Transaction relating to an asset is always routed to the primary Router of the asset, regardless of the primary Router of the buyer and the primary Router of the asset are on the same Distributed Ledger or not.

The following diagram illustrates a high level flow of a transfer request:

Asset Transaction Receipt

The Asset Transfer response is a signed notification from the Asset Manager Primary Router that the request was fulfilled. The signed Response payload includes all the details of the asset transaction and metadata related to the Recorded Distributed Ledger Transaction.
This information is then recorded on Organization A Distributed Ledger to keep records of Asset Transaction receipts. The receipt can be verified at any time by the holder.

Private Data Queries

On this P2P flow, an Organization A is requesting access to Organization’s B Private Data using an advertised resource ID.

Any Organization can request data from any other Organization. The result of the request will be bound to the ACL implementation of the resource owner.

FinP2P maintains a caching copy of ACL information to prevent DDOS from non allowed organizations. Any change in the ACL will be broadcasted to the interested parties.

 

Private Data Query Flow: User information during asset transfer

Implementation: The following User data messaging specification is considered for implementing User data sharing in FinP2P

In this Flow, Organization A is requested to execute an asset transfer from two of its users OrgA-user-1 to OrgA-user-2. The asset is managed by Organization B, so FinP2P automatically relays the transfer request to Org B Primary Router ( see Asset Transaction for flow).

During the transfer flow, Org B has to get access to the seller and buyer to validate the transaction with the regulations assigned to the asset. At this time, if no information about OrgA-user-1 and OrgA-user-2 is available for Org B, it sends a P2P Private Data Request to Org A with the user’s IDs. If Org B is “allowed” to get this type of information, Org A response includes the requested information for Org B to continue the Transfer request.

 

Broadcast Request

A broadcast request is sent to the network when multiple Routers can fulfill the request. Broadcast requests can be sent to the global network, to a specific group of Routers or to a specific group of Primary Routers sharing the same underlying Distributed Ledger.

The request specifies how many responses to wait before getting back to the caller. Responses are collected, validated and compared for consistency. Options can be set to solve inconsistency with responses with an out of date Distributed Ledger version or to recognize failures.

The rendezvous Router is also part of the response set bringing an independent value to solve inconsistency.

The specification defines multiple request formats to answer different privacy needs. Some of the forms may look like:

  • Send to closest Routers for propagation. 

  • Send to a selected group of Routers

  • Send only to Routers connected to a specific Distributed Ledger

  • Send to Rendezvous cluster for further propagation

The payload of the request is signed by the sender's Identity and it may also be encrypted to prevent forwarding Routers to get access to sensitive information.

User Balance Broadcast Request

Scenario: Organization A has two users; orga:user:1 and orga:user:2. Those users are owners of assets managed by other organizations and Distributed Ledgers. In order to get a current asset balance for those users, a broadcast message is sent to the Primary Routers of the Distributed Ledger where the asset is managed.

The broadcast request is signed by Organization A Primary Router and is sent to all primary Routers of the same Distributed Ledger. The request includes details of the user and the asset.

 

Receipt validation Broadcast Request

An organization holding an asset transfer receipt can verify its validity by broadcasting the receipt metadata. Any Router with access to the Distributed Ledger can verify the metadata transaction and respond.