Introduction

This document provides an overview of the signature schemes used in FinP2P. Currently, two signature formats are supported:

Hashlist
EIP712

Financial Transactions orchestrated by FinP2P carries a corresponding signature, representing the business terms and signed by the investors, the signature format used for the different operations, is detailed below.

Generating a Signature

Constructing the Values: Gather the necessary values based on the given signature template. These values typically include essential transaction or message details that need to be signed.
Hashing: Given the signature format, structure and generate a hash using a cryptographic hashing algorithm, such as SHA3-256 or Keccak-256. This hash represents a fixed-size, unique fingerprint of the original data.
Signing the Hash: Use the investor FinP2P FinID, private secp256k1 key ,to sign the hash. This cryptographic signature ensures that the hash (and thus the original data) has not been tampered with and verifies the identity of the signer.

Signature Formats

Shared Fields

Nonce is a field that appears in each of the signature templates. The nonce value assigned by the operation requester. The value of the nonce is a 32 bytes buffer, where first 24 bytes are assigned with a randomly generated value by the client and the last 8 bytes are assigned with the current epoch timestamp (in seconds).

Code Sample:

const nonce = Buffer.alloc(32);
nonce.fill(crypto.randomBytes(24), 0, 24);
const nowEpochSeconds = Math.floor(new Date().getTime() / 1000);
const t = BigInt(nowEpochSeconds);
nonce.writeBigInt64BE(t, 24);

1. Hashlist

Overview

The Hashlist signature format involves creating an array of hashes, where each hash represents a group of values. This structure is commonly used for operations involving multiple data points that need to be signed together. The benefit of this format is that during validation, one can construct only the necessary hash group from the original values while taking the other groups as is. This is somewhat analogous to a simplified Merkle tree, allowing for more efficient validation processes.

Operations and Templates

Operation 1: Deposit

Description:

The signature template for the deposit request contains the deposit details.

Template:

Order	Value	Type	Comment
1	nonce	string	Explanation provided above.
2	operation	string	"deposit"
3	assetType	string	For custom deposits use `"custom"`
4	assetId	string	Unique identifier of the asset (blank for `"custom"`)
5	dstAccount	string	Account to deposit the asset to
6	amount	string	Amount to deposit

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

Operation 2: Primary Sale

Description:

The signature format for an issuance in a primary sale with Delivery vs Payment involves two main components: the Asset Hash Group (AHG) and the Settlement Hash Group (SHG). Each group is hashed individually, and the resulting hashes are then combined and hashed together.

Template:

Asset Hash Group (AHG) Structure

Represents the asset instructions.

Order	Value	Type	Comment
1	nonce	[]byte	Explanation provided above.
2	operation	string	"issue"
3	assetId	string	Unique identifier of the asset
4	dstAccountType	string	"finId"
5	dstAccount	string	Investor account finId address that will receive the tokens
6	amount	string	Asset amount

Settlement Hash Group (SHG) Structure

Represents the payment/settlement instructions.

Order	Value	Type	Comment
1	assetId	string	Unique identifier of the asset
2	srcAccountType	string	"finId"
3	srcAccount	string	Investor account finId address for the payment asset
4	dstAccountType	string	"finId"
5	dstAccount	string	Issuer account finId address for the payment asset
6	amount	string	Settlement amount

//Asset Hash Group (AHG) structure:
AHG = hash('SHA3-256', [fields by order]);

//Settlement Hash Group (SHG) structure:
SHG = hash('SHA3-256', [fields by order]);

hashList = hash('SHA3-256', [AHG, SHG]);
Signature = sign(sender private secp256k1 key, hashList)

Operation 3: Secondary Sale

Description:

The signature format for the Delivery vs Payment involved in the secondary sale (executing a buying or selling intent) with settlement operation involves two main components: the Asset Hash Group (AHG) and the Settlement Hash Group (SHG). Each group should be hashed individually, and then both should be hashed together.

Template:

Asset Hash Group (AHG) Structure

Represents the asset instructions.

Order	Value	Type	Comment
1	nonce	[]byte	Explanation provided abo
2	operation	string	"transfer"
3	assetId	string	Unique identifier of the asset
4	srcAccountType	string	"finId"
5	srcAccount	string	Seller account finId address that will has the tokens
6	dstAccountType	string	"finId"
7	dstAccount	string	Buyer account finId address that will receive the tokens
8	amount	string	Asset amount

Settlement Hash Group (SHG) Structure

Represents the payment/settlement instructions.

