Merge pull request #465 from LF-Decentralized-Trust-labs/pente-docs

Add detailed Pente diagram and updated docs

doc-site/docs/architecture/pente.md

@@ -17,9 +17,7 @@ Each smart contract is its own world state.
 - The data required for each transition is confidential
 - These state transitions can be verified as part of atomic transactions with other tokens
 
-## Overview
-
-### History of EVM Private Smart Contracts
+## History of EVM Private Smart Contracts
 
 The concept of Private EVM Smart Contracts is not new.
 
@@ -33,14 +31,14 @@ When the block was confirmed by a node which already had the private input data,
 
 This model was evolved through a number of updates over the years, most significantly:
 
-- The re-building of the Haskell private state management runtime in Java
-   - [Orion](https://github.com/consensys/orion): Started in 2019, abandoned in Sep 2021
-   - [Tessera](https://github.com/consensys/tessera): Started in 2018, still maintained in 2024
+- The re-building of the Constellation (Haskell) private state management runtime in Java:
+    - [Orion](https://github.com/consensys/orion): Started in 2019, abandoned in Sep 2021
+    - [Tessera](https://github.com/consensys/tessera): Started in 2018, [deprecated in 2024](https://www.lfdecentralizedtrust.org/blog/sunsetting-tessera-and-simplifying-hyperledger-besu)
 - Support for private smart contract submission in Hyperledger Besu (additional to Quorum)
-   - The modification to the base EVM was reduced, by avoiding modification of the `V` value of transactions, and rather using a special pre-compiled smart contract address
-   - A different approach to Private transaction nonce management was adopted in Besu, where a separate nonce is managed in each privacy group
+    - The modification to the base EVM was reduced, by avoiding modification of the `V` value of transactions, and rather using a special pre-compiled smart contract address
+    - A different approach to Private transaction nonce management was adopted in Besu, where a separate nonce is managed in each privacy group
 - Quorum added "Private state validation" (not supported in Besu)
-   - Provides a validation mode that helps ensure that all transactions for a given private smart contract are always sent to the same participants
+    - Provides a validation mode that helps ensure that all transactions for a given private smart contract are always sent to the same participants
 
 However, the model has not fundamentally changed in this time.
 
@@ -51,33 +49,53 @@ Read here about the [Private transaction lifecycle](https://docs.goquorum.consen
 There are two closely related problems with the EVM Private Smart Contract model as implemented in these generations of the technology.
 
 1. When used correctly, state is locked inside of a Private Smart Contract
-   - This is fundamental to the programming model of EVM. A Smart Contract holds a single and complete set of state, visible to all parties in the privacy group.
-   - Transacting across smart contracts is problematic
-   - Implementing something like an ERC-20/ERC-721 token does not make sense in many scenarios, as the token can never be traded outside of the privacy group (noting that private positions modelled with ERC-20 tokens are a good exception to this statement)
+    - This is fundamental to the programming model of EVM. A Smart Contract holds a single and complete set of state, visible to all parties in the privacy group.
+    - Transacting across smart contracts is problematic
+    - Implementing something like an ERC-20/ERC-721 token does not make sense in many scenarios, as the token can never be traded outside of the privacy group (noting that private positions modelled with ERC-20 tokens are a good exception to this statement)
 2. The system does not provide feedback when this model is broken, intentionally, or via an operational/system error
     - Because _only the inputs_ are recorded to the blockchain for each transaction, via hash, and private smart contracts share a global address space, it is possible to have multiple overlapping sets of privacy groups transacting against the same smart contract
     - This means **the states diverge** so there is no single source of truth of the state of the private smart contract. Different parties have different data. So the fundamental assurances of a Smart Contract of agreed computation are not net.
     - The "Private state validation" feature (Quorum only) was a step towards solving this issue, by preventing mis-use of private smart contracts across different privacy groups.
     - Read more about these challenges [here](https://www.kaleido.io/blockchain-blog/why-tokens-dont-work-using-private-transactions)
 
-### The updated model in Pente
+## Paladin privacy groups
+
+The Pente domain uses the state management engine of Paladin to improve upon the existing model.
+
+Pre-submission endorsement of the full transaction execution is performed, combined with on-chain signature verification of the commitments to the input and output states, and double-spend protection on the account states enforced on-chain.
+
+![Pente EVM Privacy Groups - on-chain verification model](../images/paladin_evm_privacy_groups_verification_model.svg)
 
-Pente combined with the sophisticated state management engine of Paladin improves upon the model by using a Confidential-UTXO model to manage the private smart contracts.
+### On-chain state verification
 
 The guiding principals are:
 
+- On-chain transactions on the base EVM are the source of truth
+    - Every transaction execution is enforced **on-chain**, via threshold signature verification
+    - Pre-verification / endorsement of transactions happens off-chain prior to submission
+    - The exact signed transaction, inputs and outputs, are verified & signed by endorsers
+    - The transaction and execution result are masked as `commitments` on-chain
+        - Salted hashes of the signed input transaction, and input/output/read account states
 - No modification to the base EVM
     - No `V` value changes
     - No special execution during block execution / confirmation
     - The base EVM ledger transaction is a pure EVM transaction
-- Each Private Smart Contract exists entirely within a privacy group
-    - The address of the smart contract is tied to the uniqueness of the UTXO of the deployment
-- Submitter nonce management is managed within each privacy group
-    - Now deterministic because the nonce spending is managed inside of the UTXO states
-- The Hyperledger Besu EVM is used _as a module_ to executed un-modified EVM transactions
-    - These are executed in the Paladin runtime (not in the base Hyperledger Besu runtime)
-    - State is managed via the UTXO state storage of Paladin (not the Bonsai/Forrest state store of Besu)
-- Pente Private Smart Contract transactions are atomically interoperable via the Paladin framework
+- Each privacy group is a unique EVM smart contact on the base ledger
+    - Private Smart Contract exists entirely within a privacy group
+    - A privacy group is just like a mini-blockchain, hosted inside of one smart contract
+- Submitter account and nonce management is managed within each privacy group
+    - Accounts are UTXO states stored in this contract
+        - Externally owned accounts (EOAs)
+        - Contract accounts
+    - State/code/nonce transitions are all deterministic
+    - Endorsements of exact transitions are verified on-chain via EIP-712 signatures
+- Besu EVMs are used to pre-execute EVM transactions
+    - Just the EVM is loaded as a Java code module, on-demand when required
+    - These "ephemeral EVMs" are executed in the Paladin runtime
+        - There is no requirement for a local Besu runtime co-located with Paladin
+    - State is managed via the UTXO state storage of Paladin
+        - No use is made of the Bonsai/Forrest state store of Besu
+- Private Smart Contract transactions are atomically interoperable via the Paladin framework
     - This is the single most important enhancement. Because Pente is just another privacy preserving smart contract in Paladin, it can atomically interoperate with Token smart contracts. 
     - See the [Atomic Interop](./atomic_interop.md) section for how this enables sophisticated DvP scenarios to be programmed via Private EVM
 

doc-site/docs/index.md

@@ -6,7 +6,7 @@ Paladin provides programmable privacy for EVM.
 
 Paladin gives enterprises control of sensitive information without compromising transparency or scalability.
 
-The Paladin code base is open source, Apache 2.0 licensing and is maintained in an open source community that provides open governance and open development, as part of [Linux Foundation Decentralized Trust](https://www.lfdecentralizedtrust.org).
+The Paladin is Apache 2.0 open source, with open governance through [Linux Foundation Decentralized Trust](https://www.lfdecentralizedtrust.org).
 
 ## Programmable privacy for EVM