Add detailed documentation for Trollup components

Added comprehensive README files for Trollup Validation Server, Solana Groth16 Proof Verifier, and Solana ZK Proof Verifier. These documents include an overview, key components, program instructions, data structures, key functions, security considerations, program flow, usage, limitations, and future improvements.

README.md

@@ -101,6 +101,12 @@ sequenceDiagram
     end
 ```
 
+### **High level technical overview**
+
+- Proof: The proof is created using circuit creation provided by arkworks-rs. The proof is verified on chain by converting the proof, public inputs and verifying key data into pairs for use with Solanas alt_bn128_pairing function. This allows proof verification without using too much CU.
+
+- Validator commitment signature: The signature is created using libsecp256k1 and verified using Solanas secp256k1_recover function. This too helps keep it within the CU limit.
+
 ### **Running this example**
 
 With command line:

trollup-solana-programs/proof-verify/README.md

@@ -0,0 +1,131 @@
+# Solana Groth16 Proof Verifier Program Documentation
+
+## Overview
+
+This Solana program implements an on-chain verifier for Groth16 zero-knowledge proofs. It is designed to work within a larger system, likely the Trollup rollup, to verify proofs and update on-chain state based on the verification results. The program uses Solana's alt_bn128 precompiles for efficient pairing operations.
+
+## Key Components
+
+### 1. Program Instructions
+
+The program supports two main instructions:
+
+1. `Initialize`: Sets up the program's state account.
+2. `VerifyProof`: Verifies a Groth16 proof and updates the on-chain state.
+
+### 2. Data Structures
+
+#### ProofCommitmentPackage
+
+```rust
+pub struct ProofCommitmentPackage {
+    groth16_verifier_prepared: Groth16VerifierPrepared,
+    state_root: [u8; 32]
+}
+```
+
+This structure encapsulates the prepared Groth16 verifier and the new state root.
+
+#### Groth16VerifierPrepared
+
+```rust
+pub struct Groth16VerifierPrepared {
+    proof_a: [u8; 64],
+    proof_b: [u8; 128],
+    proof_c: [u8; 64],
+    prepared_public_inputs: [u8; 64],
+    verifying_key: Box<Groth16VerifyingKey>
+}
+```
+
+This structure contains the components necessary for Groth16 proof verification.
+
+#### Groth16VerifyingKey
+
+```rust
+pub struct Groth16VerifyingKey {
+    pub vk_alpha_g1: [u8; 64],
+    pub vk_beta_g2: [u8; 128],
+    pub vk_gamma_g2: [u8; 128],
+    pub vk_delta_g2: [u8; 128],
+}
+```
+
+This structure represents the Groth16 verifying key.
+
+### 3. Key Functions
+
+#### process_instruction
+
+The main entry point for the program. It deserializes the instruction data and routes to the appropriate handler.
+
+#### initialize
+
+Sets up the program's state account. This function:
+- Verifies the provided state account is the expected Program Derived Address (PDA).
+- Ensures the state account is empty (not already initialized).
+- Creates the state account with the necessary space for storing the state root.
+
+#### verify_proof
+
+Verifies a Groth16 proof and updates the on-chain state. This function:
+- Checks that the state account is valid and owned by the program.
+- Calls the `verify` method on the `Groth16VerifierPrepared` struct.
+- If the proof is valid, updates the on-chain state with the new state root.
+
+#### update_on_chain_state
+
+Updates the state account with the new state root.
+
+### 4. Groth16 Verification
+
+The `Groth16VerifierPrepared` struct implements the core Groth16 verification logic:
+
+- The `new` method performs basic sanity checks on the input lengths.
+- The `verify` method:
+    1. Concatenates the proof components and verifying key elements.
+    2. Calls the `alt_bn128_pairing` precompile to perform the pairing check.
+    3. Interprets the result to determine if the proof is valid.
+
+## Program Flow
+
+1. The program is initialized using the `Initialize` instruction, which sets up the state account.
+2. For each proof verification:
+   a. A `ProofCommitmentPackage` is prepared off-chain, containing the Groth16 proof components and the new state root.
+   b. This package is sent to the Solana program using the `VerifyProof` instruction.
+   c. The program verifies the Groth16 proof using the alt_bn128 pairing precompile.
+   d. If the proof is valid, the program updates the on-chain state with the new state root.
+
+## Security Considerations
+
+1. The program uses a Program Derived Address (PDA) for the state account, ensuring that only this program can modify the state.
+2. Proof verification is performed using Solana's secure alt_bn128 precompiles.
+3. The program includes several checks to ensure the validity of accounts and data before performing operations.
+
+## Error Handling
+
+The program defines a custom `Groth16Error` enum to handle various error cases that may occur during proof verification. This allows for more specific error reporting and handling.
+
+## Limitations and TODOs
+
+1. The `update_on_chain_state` function has a commented-out `invoke_signed` call, which might be needed for certain types of account updates.
+2. There's no mechanism for updating the verifying key, which might be necessary for long-term maintenance of the system.
+
+## Usage
+
+To use this program:
+
+1. Deploy the program to a Solana cluster.
+2. Initialize the program's state account using the `Initialize` instruction.
+3. For each state update:
+   a. Prepare a `ProofCommitmentPackage` off-chain, including the Groth16 proof and new state root.
+   b. Send this package to the program using the `VerifyProof` instruction.
+
+## Future Improvements
+
+1. Implement a mechanism to update the verifying key.
+2. Add support for batched proof verification for improved efficiency.
+3. Enhance error handling with more specific error types for different verification failure scenarios.
+4. Implement additional access controls or multi-signature requirements for sensitive operations.
+
+This documentation provides an overview of the Solana Groth16 Proof Verifier program. For more detailed information about specific functions or components, refer to the inline code documentation.

trollup-solana-programs/validator-signature-verify/README.md

@@ -0,0 +1,100 @@
+# Solana ZK Proof Verifier Program Documentation
+
+## Overview
+
+This Solana program implements an on-chain verifier for zero-knowledge proofs, specifically designed to work with the Trollup rollup system. It verifies off-chain generated proofs and updates the on-chain state accordingly. The program uses secp256k1 signature recovery to validate proof commitments.
+
+## Key Components
+
+### 1. Program Instructions
+
+The program supports two main instructions:
+
+1. `Initialize`: Sets up the program's state account.
+2. `VerifySig`: Verifies a proof commitment and updates the on-chain state.
+
+### 2. Data Structures
+
+#### ZkProofCommitment
+
+```rust
+pub struct ZkProofCommitment {
+    pub verifier_signature: [u8; 64],
+    pub recovery_id: u8,
+    pub public_key: [u8; 65],
+    pub new_state_root: [u8; 32],
+}
+```
+
+This structure represents an off-chain generated proof and verification result.
+
+### 3. Key Functions
+
+#### process_instruction
+
+The main entry point for the program. It deserializes the instruction data and routes to the appropriate handler.
+
+#### initialize
+
+Sets up the program's state account. This function:
+- Verifies the provided state account is the expected Program Derived Address (PDA).
+- Ensures the state account is empty (not already initialized).
+- Creates the state account with the necessary space for storing the state root.
+
+#### verify_proof
+
+Verifies a proof commitment and updates the on-chain state. This function:
+- Verifies the signature of the proof commitment.
+- If valid, updates the on-chain state with the new state root.
+
+#### verify_signature_with_recover
+
+Performs the actual signature verification using secp256k1 recovery. This function:
+- Computes the keccak256 hash of the new state root.
+- Recovers the public key from the signature.
+- Compares the recovered public key with the expected public key.
+
+#### update_on_chain_state
+
+Updates the state account with the new state root.
+
+## Program Flow
+
+1. The program is initialized using the `Initialize` instruction, which sets up the state account.
+2. Off-chain, proofs are generated and verified by a trusted validator.
+3. The validator creates a `ZkProofCommitment` with their signature and the new state root.
+4. This commitment is sent to the Solana program using the `VerifySig` instruction.
+5. The program verifies the signature using secp256k1 recovery.
+6. If the signature is valid, the program updates the on-chain state with the new state root.
+
+## Security Considerations
+
+1. The program uses a Program Derived Address (PDA) for the state account, ensuring that only this program can modify the state.
+2. Signature verification is performed using secp256k1 recovery, which is a secure method for verifying signatures.
+3. The program checks that the recovered public key matches the expected public key of the trusted validator.
+
+## Limitations and TODOs
+
+1. The public key of the trusted validator is currently hardcoded in the proof commitment. A TODO note suggests getting this from a Solana account instead.
+2. Error handling could be improved with more specific error types.
+3. The `update_on_chain_state` function has a commented-out `invoke_signed` call, which might be needed for certain types of account updates.
+
+## Usage
+
+To use this program:
+
+1. Deploy the program to a Solana cluster.
+2. Initialize the program's state account using the `Initialize` instruction.
+3. For each state update:
+   a. Generate and verify a proof off-chain.
+   b. Create a `ZkProofCommitment` with the validator's signature and new state root.
+   c. Send this commitment to the program using the `VerifySig` instruction.
+
+## Future Improvements
+
+1. Implement a mechanism to update the trusted validator's public key.
+2. Add support for multiple validators or a validator set.
+3. Implement batched proof verification for improved efficiency.
+4. Enhance error handling with custom error types for more informative error messages.
+
+This documentation provides an overview of the Solana ZK Proof Verifier program. For more detailed information about specific functions or components, refer to the inline code documentation.

validator/README.md

@@ -0,0 +1,104 @@
+# Trollup Validation Server
+
+## Overview
+
+The Trollup Validation Server is a crucial component of the Trollup rollup system. It provides an API for verifying zero-knowledge proofs and committing state changes to the Solana blockchain. The server is built using the Warp web framework and includes Swagger UI for API documentation.
+
+## Key Components
+
+### 1. Main Server (main.rs)
+
+The main server file sets up the web server and defines the API routes.
+
+#### Key Features:
+- Swagger UI integration for API documentation
+- Health check endpoint
+- Proof verification and commitment endpoint
+- CORS support
+
+#### Routes:
+- `/health`: Health check endpoint
+- `/prove/{new_state_root}`: Endpoint for proof verification and commitment
+- `/api-doc.json`: OpenAPI specification
+- `/swagger-ui`: Swagger UI for API documentation
+
+### 2. Handler (handler.rs)
+
+Contains the main logic for handling API requests.
+
+#### Key Functions:
+- `prove`: Handles proof verification and commitment
+- `health_handler`: Responds to health check requests
+
+### 3. Commitment (commitment.rs)
+
+Manages the creation and signing of commitments, as well as their submission to the Solana blockchain.
+
+#### Key Functions:
+- `create_and_sign_commitment`: Creates and signs a ZkProofCommitment
+- `verify_and_commit`: Verifies a proof and commits the result to the Solana blockchain
+
+### 4. Models (models.rs)
+
+Defines data structures used in the API.
+
+#### Key Structures:
+- `ApiResponse`: Represents the response format for API calls
+
+## API Endpoints
+
+### 1. POST /prove/{new_state_root}
+
+Verifies a zero-knowledge proof and commits the result to the Solana blockchain.
+
+#### Parameters:
+- `new_state_root` (path): The new state root for the transaction batch
+- Request body: `ProofPackagePrepared` (contains the proof to be verified)
+
+#### Responses:
+- 200 OK: Successful verification and commitment
+    - Body: `ApiResponse` (contains success status and transaction signature)
+
+### 2. GET /health
+
+Health check endpoint.
+
+#### Responses:
+- 200 OK: Server is healthy
+
+## Configuration
+
+The server uses a `TrollupConfig` for configuration settings. This likely includes:
+- RPC URL for Solana connection
+- Program IDs for various Solana programs
+- API keypair for transaction signing
+
+## Security Considerations
+
+1. The server uses Solana keypairs for signing transactions. Ensure these are kept secure.
+2. Proof verification is performed before committing to the blockchain, ensuring only valid state changes are recorded.
+3. The `create_and_sign_commitment` function uses secp256k1 for cryptographic operations.
+
+## Error Handling
+
+The server uses custom error types (`ValidationError`) for handling various error scenarios during proof verification and commitment.
+
+## Testing
+
+The `commitment.rs` file includes a test for the `create_and_sign_commitment` function, ensuring the correctness of commitment creation and signing.
+
+## Usage
+
+To run the server:
+
+1. Ensure all dependencies are installed.
+2. Set up the necessary configuration (Solana RPC URL, program IDs, etc.).
+3. Run the server using `cargo run`.
+4. Access the Swagger UI at `http://localhost:27183/swagger-ui/` for API documentation and testing.
+
+## Future Improvements
+
+1. Add more comprehensive error handling and logging.
+2. Implement rate limiting and additional security measures.
+3. Add support for batched proof verification for improved efficiency.
+4. Implement monitoring and alerting for server health and performance.