...
<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
...
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.
Code Block |
---|
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:
Types | Format | Samples |
---|---|---|
String | UTF-8, UTF-16 |
Numbers
int8, int16, … int256
unit8, uint16 … uint256
float32, float64
Date
RFC339, ISO 8601
Rand
A random value
UID
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.
...
Code Block |
---|
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:
Code | Description | Notes |
---|---|---|
0 | The request was handled successfully | |
1-999 | An error has occurred. | See task for error descriptions |
Code Block |
---|
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 } |
...
Code Block |
---|
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.
Code Block |
---|
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.
Code Block |
---|
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
Code Block |
---|
message FinIDToken {
bytes token = 1; // Serialized FinID JWT
} |
Address
Network Address of this Node.
Code Block |
---|
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.
Code Block |
---|
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.
Code Block |
---|
message Capability {
Version finp2pVersion = 1;
(TBD)
} |
Resource Service
This service groups the requests associated with remote Resource access and verification.
Code Block |
---|
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.
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
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.
Code Block |
---|
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
Code Block |
---|
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.
Code Block |
---|
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.
Code Block |
---|
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.
Code Block |
---|
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;
}
}
|
Code Block |
---|
message Investor {
ResourceID resource = 1;
FinID finID = 2;
} |
Code Block |
---|
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
} |
Code Block |
---|
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
Code Block |
---|
message SignedTransferResponse {
common.Envelope envelope = 1;
common.Signature signature = 2;
oneof payload {
Acknowledgement ack = 10;
TransferResponse transferResponse = 11;
}
} |
Code Block |
---|
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
Code Block |
---|
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.
Code Block |
---|
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.
Code Block |
---|
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
Code Block |
---|
message FinIDToken {
bytes token = 1; // Serialized FinID JWT
} |
Address
Network Address of this Node.
Code Block |
---|
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.
Code Block |
---|
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.
Code Block |
---|
message Capability { uint64Version ammountfinp2pVersion = 21; // Balance(TBD) } |