Order	Value	Type	Comment
1	assetId	string	Unique identifier of the asset
2	srcAccountType	string	"finId"
3	srcAccount	string	Buyer account findId address for the payment asset
4	dstAccountType	string	"finId"
5	dstAccount	string	Seller account findId address for the payment asset
6	amount	string	Settlement amount

//Asset Hash Group (AHG) structure:
AHG = hash('SHA3-256', [fields by order]);

//Settlement Hash Group (SHG) structure:
SHG = hash('SHA3-256', [fields by order]);

hashList = hash('SHA3-256', [AHG, SHG]);
Signature = sign(sender private secp256k1 key, hashList)

Operation 4: Loan

Description:

The signature format for the loan involved in the execution of a loan with includes both the pledged asset and money side of the transaction.

Template:

Order	Value	Type	Comment
1	nonce	[]byte	Explanation provided above.
2	operation	string	"loan"
3	pledgeAssetId	string	Unique identifier of the asset
4	pledgeBorrowerAccountType	string	"finId"
5	pledgeBorrowerAccountId	string	Borrower account
6	pledgeLenderAccountType	string	"finId"
7	pledgeLenderAccountId	string	Lender account
8	pledgeAmount	string	Pledged asset amount
9	moneyAssetId	string	Unique identified of the asset
10	moneyLenderAccountType	string	"finId"
11	moneyLenderAccountId	string	Lender account
12	moneyBorrowerAccountType	string	"finId"
13	moneyBorrowerAccountId	string	Borrower account
14	borrowedMoneyAmount	string	Lender settlement amount
15	returnedMoneyAmount	string	Returned money at maturity, which includes applicable interest
16	openTime	string	Settlement time for Loan, EPOCH in seconds
17	closeTime	string	Maturity time for Loan, EPOCH in seconds

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

Operation 5: Redeem

Description:

The signature format for a redeem operation with settlement involves two main components: the Asset Hash Group (AHG) and the Settlement Hash Group (SHG). Each group should be hashed individually, and then both should be hashed together.

Template:

Asset Hash Group (AHG) Structure

Represents the asset instructions.

Order	Value	Type	Comment
1	nonce	[]byte	Explanation provided above.
2	operation	string	"redeem"
3	assetId	string	Unique identifier of the asset
4	srcAccountType	string	"finId"
5	srcAccount	string	Investor account finId address
6	amount	string	Asset amount

Settlement Hash Group (SHG) Structure

Represents the payment/settlement instructions.

Order	Value	Type	Comment
1	assetId	string	Unique identifier of the asset
2	srcAccountType	string	"finId"
3	srcAccount	string	Issuer account findId address for the payment
4	dstAccountType	string	"finId"
5	dstAccount	string	Investor account finId address that will receive the funds
6	amount	string	Settlement amount

//Asset Hash Group (AHG) structure:
AHG = hash('SHA3-256', [fields by order]);

//Settlement Hash Group (SHG) structure:
SHG = hash('SHA3-256', [fields by order]);

hashList = hash('SHA3-256', [AHG, SHG]);
Signature = sign(sender private secp256k1 key, hashList)

Operation 1: Withdraw

Description:

The signature template for the Withdraw request contains the Withdraw details. The destination related fields are optional and only signed in case the request contains those details

Order	Value	Type	Comment
1	nonce	string	Explanation provided above.
2	operation	string	"withdraw"
3	assetId	string	Unique identifier of the asset
4	srcAccountType	string	"finId"
5	srcAccount	string	Source account to withdraw funds from
6	dstAccountType	string	"finId" (optional)
7	dstAccount	string	Account to deposit the asset to (optional)
8	amount	string	string representation of the amount

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

2. EIP712

Overview

The EIP712 signature format leverages the widely adopted EIP712 standard for creating structured, off-chain signatures. This format is designed to securely sign typed data, ensuring that the data structure is clear and unambiguous. It is commonly used in operations requiring multiple data points to be signed in a standardized and interoperable manner. Furthermore, the EIP712 format is understood and supported by various key management systems, making it a versatile choice for secure digital signatures.

Operations and Templates

Template Domain Header

Field Name	Field Type	Value	Description
name	string	FinP2P	The name of the domain.
version	string	1	The version of the domain.
chainId	uint256	1	The ID of the blockchain network (e.g., 1 for Ethereum mainnet).
verifyingContract	address	0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC	The address of the verifying contract. (Not used for FinP2P, as contracts on multiple ledgers may be involved.)

Operation 1: Deposit

The signature template for the deposit request contains the deposit details.

Type Definitions

primaryType: Deposit

