A Ricardian contract is any human readable contract agreed between two or more parties. Leveraging blockchain Proof-of-Existence (PoE) with Ricardian contracts can ensure legal contract compliance within smart contracts. With privacy and 3rd party smart contract interoperability, legally auditable and binding Ricardian contracts bridge legal compliance to decentralized systems and exchanges (DEXs) so they can support more products. New financial products offered for exchange on 3rd party decentralized systems can now require and enforce Ricardian contract agreement as a condition to receive a transfer on a decentralized exchange (DEX).

This story chronicles ImmutableSoft’s journey to add Ricardian relationships to their existing Solidity smart contract federation for users to securely manage product file releases. As a federated system, each organization manages their own affairs using the rules of the federation as defined in the public smart contract code. The innovation on top of PoE is document history and 3rd party integration. Public fill-in contract documents are already supported but client privacy by default was added to the smart contract logic. Some changes are highlighted in bold below showing the new parameter parentHash required to designate the file release a Ricardian leaf. A parentHash of zero is a master Ricardian contract or traditional file PoE release.

  /// @notice Create new release(s) of an existing product.
  /// Entity and Product must exist.
  /// @param productIndex Array of product IDs of new release(s)
  /// @param newVersion Array of version, architecture and languages
  /// @param newHash Array of file SHA256 CRC hash
  /// @param newFileUri Array of valid URIs of the release binary
  /// @param parentHash Array of SHA256 CRC hash of parent contract
  function creatorReleases(uint256[] memory productIndex,
                           uint256[] memory newVersion,
                           uint256[] memory newHash,
                           string[] memory newFileUri,
                           uint256[] calldata parentHash)
  {...      // Only emit events for non-Ricardian leaf's (public)
      if (parentHash[i] == 0)
        emit creatorReleaseEvent(entityIndex, productIndex[i],
                                 version);
  }

Each contract or document is uniquely identified by its SHA256 hash. This unique one-way hash of a file is often referred to as the Proof-of-Existence (PoE) hash. A Proof-of-Custody (PoC) hash is a PoE hash securely recorded to an immutable blockchain by an authorizing agency who verified custody. Providing service-based PoC of signed documents with revision history involves publicizing the master documents while keeping each client/signed contract private. When parental history is recorded it is possible to learn the master document from any client leaf SHA256 PoC hash. The immutable document history ensures a 3rd party can verify a client has signed/agreed to a contract. With history a leaf contracts’ PoC hash is proof to 3rd parties of agreement to the master document. This proof can then be utilized without divulging any private information to the 3rd party.

The data relations of the documents managed by the smart contracts is best visualized with a downward growing list, each unknown to each other except for a single list of parent(s). The first, or root or base, document is the master contract and has no parent. Each downward branch off this master contract is a completed, submitted and approved client (private), or an approved revised contract (public or private). There is no way to traverse down the tree (for privacy), yet the contract revisions and master document can easily be learned by traversing up the tree from a leaf.

Proof-of-Existence (PoE) applies to any on-chain file hash, while Proof-of-Custody (PoC) is defined in this discussion to be any private client Ricardian contract of a product managed by the owner of a verifying organization that has a public master document release associated with this product as a parent. The security of a Ricardian contract chain is determined first when ImmutableSoft verifies the federated entity (ie. the organization or person) is real and authorizes their write access to the Immutable smart contracts. This federated entity can then record their Ricardian contract product with signed blockchain transactions to Ethereum through the smart contracts.

Once approved and recorded on-chain by a federated entity or Contract Service Provider (CSP), any copy of the client agreement (ie. pdf) contract can confirm PoC by re-computing the file’s SHA256 hash of the submitted contract and checking existence on-chain. The confirming party records this client leaf agreement with a minted token that represents PoC of the final client agreement. Then the client may be transferred this newly minted token that immutably records the hash of the agreed contract (PoC). When this token is presented to 3rd parties, token ownership can then prove they are authorized signatories of the master contract, without divulging any private information. Digital presentation of client agreement with PoC tokens furthers interoperability by leveraging token ownership rights.

There are many practical uses of Ricardian PoC tokens to bridge legal chasms into decentralized systems while maintaining privacy. Specifics can often be enlightening so the remainder of this article will focus on the single use-case of 3rd party verifiable Know Your Customer (KYC) contracts using non-fungible (ie. unique) tokens.

A company, say XYZ Inc., provides KYC services by first releasing their attorney drafted KYC and Anti-Money Laundering (AML) document as a public form fill master PDF document. Configured as a KYC service product and master release within the Immutable Ecosystem, XYZ Inc.can then use this master document as a root or master Ricardian contract for their KYC service. When client customer ABC of the KYC/AML product completes the form-fill PDF with their private information, including appending additional information and/or verifying photos (driver’s license, etc.) and/or signs the completed document, multiple verification processes of XYZ Inc.begin in parallel.

After customer ABC has submitted the document with SHA256 hash (PoC) to XYZ Inc., any revision to the document changes the PoC hash and requires notification of both parties. XYZ may clarify/stamp/watermark if desired but if so must share any final document and PoC hash with customer ABC. Once the internal identity verification (ie. AML) procedures of XYZ Inc.have been completed satisfactorily, XYZ securely writes a transaction to the Ecosystem smart contracts containing a new release with a PoC hash of the final approved document of client ABC as verified by XYZ. This PoC confirms completion of KYC paperwork and verification of client ABC without divulging any information. Using the file release (PoE) smart contract interface the result of this transaction is an ERC721 (non-fungible) token representing the PoC hash of the signed and approved contract from ABC. The token represents proof that ABC has signed a legal agreement with XYZ Inc. as described in the public KYC product and public master document — in this case the KYC/AML form-fill document and product.

