Coin Core Executor

The executor is the Coin Core component that executes and saves the results of transactions. The work that the executor does can be broken into three stages: prepare, execute, and persist.



During the preparation stage, the executor retrieves information required to execute a transaction and makes sure that all balances are up to date and accurate.


The steps are:

  • Read event targets: All targets required by the event are loaded from the event configuration.
  • Load target accounts: The account balance associated with each target is loaded.
  • Execute coin behaviors: If coins held in a balance have configured coin behaviors, the balance may not be usable immediately after it is loaded. Before it can be used, all coin behaviors must run so that if the balance contains any diminished or expired coins they are recovered, before the transaction starts. This step may produce ledger entries.


During the execution stage, the executor applies all event balance modifiers and creates a transaction record.


The steps are:

  • Apply modifiers: All the balance modifiers are run in a sequence, altering account balances and producing a number of ledger entries describing the changes that took place. All modifications are recorded for verification in the next step.
  • Verify the ledger invariant: After all balance modifiers have been applied, an extra step verifies that all modifications are balanced and that the transaction satisfies the ledger invariant (credits equal debits).


The final stage is the persistence stage. During this stage, tamper evidence is generated (if enabled) and data mutations are saved back to the data store. We will briefly go over the steps involved in the persistence stage after which, the process of generating tamper evidence is explained.


The steps are:

  • Generate hashes: If tamper evidence is enabled all entries and the transaction are hashed so that the contents can be verified later.
  • Generate tamper evidence: If tamper evidence is enabled, the transaction information will be sent to an auditing service where tamper evidence will be created and saved. Tamper evidence can be verified at a later time to check that no one has tampered with the ledger.
  • Write ledger entries: All ledger entries generated by coin behaviors and balance modifiers are written in the ledger.
  • Save transaction information: Information about the transaction is saved to the transaction log.

Once persistence is completed, the transaction is finished and a transaction ID is returned to the user. This ID can be used later to retrieve the transaction information, ledger entries, and tamper evidence.

Tamper Evidence

Tamper evidence refers to cryptographic artifacts (proofs) that can be used to show that some piece of data has not been altered, or otherwise tampered with, after the time that the artifact was produced. Tamper evidence is generated by an audit service. In this document, tamper evidence will be discussed in the context of Coin Core transactions, but tamper evidence can be produced for any kind of data.

A high-level overview of the process of generating and verifying tamper evidence is given below. The term "transaction information," as used below, refers to a list of events and state mutations that constitute a transaction. The term "transaction data" refers to transaction information which has been hashed to create a compact binary digest of the transaction information.
The process for generating tamper evidence is shown in the following diagram.



Step 1: The client initiates a transaction and passes a public key to Coin Core, which executes the transaction and hashes the result to create transaction data.
Step 2: The transaction data and the public key of the client requesting the transaction are sent to the audit service.
Step 3: The audit service generates a key pair and uses it and the client's public key to generate a shared key.
Step 4: This shared key is used to encrypt the transaction data, forming the tamper evidence artifact.

After the above procedure is completed, the audit service's generated private key is discarded so that the audit service cannot later decrypt or alter the artifact.
The process of verifying that a transaction has not been tampered with simply entails fetching the transaction from Coin Core, re-executing the transaction, and verifying that the transaction data matches the decrypted value of the tamper evidence artifact.



Step 1: Request the transaction data from Coin Core using the transaction ID.
Step 2: Coin Core returns the transaction information.
Step 3: Request the tamper evidence artifact from the audit service.
Step 4: Audit service returns the artifact (which is encrypted using the shared key) and the audit service's generated public key.
Step 5: The verification program uses the transaction information from step 2 to execute the transaction and re-generate the transaction data. It then verifies that the generated data matches the transaction data in the tamper evidence artiface (decrypted using the reconstructed shared key).