Type Name	Field Name	Field Type	Description
FinId	idkey	string	The unique identifier key for the FinP2P account.
Term	assetId	string	The unique identifier of the asset.
Term	assetType	string	For custom deposits use `"custom"`.
Term	amount	string	The amount of the asset involved in the transaction.
Deposit	nonce	string	A unique identifier for the deposit request.
Deposit	dstAccount	FinId	The destination account, represented by the FinId type.
Deposit	asset	Term	The asset details, represented by the Term type.

Message

Order	Value	Type	Comment
1	nonce	string	A unique identifier for the deposit request.
2	dstAccount	FinId	The destination account, represented by the FinId type.
3	Asset		Asset details, represented by the Term type.
3a	---> assetId	string	Unique identifier of the asset.
3b	---> assetType	string	Use `"custom"` for custom deposits.
3c	---> amount	string	Amount of the asset involved in the transaction.

JSON Sample:

{
  "primaryType": "Deposit",
  "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": "address"}
    ],
    "FinId": [
      {"name": "idkey", "type": "string"}
    ],
    "Term": [
      {"name": "assetId", "type": "string"},
      {"name": "assetType", "type": "string"},
      {"name": "amount", "type": "string"}
    ],
    "Deposit": [
      {"name": "nonce", "type": "string"},
      {"name": "dstAccount", "type": "FinId"},
      {"name": "asset", "type": "Term"}
    ]
  },
  "message": {
    "nonce": "0x1234567890abcdef",
    "dstAccount": {"idkey": "finId123"},
    "asset": {
      "assetId": "asset123",
      "assetType": "custom",
      "amount": "1000"
    }
  }
}

Operation 2: Primary Sale

The signature format for the issuance involved in the primary sale, including both the asset and settlement instructions.

Type Definitions

primaryType: PrimarySale

Type Name	Field Name	Field Type	Description
FinId	idkey	string	Unique identifier key for the FinP2P account.
Term	assetId	string	Unique identifier of the asset.
Term	amount	string	Amount of the asset involved in the transaction.
PrimarySale	nonce	string	Unique identifier for the primary sale request.
PrimarySale	buyer	FinId	Buyer information represented by the FinId type.
PrimarySale	issuer	FinId	Issuer information represented by the FinId type.
PrimarySale	asset	Term	Asset details represented by the Term type.
PrimarySale	settlement	Term	Settlement details represented by the Term type.

Message:

Order	Value	Type	Comment
1	nonce	string	A unique identifier for the primary sale request.
2	Buyer	FinId	The finId of the investor (buyer) participating in the issuance.
3	Issuer	FinId	The finId of the issuer of the asset sold in primary sale.
4	Asset		Asset details, represented by the Term type.
4a	---> assetId	string	Unique identifier of the asset.
4b	---> amount	string	Amount of tokens being issued.
5	Settlement		Settlement details, represented by the Term type.
5a	---> assetId	string	Unique identifier of the settlement asset.
5b	---> amount	string	Unit value for each token.

{
  "primaryType": "PrimarySale",
  "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": "address"}
    ],
    "FinId": [
      {"name": "idkey", "type": "string"}
    ],
    "Term": [
      {"name": "assetId", "type": "string"},
      {"name": "amount", "type": "string"}
    ],
    "PrimarySale": [
      {"name": "nonce", "type": "string"},
      {"name": "buyer", "type": "FinId"},
      {"name": "issuer", "type": "FinId"},
      {"name": "asset", "type": "Term"},
      {"name": "settlement", "type": "Term"}
    ]
  },
  "message": {
    "nonce": "0xabcdef1234567890",
    "buyer": {"idkey": "buyerFinId"},
    "issuer": {"idkey": "issuerFinId"},
    "asset": {
      "assetId": "asset456",
      "amount": "2000"
    },
    "settlement": {
      "assetId": "settleAsset456",
      "amount": "2000"
    }
  }
}

Operation 3: Secondary

The signature format for the trade involved in a secondary sale, including both the asset and settlement instructions.

Type Definitions

Primary Type: Buying

Type Name	Field Name	Field Type	Description
FinId	idkey	string	Unique identifier key for the FinP2P account.
Term	assetId	string	Unique identifier of the asset.
Term	amount	string	Amount of the asset involved in the transaction.
Buying	nonce	string	Unique identifier for the buying request.
Buying	buyer	FinId	Buyer information represented by the FinId type.
Buying	seller	FinId	Seller information represented by the FinId type.
Buying	asset	Term	Asset details represented by the Term type.
Buying	settlement	Term	Settlement details represented by the Term type.

