Page Comparison

...

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

ResourceID Proto3 Representation

...

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:message SignatureTemplate {
  alg: { repeated HashGroup hashGroups = signature: "ecdsa",1;
    bytes hash: "sha3-256"
  },
  fields:[
    nonce: = 2; // combined hash value of all hash groups
}

message HashGroup {
    bytes  type: < nonce value type >
    },
    sender:hash = 1;
    repeated HashField fields = 2;
}

message HashField {
    string name type:= <1;
id type>   enum Type },{
    recipient:{    UNKNOWN = 0;
type: < id type >    STRING }, = 1;
  quantity: {     INT  type:= <2;
value type >     }, BYTES  = 3;
asset: {   }
   type: <Type assettype id= type2;
>    bytes }value =  ]3;
}

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.

...

message Signature {
    Algorithm alg = 1;
    bytes payload =2 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

...

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
}

...

message Signature {
    Algorithm alg = 1;
  byte  bytes payload =2 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

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.

...

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.

message Asset {
    enum Type {
        Unknown = 0;
        FinP2PAsset = 1;
  AdvertisementPayload payload      Fiat = 2;
}   message AdvertisementPayload {   FinIDTokenCryptocurrency token= 13;
// Required   repeated}
Address address    string code = 21; // code repeateduniquely identifying Resourcesthe 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 envelopeasset (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 FinP2P Services 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.

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; // Toip fieldsaddress is| setname to// clusterIDName is a BalanceRequestPayloadDNS =resolvable 2;name
} message BalanceRequestPayloaduint32 {
  FinID finid port = 12; // owner of the account
  ResourceID asset = 2;listen port
}

Response Message

...

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 BalanceResponseACL {
  Enveloperepeated ResourceID enveloperesources = 1; // List Status status = 2;
  BalanceResponsePayload payload = 3;of Org ID that can access a resource.
}

message BalanceResponsePayloadResource {
  FinIDACL finIDacl = 1;
// Account OwnerRecourceID   ResourceIDresource asset = 2; // Advertised resource.
}

Capabilities

The capability structure enumerate the

...

supported capabilities of this node.

message Capability {
  uint64Version ammountfinp2pVersion = 21;
 // Balance(TBD)
}