While only ABC and XYZ have possession of the final document and thus can calculate the one-way SHA256 hash, a 3rd party that trusts XYZ can then trust that ABC is KYC verified by XYZ through token ownership of the PoC hash. ABC, or XYZ Inc., can prove compliance in a court of law by presenting the signed document that has the same unique one-way SHA256 hash that was recorded as the PoC of a minted token. The ability to prove existence allows a 3rd party to ensure a signed agreement exists without having to know any of the details. A KYC blockchain service agreement can be required and enforced in 3rd party smart contracts if Ricardian contract tokens are checked and ensured to be clients of the master parent.

      // Check that Ricardian client matches the offer's parent
      if (theOffer.ricardianParent > 0)
      {
        require(ricardianClients[i] > 0, "Client required");
        uint parentDepth =
          creatorTokenInterface.creatorParentOf(
                                    ricardianClients[i],
                                    theOffer.ricardianParent);        require(parentDepth > 0, "Parent not found");
      }
      else
        require(ricardianClients[i] == 0, "Client not allowed");

With any smart contracts, angles vulnerable for misuse should be carefully researched and in this case there are some concerns worth addressing. The first concern is that XYZ Inc., or other Contract Service Provider (CSP), must be trusted — because of the privacy engineered into the system, any file hash can be recorded as a leaf of a master contract. A 3rd party user of this system must be able to trust that the KYC information has been validated and the relevant PoC hash properly stored on the blockchain in correct relation to the master document or revision signed/agreed to. This level of trust should be relatively easy to achieve by a legitimate business that bases its revenue on its reputation, for example our previous XYZ Inc. that performs KYC/AML services for others (ie. a CSP).

Another potential for misuse is in the public nature of the blockchain itself. All information on a blockchain is public and immutable. Even with no API to query or event triggered upon creation of leaf contracts, it is feasible that an attacker could reverse or social engineer the PoC hash of someone else’s identity token (KYC) and replay it to a 3rd party as a means to “prove” identity. Since the 3rd party has no direct knowledge of the user, a replay or counterfeit attack such as this might go undetected. To cryptographically solve this for integrated blockchain solutions, 3rd party smart contracts can leverage the PoC token ownership. If each client is transferred (ie. given ownership of) their contract PoC token minted by XYZ Inc., then the client can use token ownership to prove themselves to a 3rd party smart contract. ABC’s ownership of a client PoC token can be checked directly by the asset token itself before/during transfer to cryptographically prove possession.

By leveraging ownership, the KYC blockchain service agreement can now be required and enforced by default on any 3rd party exchange when Ricardian contract token chains are checked and enforced at the token transfer level. If a tokenized asset requires a Ricardian contract, it cannot be exchanged to a receiving Ethereum address that does not have a valid client token owned by that address.

function _beforeTokenTransfer(address from, address to,
                              uint256 tokenId)
      internal override(ERC721, ERC721Enumerable)
  {
    // Skip this check when first minting
    if (from != address(0))
    {
      // On exchange (not direct transfer)
      //   check any required Ricardian contracts
      if ((msg.sender != ownerOf(tokenId)) &&
          (TokenIdToRicardianParent[tokenId] > 0) &&
          (address(creatorInterface) != address(0)))
      {
        uint hasChild = creatorInterface.creatorHasChildOf(
                          to, TokenIdToRicardianParent[tokenId]);
        require(hasChild > 0,
                "Ricardian child agreement not found.");
      }
    }
}

When a blockchain transaction is made by client ABC, the public key transaction signature proves PoC token ownership. As such a secure blockchain method to prove authorization is now available without disclosure of any information to the 3rd party. All available on a publicly immutable database such as Ethereum through open, federated and interoperable smart contracts such as the Immutable Ecosystem. When the Ricardian client verification technology is encapsulated entirely within the token transfer logic, 3rd party exchanges, by default, enforce this requirement. The following steps are encompassed into a single blockchain transaction to cryptographically prove existence of KYC upon exchange.

Widespread adoption of Ricardian contract technology will require 3rd party interoperability. Tokenization appears to be common ground for interoperability and a non-fungible unique token ID can be leveraged to allow a hash lookup and vice versa. Immutably encoded into the unique token ID, or queried from, should be the issuing organization and the specific product (KYC/AML) and master file (ie. form-fill document). Interoperable unique tokens minted with a read-only PoC hash whose ownership is transferred to the client (ABC) has many advantages. Reverse lookup to find the authorized federated entity/product and master document (XYZ Inc.’s KYC .pdf) from any client completes the solution by allowing a search by ownership.

Public Ricardian contracts managed by federated smart contracts provide requirements automation and decentralized interoperability for legal contracts with privacy. As decentralized exchange (DEX) technology attracts products with additional legal/contractual requirements, the available solutions offered by ImmutableSoftare ready and tested for this challenge. When Ricardian contract agreements are enforceable within interoperable smart contracts, automation of legal processes for complex financial products can allow decentralization. Private and interoperable Contract Service Providers (CSP) that mint interoperable client PoC tokens are required for established financial and legal authorities to leverage their processes within this new frontier of decentralization.