Message:

Order	Value	Type	Comment
1	nonce	string	A unique identifier for the buying request.
2	Buyer	FinId	The finId of the buyer of the asset.
3	Seller	FinId	The finId of the seller of the asset.
4	Asset		Asset details, represented by the Term type.
4a	---> assetId	string	Unique identifier of the asset.
4b	---> amount	string	Amount of tokens being issued.
5	Settlement		Settlement details, represented by the Term type.
5a	---> assetId	string	Unique identifier of the settlement asset.
5b	---> amount	string	Unit value for each token.

Sample JSON:

{
  "primaryType": "Buying",
  "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": "address"}
    ],
    "FinId": [
      {"name": "idkey", "type": "string"}
    ],
    "Term": [
      {"name": "assetId", "type": "string"},
      {"name": "amount", "type": "string"}
    ],
    "Buying": [
      {"name": "nonce", "type": "string"},
      {"name": "buyer", "type": "FinId"},
      {"name": "seller", "type": "FinId"},
      {"name": "asset", "type": "Term"},
      {"name": "settlement", "type": "Term"}
    ]
  },
  "message": {
    "nonce": "0x123abc456def7890",
    "buyer": {"idkey": "buyerFinId456"},
    "seller": {"idkey": "sellerFinId456"},
    "asset": {
      "assetId": "asset789",
      "amount": "3000"
    },
    "settlement": {
      "assetId": "settleAsset789",
      "amount": "3000"
    }
  }
}

Primary Type: Selling

Type Name	Field Name	Field Type	Description
FinId	idkey	string	Unique identifier key for the FinP2P account.
Term	assetId	string	Unique identifier of the asset.
Term	amount	string	Amount of the asset involved in the transaction.
Selling	nonce	string	Unique identifier for the selling request.
Selling	buyer	FinId	Buyer information represented by the FinId type.
Selling	seller	FinId	Seller information represented by the FinId type.
Selling	asset	Term	Asset details represented by the Term type.
Selling	settlement	Term	Settlement details represented by the Term type.

Message:

Order	Value	Type	Comment
1	nonce	string	A unique identifier for the selling request.
2	Buyer	FinId	The finId of the buyer of the asset.
3	Seller	FinId	The finId of the seller of the asset.
4	Asset		Asset details, represented by the Term type.
4a	---> assetId	string	Unique identifier of the asset.
4b	---> amount	string	Amount of tokens being issued.
5	Settlement		Settlement details, represented by the Term type.
5a	---> assetId	string	Unique identifier of the settlement asset.
5b	---> amount	string	Unit value for each token.

Sample JSON:

{
  "primaryType": "Selling",
  "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": "address"}
    ],
    "FinId": [
      {"name": "idkey", "type": "string"}
    ],
    "Term": [
      {"name": "assetId", "type": "string"},
      {"name": "amount", "type": "string"}
    ],
    "Selling": [
      {"name": "nonce", "type": "string"},
      {"name": "buyer", "type": "FinId"},
      {"name": "seller", "type": "FinId"},
      {"name": "asset", "type": "Term"},
      {"name": "settlement", "type": "Term"}
    ]
  },
  "message": {
    "nonce": "0xabcdef9876543210",
    "buyer": {"idkey": "buyerFinId987"},
    "seller": {"idkey": "sellerFinId987"},
    "asset": {
      "assetId": "asset321",
      "amount": "1500"
    },
    "settlement": {
      "assetId": "settleAsset321",
      "amount": "1500"
    }
  }
}

Operation 4: Redemption

The signature format for a redemption operation, including both the asset and settlement instructions.

Type Definitions

Primary Type: Redemption

Type Name	Field Name	Field Type	Description
FinId	idkey	string	Unique identifier key for the FinP2P account.
Term	assetId	string	Unique identifier of the asset.
Redemption	nonce	string	Unique identifier for the redemption request.
Redemption	seller	FinId	Seller information represented by the FinId type.
Redemption	issuer	FinId	Issuer information represented by the FinId type.
Redemption	asset	Term	Asset details represented by the Term type.
Redemption	settlement	Term	Settlement details represented by the Term type.

Message

Order	Value	Type	Comment
1	nonce	string	A unique identifier for the redemption request.
2	Seller	FinId	Seller information represented by the FinId type.
3	Issuer	FinId	Issuer information represented by the FinId type.
4	Asset		Asset details, represented by the Term type.
4a	---> assetId	string	Unique identifier of the asset.
4b	---> amount	string	Amount of tokens being redeemed.
5	Settlement		Settlement details, represented by the Term type.
5a	---> assetId	string	Unique identifier of the settlement asset.
5b	---> amount	string	Unit value for each token.

