API Reference

Ledger Proofs

Introduction

The FinP2P network enables secure, decentralized financial transactions across disparate ledgers. Central to this is the Execution Plan (EP), a mechanism for orchestrating multi-step operations. This document details additional capabilities in the EP trust model for allowing ledger adapters to provide proofs of execution of EP instructions.

Ledger Operation Proofs

Ledger operations produce a Receipt, which serves as a guarantee from the underlying platform of a transaction that occurred in its ledger. This receipt is provided by an adapter to the router to record transactions, either as part of the EP instruction completion proposal phase or individually to record transactions that were triggered externally to FinP2P and affect the investors' accounts.

To further enhance this guarantee, an additional proof can be attached to the Receipt. By supplying the proof as part of the Receipt, the organization adds another layer of trust and a guarantee that a transaction was recorded in the ledger. This can increase the trust of other parties that may not have direct access to the ledger.

Organizations can provide segregated private keys for ledger proofs. The information about the key used for verification is provided by the FinP2P asset policy, which provides general information about the tokenization platform capabilities and is published as metadata on specific asset profiles. These keys can be further pinned by other parties to reduce the need to trust external configuration dependencies.

Overview of Proof Types

  • Receipt Signature Based:
    • Ledgers may apply a digital signing algorithm encoding the Receipt transaction information into a digest, which will be signed by a private key owned exclusively by the organization controlling the ledger or tokenization platform. The additional signature-based proof adds another layer of reliability for the guarantee provided by the organization that the Receipt transaction was indeed recorded in its ledger, and the data was not tampered with.
    • The proof is a digital signature applied to the Receipt data and signed by a private key owned by the controlling organization of the tokenization platform, the structure of the message to be signed can follow the below EIP712 structure of Hashlist structure.
    • The key may differ from the Organization's Router private key, which is associated with the public key identity of the organization in the FinP2P network (AKA FinID).

Other proof types to be added soon:

  • Zero Knowledge:
    • For ledgers and tokenization platforms that support Zero Knowledge Proofs (ZKP), the ledger may provide a ZKP for the existence of the transaction within a blockchain block and that the network has reached consensus about the block.
  • Ledger Specific Proofs:
    • Ledgers may supply proof of a transaction being recorded on a ledger by providing ledger-specific cryptographic proofs of this action. This may require additional key pre-setup to ensure other parties can validate the proof.

Receipt Signature Based proof

EIP712 Proof Structure

Type Definitions

The following table describes the EIP-712 type definitions used in the message:

OrderType NameField NameField TypeDescription
1EIP712DomainnamestringName of the signing domain
2versionstringVersion of the signing domain
3chainIduint256Chain ID where the contract is deployed
4verifyingContractstringAddress of the verifying contract
5AccountaccountTypestringType of the account
6AccountfinIdstringFinID of the account
9TransactionDetailsoperationIdstringOperation ID of the transaction
10TransactionDetailstransactionIdstringTransaction ID on the ledger
11AssetassetIdstringID of the asset
12AssetassetTypestringType of the asset
13TradeDetailsexecutionPlanIdstringExecution plan ID
14TradeDetailsinstructionSequenceNumberstringInstruction sequence number
15ReceiptidstringID of the receipt
16ReceiptsourceAccountthe source account
17ReceiptdestinationAccountthe destination account
20ReceiptassetAssetthe asset
22ReceipttradeDetailsTradeDetailsthe trade details relating to the EP
23ReceipttransactionDetailsTransactionDetailsthe transaction details

Message Fields

The following table describes the fields included in the EIP-712 message:

Field NameField TypeDescription
idstringID of the receipt
sourceAccountTypestringType of the source account
sourceFinIdstringFinancial ID of the source account
destinationAccountTypestringType of the destination account
destinationFinIdstringFinancial ID of the destination account
assetIdstringID of the asset
assetTypestringType of the asset
operationIdstringOperation ID of the transaction
transactionIdstringTransaction ID
executionPlanIdstringExecution plan ID
instructionSequenceNumberstringInstruction sequence number

JSON Sample:

{
  "primaryType": "Receipt",
  "domain": {
    "name": "FinP2P",
    "version": "1",
    "chainId": 1,
    "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC"
  },
  "types": {
    "EIP712Domain": [
      {"name": "name", "type": "string"},
      {"name": "version", "type": "string"},
      {"name": "chainId", "type": "uint256"},
      {"name": "verifyingContract", "type": "string"}
    ],
    "Account": [
      {"name": "accountType", "type": "string"},
      {"name": "finId", "type": "string"}
    ],
    "TransactionDetails": [
      {"name": "operationId", "type": "string"},
      {"name": "transactionId", "type": "string"}
    ],
    "Asset": [
      {"name": "assetId", "type": "string"},
      {"name": "assetType", "type": "string"}
    ],
    "TradeDetails": [
      {"name": "executionPlanId", "type": "string"},
      {"name": "instructionSequenceNumber", "type": "string"}
    ],
    "Receipt": [
      {"name": "id", "type": "string"},
      {"name": "source", "type": "Account"},
      {"name": "destination", "type": "Account"},
      {"name": "asset", "type": "Asset"},
      {"name": "tradeDetails", "type": "TradeDetails"},
      {"name": "transactionDetails", "type": "TransactionDetails"}
    ]
  },
  "message": {
    "id": "receipt123456",
    "source": {
      "accountType": "sourceAccountType",
      "finId": "sourceFinId"
    },
    "destination": {
      "accountType": "destinationAccountType",
      "finId": "destinationFinId"
    },
    "asset": {
      "assetId": "asset123",
      "assetType": "finp2p"
    },
    "tradeDetails": {
      "executionPlanId": "ep123",
      "instructionSequenceNumber": "1"
    },
    "transactionDetails": {
      "operationId": "op123",
      "transactionId": "tx123"
    }
  }
}

Hashlist Proof Structure

The signature template for the Receipt proof in Hashlist format, The Hashlist signature format involves creating an array of hashes, where each hash represents a group of values.

The list of fields as defined in Message Fields is hashed in order to create a Hash Group (HG). The HG is then hashed to create a Hashlist. The Hashlist is then signed by the sender's private key.

HG = hash('SHA3-256', [fields by order]);
hashList = hash('SHA3-256', [HG]);
Signature = sign(sender private secp256k1 key, hashList)