Merge pull request LF-Decentralized-Trust-labs#369 from LF-Decentrali…

…zed-Trust-labs/docs-migration

Working branch for docs

README.md

@@ -1,79 +1,46 @@
 # Paladin
 
-Paladin is a privacy preserving transaction manager for Ethereum.
-
-## Architecture overview
-
-<big>**⚠ WORK IN PROGRESS ⚠**</big>
-
-![Paladin Architecture Overview](./architecture/diagrams/architecture_overview.jpg)
-
-- Paladin is a sidecar process that runs alongside a Hyperledger Besu node
-    - Learn more about [Runtime Architecture](./architecture/runtime_architecture.md)
-- Paladin provides **secure channels** of communication to other Paladins over which it can selectively disclose private data
-    - Learn more about [Private Data Transports & Endpoint Registry](./architecture/data_and_registry.md)
-- Paladin supports Privacy Preserving Smart Contracts, and provides samples out-of-the-box
-    - Each smart contract has a part of that runs as a EVM smart contract on an **unmodified** EVM blockchain, and a part that runs as part of Paladin
-      - Learn more about [ledger layers](./architecture/ledger_layers.md)
-    - _Some_ implement `tokens backed by Zero-knowledge Proofs`
-      - Learn more about [Zeto](./architecture/zeto.md)
-    - _Some_ implement `tokens backed by Notary Certificates` (issuer/signatory endorsed tokens)
-      - Learn more about [Noto](./architecture/noto.md)
-    - _Some_ implement domains of `EVM Private Smart Contracts` running in `Privacy Groups` 
-      - Learn more about [Pente](./architecture/pente.md)
-      > Provides function similar to that provided by the [Tessera](https://github.com/consensys/tessera) project (successor to [Constellation](https://github.com/Consensys/constellation)) with additional interoperability and other enhancements
-    - _All_ use the EVM base ledger as the source of truth for order and finality of transactions
-    - _All_ are `atomically interoperable` via the base EVM ledger
-      - Learn more about [Atomic interop of privacy preserving smart contracts](./architecture/atomic_interop.md)
-    - _All_ store state in the EVM base ledger in a securely masked format preserving
-        - **Confidentiality**: the data is protected via cryptography, and selectively disclosed on a need to know basis
-        - **Anonymity**: the parties involved in a transaction, or set of transactions, cannot be determined without access to the confidential data
-        - Learn more about [Privacy](./privacy.md)
-- Paladin provides a high performance transaction manager that coordinates transaction assembly, submission and confirmation across Paladin runtimes
-    - To any EVM smart contract directly on the **base EVM ledger**
-    - To EVM Private Smart Contracts in **privacy groups**, backed by privacy preserving smart contracts
-    - To Privacy Preserving Smart Contracts that use **UTXO models** for highly scalable private tokens
-    - For atomic swaps between privacy preserving smart contracts
-    - Learn more about [Distributed transaction management](./architecture/transaction_manager.md) 
-- Paladin provides enterprise grade key management integration
-    - Managing many keys/identities within a single Paladin runtime
-    - With modular integration of remote HSM-backed key management systems
-    - Supporting native Ethereum, EIP-712, and ZKP compatible cryptography
-    - Learn more about [Signing and Key Management](./architecture/key_management.md) 
-- Paladin provides a development, configuration, and deployment pipeline for privacy preserving smart contracts
-    - Definition of the smart contract functions, inputs and events
-    - Supporting EVM programmable private smart contracts and UTXO based token models
-    - A set of gRPC code plug points for private lifecycle coordination and state management
-        - Programming wallet functions - coin/state selection
-        - Programming endorsement coordination / signature collection / sequencer selection
-        - Programming transaction verification & proof generation
-    - Support for `Java` and `WebAssembly` high performance code modules
-    - Learn more about the [Paladin programming model](./architecture/programming_model.md)
-
-## Dev environment setup
+Paladin brings true programmable privacy to the world's most popular smart contract platform.
+
+![Paladin](doc-site/docs/images/paladin_overview.svg)
+
+## Documentation
+
+Learn more about Paladin here:
+
+- https://lf-decentralized-trust-labs.github.io/paladin/head
+
+![Paladin](doc-site/docs/images/paladin_runtime.svg)
+
+## Getting started with Paladin
+
+Get a 3-node Paladin network running with Besu on your laptop:
+
+- https://lf-decentralized-trust-labs.github.io/paladin/head/getting-started
+
+![Paladin](doc-site/docs/images/paladin_deployment.svg)
+
+## Getting set up for development of Paladin
+
+Welcome!
+
+### Building locally
 
 Install the following pre-reqs:
-- JDK [version 21](https://jdk.java.net/archive/) which is compatible with [Gradle version 8.4](./gradle/wrapper/gradle-wrapper.properties)
-- install [protoc](https://grpc.io/docs/protoc-installation/)
-- install [docker with compose plugin](https://docs.docker.com/compose/install/)
-- install npm
+- JDK - https://adoptium.net/download/
+- Protoc - https://grpc.io/docs/protoc-installation/
+- Docker - https://docs.docker.com/compose/install/
+- NodeJS - https://nodejs.org/en/download/package-manager
 
 
-Run the following command to build Paladin:
+Then the following command to build Paladin via Gradle:
 
 ```shell
 ./gradlew build
 ```
 
-## How to run Paladin
-
-TBD
-
-### Build Paladin docker image
+### Running a full development environment
 
-TBD
+Check out the operator readme:
 
-## Repo structure
-This is a [Monorepo](https://en.wikipedia.org/wiki/Monorepo). To avoid overcomplicating monorepo setup, you should adhere to the following practices:
-1. One folder per repo. (a "repo" contains a set of code that could be separated into a standalone Github repo)
-2. You can use folders to group repos, however, nested repos are not allowed.
+- [operator/README.md](operator/README.md)

architecture/atomic_interop.md → doc-site/docs/architecture/atomic_interop.md

@@ -47,7 +47,7 @@ See the [Programming Model](./programming_model.md) section for more information
 
 The first type of atomic interop supported by Paladin is approval-based atomic transactions.
 
-![Approval-based atomic transaction flow](./diagrams/approval_based_atomic_tx.jpg)
+![Approval-based atomic transaction flow](../images/approval_based_atomic_tx.jpg)
 
 In the above example Bob and Sally are performing a DvP of some privacy preserving cash tokens, and some privacy preserving bond tokens, in coordination with a programmed EVM private smart contract that _only Bob and Sally are party to_.
 

architecture/data_and_registry.md → doc-site/docs/architecture/data_and_registry.md

@@ -4,7 +4,7 @@ Each Paladin runtime needs to share data privately with other Paladins, based on
 
 These message are frequent and occur as part of the [Distributed transaction manager](./transaction_manager.md) operation to coordinate the assembly and submission of transactions.
 
-![Data transports & registry](./diagrams/data_transports_and_registry.jpg)
+![Data transports & registry](../images/data_transports_and_registry.jpg)
 
 ## Types of identity
 

doc-site/docs/architecture/domains.md

@@ -0,0 +1,3 @@
+![Domain API lifecycle](../images/domain_lifecycle.svg)
+
+> Work in progress docs page

architecture/key_management.md → doc-site/docs/architecture/key_management.md

@@ -2,7 +2,7 @@
 
 > TODO: Well established architecture already being brought across to Paladin here (Lead: Matt Clarke)
 
-![Key Management](./diagrams/key_management.jpg)
+![Key Management](../images/key_management.jpg)
 
 Key management in Paladin is designed to meet a complex set of requirements for enterprise
 key management, spanning both the secure storage of key materials in advanced locations (HMS/SSM),

architecture/ledger_layers.md → doc-site/docs/architecture/ledger_layers.md

@@ -2,7 +2,7 @@
 
 When we consider the make up of a distributed ledger system that preserves privacy for those transacting on it, there are a necessary set of layers that are present in any implementation.
 
-![Ledger layers](./diagrams/ledger_layers.png)
+![Ledger layers](../images/ledger_layers.png)
 
 The Paladin project:
 - Provides an enterprise grade runtime within the these layers can come together

architecture/noto.md → doc-site/docs/architecture/noto.md

@@ -3,10 +3,12 @@
 Privacy preserving token smart contract for fungible and non-fungible tokens, with transactions pre-verified by a notarizing entity.
 
 Examples of potential notaries:
+
 - The issuer of a tokenized cash asset, such as the bank issuing a tokenized deposit, or the central bank maintaining a wholesale CBDC
 - The registrar of a tokenized security, such as the issuer or transfer-agent of a tokenized fund unit or bond certificate
 
 In the notarized token model implemented by Noto, this notarizing entity:
+
 1. Sees all transaction data, before the transaction is finalized
 2. Verifies a signature from the transacting entity, that authorizes the transaction based on the disclosed data
 3. Writes the transaction to the blockchain using the notary identity, including the verified signature
@@ -25,32 +27,32 @@ Walking through a simple token transfer scenario, where Party A has some fungibl
 
 No information is leaked to Party C, that allows them to infer that Party A and Party B previously transacted.
 
-![Noto transaction walkthrough](./diagrams/noto_transaction_flow_example.png)
+![Noto transaction walkthrough](../images/noto_transaction_flow_example.png)
 
 1. `Party A` has three existing private states in their wallet and proposes to the notary:
-   - Spend states `S1`, `S2` & `S3`
-   - Create new state `S4` to retain some of the fungible value for themselves
-   - Create new state `S5` to transfer some of the fungible value to `Party B`
+    - Spend states `S1`, `S2` & `S3`
+    - Create new state `S4` to retain some of the fungible value for themselves
+    - Create new state `S5` to transfer some of the fungible value to `Party B`
 2. `Notary` receives the signed proposal from `Party A`
-   - Validates that the rules of the token ecosystem are fully adhered to
-   - Example: `sum(S1,S2,S3) == sum(S4,S5)`
-   - Example: `Party B` is authorized to receive funds
-   - Example: The total balance of `Party A` will be above a threshold after the transaction
-   - Uses the notary account to submit `TX1` to the blockchain recording signature + hashes
+    - Validates that the rules of the token ecosystem are fully adhered to
+    - Example: `sum(S1,S2,S3) == sum(S4,S5)`
+    - Example: `Party B` is authorized to receive funds
+    - Example: The total balance of `Party A` will be above a threshold after the transaction
+    - Uses the notary account to submit `TX1` to the blockchain recording signature + hashes
 3. `Party B` processes the two parts of the transaction
-   - a) Receives the private data for `#5` to allow it to store `S5` in its wallet
-   - b) Receives the confirmation from the blockchain that `TX1` created `#5`
-   - Now `Party B` has `S5` confirmed in its wallet and ready to spend
+    - a) Receives the private data for `#5` to allow it to store `S5` in its wallet
+    - b) Receives the confirmation from the blockchain that `TX1` created `#5`
+    - Now `Party B` has `S5` confirmed in its wallet and ready to spend
 4. `Party B` proposes to the notary:
-   - Spend state `S5`
-   - Create new state `S6` to retain some of the fungible value for themselves
-   - Create new state `S7` to transfer some of the fungible value to `Party C`
+    - Spend state `S5`
+    - Create new state `S6` to retain some of the fungible value for themselves
+    - Create new state `S7` to transfer some of the fungible value to `Party C`
 5. `Notary` receives the signed proposal from `Party B`
-   - Validates that the rules of the token ecosystem are fully adhered to
-   - Uses the notary account to submit `TX2` to the blockchain recording signature + hashes
+    - Validates that the rules of the token ecosystem are fully adhered to
+    - Uses the notary account to submit `TX2` to the blockchain recording signature + hashes
 3. `Party C` processes the two parts of the transaction
-   - a) Receives the private data for `#7` to allow it to store `S7` in its wallet
-   - b) Receives the confirmation from the blockchain that `TX2` created `#7`
-   - Now `Party C` has `S7` confirmed in its wallet and ready to spend
+    - a) Receives the private data for `#7` to allow it to store `S7` in its wallet
+    - b) Receives the confirmation from the blockchain that `TX2` created `#7`
+    - Now `Party C` has `S7` confirmed in its wallet and ready to spend
 
 > TODO: Fill in significantly more detail on how Noto operates (Lead: Andrew Richardson)

