High Level Architectural Components
As is typical with most application architectures there are 3 well-defined layers: user-facing dapps, middleware to implement the application business components, and a foundational blockchain network infrastructure that supports the sophisticated requirements of the higher layers.
Interface Layer
This layer provides the traditional user interface for interacting with Provenance Blockchain-based applications. Marketplaces and Exchanges are typical use cases where users buy, sell, and trade things of value. These "things of value" include asset-backed securities, cryptocurrency, or tokenized assets.
An important component of the interface layer is the Wallet. Entities (organizations, systems, or users) must have an account to conduct business on the Provenance Blockchain. An account is represented by the public key portion of a public and private key-pair. Accounts contain a uniquely identified address, which simply a string value derived from the entity’s public key following the Bech32 format, thus providing standard blockchain pseudonymity.
Consider a Hash transfer transaction where Alice is a Hash holder and Bob is the recipient. Alice holds 100 Hash at address
tp1kaczxflvhq4700r0ntdnqlxpu80xdp869seh9e (again, address is derived from the public key portion of a key pair that Alice holds). Bob also has generated a key pair and an address from the public key portion of the key pair tp18839rhfk0ql7mdqgn27eeaesmfr9ckpajssuc4.Before Alice can send a transfer transaction request to the Provenance Blockchain she must sign the transfer transaction. Alice uses the private key portion of her key pair to sign the transaction and submits the transaction to the blockchain. Provenance Blockchain validates the transfer transaction signature against Alice's public key, verifies that she has an account on Provenance Blockchain, and that the address holds enough Hash to pay transaction fees and to transfer to Bob.
A Wallet is where Alice and Bob store their key pairs. The Wallet is used to manage key pairs, addresses, and the token-values the addresses hold. Typically, and when using the Provenance Blockchain Wallet, HD Wallets are used. HD Wallets allow entities to create a root mnemonic seed (seed phrase) and then derive child keys from the root that can be used to hold value on Provenance Blockchain. For example, Alice's address
tp1kaczxflvhq4700r0ntdnqlxpu80xdp869seh9e is one of many keys in her HD Wallet. Entities can import, export, or regenerate their Wallet (and any subsequent derived addresses) using the root mnemonic seed (seed phrase). The root mnemonic seed is a secret value that the entity controls and never exposes to the Provenance Blockchain ecosystem.Middleware
The middleware layer is where organizational business processes are defined. These business processes include the creation of business value. For example, originating a loan is an action that creates a value marker. Utilizing a stable coin marker for a payment application also creates and uses value markers.
The middleware layer is the bridge between the Provenance Blockchain and the financial services business logic. The middleware layer connects directly to a Provenance Blockchain node to invoke transactions, query transactions, and listen for events.
The middleware layer is also where entities leverage the Provenance Blockchain client-side Contract Execution Environment for the onboarding and management of private and sensitive information. The Contract Execution Environment is a client-side solution that provides the ability for entities to exchange private data yet still leverage the ownership, immutability and value benefits provides by the Provenance Blockchain.
Provenance Blockchain
The Provenance layer is the Provenance Blockchain network and provides:
- A persistent, distributed, immutable, and replicated deterministic state machine
- The networking and consensus layers of the Provenance Blockchain including transaction ordering and consensus
- Value and ownership markers leveraged middleware business applications including coins, cryptocurrency, and tokenization
- Exchange, trading, and settlement of value markers and bridges to fiat currency
- Bi-lateral exchange implementations using Smart Contracts
- Blockchain primitives such as account authorization, governance, staking, voting, gas and fee processing, telemetry, and node configuration.
Major Components
Provenance Blockchain facilitates the development of blockchain-based financial services via components.
Application Trinity
Provenance Blockchain is composed of these core concepts:
- Modules that implement financial services business logic. Modules are composed to realize complex financial services processes.
- Smart Contracting engine to develop and deploy contracts directly to the Provenance Blockchain.
- Off-chain client-side agreements using the Contract Execution Environment.
Provenance Blockchain distinguishes three types of applications based on these core concepts:
On-Chain
Any client application that is configured with the proper key/addresses and modules, and uses Hash tokens for service payments, can transact directly on-chain within the Provenance Blockchain ecosystem. Applications interact directly with the core Provenance Blockchain Modules and a Provenance Blockchain Node. Applications may implement and leverage custom Smart Contracts specific to the business application use case.
Client-Side
Using the client-side Contract Execution Environment, Provenance Blockchain includes functionality to encrypt and store confidential data and documents and to securely and selectively share those with other clients. Note that the on-chain immutability is extended to the off-chain data when the on-chain contract refers to those data by their hash (checksum) identifier, i.e. the cryptographic hash of the data's content. This functionality allows for off-chain transactions that optionally can complement the on-chain operations. The Contract Execution Environment is a client-hosted solution (or, optionally, hosted by a trusted service provider) that also interacts with a Provenance Blockchain Node.
Hybrid
Financial transactions often consist of on-chain and client-side parts. For financial transactions, for example, the confidential documents supporting the transaction can be referred to by reference in the on-chain transaction. Those references point at immutable and encrypted documents that are safely stored off-chain. As part of the transaction, those confidential documents can be securely and selectively shared between the business partners. Provenance Blockchain fully supports this hybrid model, which allows for more complex financial transactions to be conducted within the Provenance Blockchain-ecosystem.
Provenance Blockchain Node
A Provenance Blockchain Node is a daemon process (
provenanced) Full-Node Client implementation and is the core process that runs the Provenance Blockchain. This process runs the state-machine, starting from a genesis file, and connects to peers on the network running the same client to receive and relay transactions, block proposals and signatures. Participants in the network run this process to initialize their state-machine, connect with other full-nodes and update their state-machine as new blocks come in. The blockchain full-node presents itself as the provenanced binary.Nodes in the network include:
- Query nodes used by business application middleware for efficient and fast state query.
- Transactional nodes used by business application middleware for efficient transaction submission and event listening.
- Archival nodes where the pruning strategy is set to maintain all historic states.
- Validators that are responsible for committing new blocks in the blockchain for which they are rewarded with gas fees (i.e. Hash). These validators participate in the consensus protocol by broadcasting votes. Validators bond their own Hash and have Hash delegated, or staked to them by Hash holders. Validators have a stake in the network.
- Sentry nodes for Validator DDoS mitigation.
Cosmovisor
Cosmovisor is a small process manager around the Provenance Blockchain daemon process (
provenanced) that monitors the governance module for upgrade proposals. Approved upgrade proposals can be run manually or automatically to download the new code, stop the node, run the migration script, replace the node binary, and start with the a genesis file.Modules
Modules define the Provenance Blockchain logic. Provenance Blockchain is composed of modules from the Cosmos SDK and custom modules to support value markers and the Contract Execution Environment. Modules provide core functionality that blockchain applications need, including a boilerplate implementation of the ABCI to communicate with the underlying consensus engine, a multistore to persist state, a server to form a full-node, and interfaces to handle queries. Modules implement the bulk of the logic of financial service applications and the core does the wiring to enable modules to be composed together.
Modules can be seen as little state-machines within the state-machine. They generally define a subset of the state using one or more key-value stores and message types.
Key Ring
To interact with the
provenanced daemon, and by extension the node, a keyring that holds the private/public key pairs used to interact with a node must be established. For example, a validator key needs to be set up before running the blockchain node so that blocks can be correctly signed. The private key can be stored in different locations, called "backends", such as a file, an HSM, or the operating system's own key storage. Refer to the Cosmos keyring documentation for more information.Genesis
Before running a node the chain is initialized via a genesis file. A default Provenance Blockchain genesis file is provided depending on the network in use (mainnet versus testnet). Refer to Running a Node for more information on establishing a genesis file.
Interacting with a Node
There are multiple ways to interact with a node: using the CLI, using gRPC, or using the REST endpoints. With a running node, the
provenanced daemon process can be used as a CLI. The CLI provides functionality for signing and submitting transactions, querying, key and key ring management, as well as Module interaction. Refer to the Cosmos Interacting with the Node documentation for more information.Smart Contracts
The Provenance Blockchain Smart Contract engine is based on the CosmWasm smart contracting platform. It is referred to as
provwasm within the ecosystem. It provides a the smart contracting component of the ecosystem.ProvWasm is a module within Provenance Blockchain thereby providing smart contracting support to the Provenance Blockchain chain without adjusting existing logic. Smart contracts are hosted on a running Provenance Blockchain node (
provenanced) where they can then be used by applications. Applications connect to smart contracts in the same way as they would interact with modules: CLI, gRPC, or REST.There are 3 phases of a ProvWasm contract that help understand how they are used:
- Upload Code: Upload the optimized smart contract (wasm) code, no state nor contract address (example Standard ERC20 contract)
- Instantiate Contract: Instantiate a code reference with some initial state, creates new address (example set token name, max issuance, etc for my ERC20 token)
- Execute Contract: This may support many different calls, but they are all unprivileged usage of a previously instantiated contract, depends on the contract design (example: Send ERC20 token, grant approval to other contract).
Provenance Blockchain Smart Contract instantiation and execution is metered and requires gas. Furthermore, both instantiation and execution allow the signer to send some tokens to the contract along with the message. Two key differences are that sending tokens directly to a contract does not trigger any contract code.
Provenance Blockchain Smart Contract are able to leverage Provenance Blockchain Modules. This allows for the creation of complex, multi-module contracts.
Contract Execution Environment
The Provenance Blockchain Contact Execution Environment (BlockVault) is an optional layer on top of the Provenance Blockchain to allow single- and multi-party client-side contract execution while preserving data privacy. Provenance Blockchain client-side contracts take encrypted data from the user (client) and transform the information into encrypted data in the user’s own private object store with object hashes recorded on the blockchain. BlockVault directly integrates with the Provenance Blockchain Metadata Module to simplify generating signed records of an asset’s provenance.
Assets can be directly defined with the Metadata module, but the BlockVault execution environment assists in the complex process of hashing of data, maintenance of immutable objects, and signature orchestration between multiple parties.
Client Contracts
Client-side contracts differ from "smart contracts" in that they keep data private between parties off-chain and thus facilitate a structure to record agreed-upon state data to the blockchain. Smart contracts, in comparison, are run directly on the blockchain and require the validators to have access to the data, which complicates many consumer-based transactions due to data privacy laws.
Transaction Flow
Entities and organizations utilize the Contract Execution Environment to execute contracts creating single or multi-party agreements. Entity identity and data encryption make use of public-private key pairs. Entities are known to each other and share data with each other through their public keys. Contracts and asset data are forwarded to all entities participating in the contract by public key identifier. Entities provide an implementation of an Encrypted Object Store (EOS) where encrypted data related to their public key is stored. Contract execution consumes data from the entity EOS, and the results of the contract executions are returned to the submitting entity's execution environment. The hash sum of the Contract execution results, i.e. the cryptograph hash of its content, are submitted to the Provenance Blockchain (via the Metadata module) where they are validated and committed to the chain. Provenance Blockchain emits events notifying entities the contract has been committed on the blockchain. An index, local to the entity, is updated with the new contract information. This information is used later for searching and querying the data.
Refer to the Contract Execution Environment for information and tutorials.