Sample JSON:

{
  "primaryType": "Redemption",
  "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": "address"}
    ],
    "FinId": [
      {"name": "idkey", "type": "string"}
    ],
    "Term": [
      {"name": "assetId", "type": "string"},
      {"name": "amount", "type": "string"}
    ],
    "Redemption": [
      {"name": "nonce", "type": "string"},
      {"name": "seller", "type": "FinId"},
      {"name": "issuer", "type": "FinId"},
      {"name": "asset", "type": "Term"},
      {"name": "settlement", "type": "Term"}
    ]
  },
  "message": {
    "nonce": "0xabcdef1234567890",
    "seller": {"idkey": "sellerFinId123"},
    "issuer": {"idkey": "issuerFinId123"},
    "asset": {
      "assetId": "asset456",
      "amount": "2000"
    },
    "settlement": {
      "assetId": "settleAsset456",
      "amount": "2000"
    }
  }
}

Operation 4: Loan

The signature format for a loan operation, including both the asset and settlement instructions.

Type Definitions

Primary Type: Loan

Type Name	Field Name	Field Type	Description
FinId	idkey	string	Unique identifier key for the FinP2P account.
Term	assetId	string	Unique identifier of the asset.
Term	amount	string	Amount of the asset involved in the transaction.
Loan	nonce	string	Unique identifier for the loan request.
Loan	borrower	FinId	Borrower information represented by the FinId type.
Loan	lender	FinId	Lender information represented by the FinId type.
Loan	asset	Term	Asset details represented by the Term type.
Loan	settlement	Term	Settlement details represented by the Term type.
Loan	loanTerms	LoanTerms	Loan terms represented by the LoanTerms type.
LoanTerms	openTime	string	Opening time of the loan.
LoanTerms	closeTime	string	Closing time of the loan.
LoanTerms	borrowedMoneyAmount	string	Amount of money borrowed in the loan.
LoanTerms	returnedMoneyAmount	string	Amount of money to be returned at the loan’s maturity.

Message

Order	Value	Type	Comment
1	nonce	string	A unique identifier for the loan request.
2	Borrower	FinId	Borrower information represented by the FinId type.
3	Lender	FinId	Lender information represented by the FinId type.
4	Asset		Asset details represented by the Term type.
4a	---> assetId	string	Unique identifier of the asset.
4b	---> amount	string	Amount of tokens being issued.
5	Settlement		Settlement details represented by the Term type.
5a	---> assetId	string	Unique identifier of the settlement asset.
5b	---> amount	string	Unit value for each token.
6	LoanTerms		Loan terms represented by the LoanTerms type.
6a	---> openTime	string	Opening time of the loan.
6b	---> closeTime	string	Closing time of the loan.
6c	---> borrowedMoneyAmount	string	Amount of money borrowed in the loan.
6d	---> returnedMoneyAmount	string	Amount of money to be returned at the loan’s maturity.

Sample JSON:

{
  "primaryType": "Loan",
  "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": "address"}
    ],
    "FinId": [
      {"name": "idkey", "type": "string"}
    ],
    "Term": [
      {"name": "assetId", "type": "string"},
      {"name": "amount", "type": "string"}
    ],
    "LoanTerms": [
      {"name": "openTime", "type": "string"},
      {"name": "closeTime", "type": "string"},
      {"name": "borrowedMoneyAmount", "type": "string"},
      {"name": "returnedMoneyAmount", "type": "string"}
    ],
    "Loan": [
      {"name": "nonce", "type": "string"},
      {"name": "borrower", "type": "FinId"},
      {"name": "lender", "type": "FinId"},
      {"name": "asset", "type": "Term"},
      {"name": "settlement", "type": "Term"},
      {"name": "loanTerms", "type": "LoanTerms"}
    ]
  },
  "message": {
    "nonce": "0x1234567890abcdef",
    "borrower": {"idkey": "borrowerFinId"},
    "lender": {"idkey": "lenderFinId"},
    "asset": {
      "assetId": "asset123",
      "amount": "10000"
    },
    "settlement": {
      "assetId": "settleAsset123",
      "amount": "10000"
    },
    "loanTerms": {
      "openTime": "1609459200",
      "closeTime": "1640995200",
      "borrowedMoneyAmount": "10000",
      "returnedMoneyAmount": "11000"
    }
  }
}