doc-site/docs/architecture/overview.md

@@ -0,0 +1,50 @@
+# Paladin
+
+Paladin is a privacy preserving transaction manager for Ethereum.
+
+## Architecture overview
+
+![Paladin Architecture Overview](../images/paladin_runtime.svg)
+
+- Paladin is a sidecar process that runs alongside a Hyperledger Besu node
+    - Learn more about [Runtime Architecture](./runtime_architecture.md)
+- Paladin provides **secure channels** of communication to other Paladins over which it can selectively disclose private data
+    - Learn more about [Private Data Transports & Endpoint Registry](./data_and_registry.md)
+- Paladin supports Privacy Preserving Smart Contracts, and provides samples out-of-the-box
+    - Each smart contract has a part of that runs as a EVM smart contract on an **unmodified** EVM blockchain, and a part that runs as part of Paladin
+      - Learn more about [ledger layers](./ledger_layers.md)
+    - _Some_ implement `tokens backed by Zero-knowledge Proofs`
+      - Learn more about [Zeto](./zeto.md)
+    - _Some_ implement `tokens backed by Notary Certificates` (issuer/signatory endorsed tokens)
+      - Learn more about [Noto](./noto.md)
+    - _Some_ implement domains of `EVM Private Smart Contracts` running in `Privacy Groups` 
+      - Learn more about [Pente](./pente.md)
+      > Provides function similar to that provided by the [Tessera](https://github.com/consensys/tessera) project (successor to [Constellation](https://github.com/Consensys/constellation)) with additional interoperability and other enhancements
+    - _All_ use the EVM base ledger as the source of truth for order and finality of transactions
+    - _All_ are `atomically interoperable` via the base EVM ledger
+      - Learn more about [Atomic interop of privacy preserving smart contracts](./atomic_interop.md)
+    - _All_ store state in the EVM base ledger in a securely masked format preserving
+        - **Confidentiality**: the data is protected via cryptography, and selectively disclosed on a need to know basis
+        - **Anonymity**: the parties involved in a transaction, or set of transactions, cannot be determined without access to the confidential data
+        - Learn more about [Privacy](./privacy.md)
+- Paladin provides a high performance transaction manager that coordinates transaction assembly, submission and confirmation across Paladin runtimes
+    - To any EVM smart contract directly on the **base EVM ledger**
+    - To EVM Private Smart Contracts in **privacy groups**, backed by privacy preserving smart contracts
+    - To Privacy Preserving Smart Contracts that use **UTXO models** for highly scalable private tokens
+    - For atomic swaps between privacy preserving smart contracts
+    - Learn more about [Distributed transaction management](./transaction_manager.md) 
+- Paladin provides enterprise grade key management integration
+    - Managing many keys/identities within a single Paladin runtime
+    - With modular integration of remote HSM-backed key management systems
+    - Supporting native Ethereum, EIP-712, and ZKP compatible cryptography
+    - Learn more about [Signing and Key Management](./key_management.md) 
+- Paladin provides a development, configuration, and deployment pipeline for privacy preserving smart contracts
+    - Definition of the smart contract functions, inputs and events
+    - Supporting EVM programmable private smart contracts and UTXO based token models
+    - A set of gRPC code plug points for private lifecycle coordination and state management
+        - Programming wallet functions - coin/state selection
+        - Programming endorsement coordination / signature collection / sequencer selection
+        - Programming transaction verification & proof generation
+    - Support for `Java` and `WebAssembly` high performance code modules
+    - Learn more about the [Paladin programming model](./programming_model.md)
+

architecture/pente.md → doc-site/docs/architecture/pente.md

@@ -10,7 +10,7 @@ Pente is a privacy preserving smart contract for Paladin, which provides a diffe
 
 _Each smart contract is its own world state._
 
-![Private Smart Contracts backed by C-UTXO](./diagrams/private_smart_contract_overview.png)
+![Private Smart Contracts backed by C-UTXO](../images/private_smart_contract_overview.png)
 
 - Private smart contracts exists uniquely within a privacy group
 - The transactions are confirmed by spending UTXO states on the base EVM ledger