a bunch more content

Author: kmurphypolygon

docs/cdk/agglayer/agglayer-go.md

@@ -5,6 +5,14 @@ The Agglayer Golang service is a web service designed to receive zero-knowledge
 !!! warning
     This service is now deprecating in favor of the more robust and efficient [Rust implementation](agglayer-rs.md).
 
+## Architecture
+
+The AggLayer Golang architecture supports interactions with multiple CDK chains for ZKP verification. 
+
+It uses PostgreSQL database for storage and interacts with both L1 and L2 chains through configured RPC nodes.
+
+[pic-here]
+
 ## Get started
 
 ### Run locally with Docker
@@ -21,28 +29,6 @@ The Agglayer Golang service is a web service designed to receive zero-knowledge
     make run-docker
     ```
 
-### Configure key signing 
-
-1. Install `polygon-cli`:
-
-    ```bash
-    go install github.com/maticnetwork/polygon-cli@latest
-    ```
-
-2. Create a new signature:
-
-    ```bash
-    polygon-cli signer create --kms GCP --gcp-project-id gcp-project --key-id mykey-tmp
-    ```
-
-3. Install `gcloud` CLI and set up ADC:
-
-    ```bash
-    gcloud auth application-default login
-    ```
-
-4. Configure `KMSKeyName` in `agglayer.toml`.
-
 ## Production set up
 
 1. Ensure only one instance of Agglayer is running at a time.
@@ -75,16 +61,34 @@ The Agglayer Golang service is a web service designed to receive zero-knowledge
     go install .
     ```
 
+### Configure key signing 
+
+1. Install `polygon-cli`:
+
+    ```bash
+    go install github.com/maticnetwork/polygon-cli@latest
+    ```
+
+2. Create a new signature:
+
+    ```bash
+    polygon-cli signer create --kms GCP --gcp-project-id gcp-project --key-id mykey-tmp
+    ```
+
+3. Install `gcloud` CLI and set up ADC:
+
+    ```bash
+    gcloud auth application-default login
+    ```
+
+4. Configure `KMSKeyName` in `agglayer.toml`.
+
 ### Configure `agglayer.toml`
 
 * `[FullNodeRPCs]` to point to the corresponding L2 full node.
 * `[L1]` to point to the corresponding L1 chain.
 * `[DB]` section with the managed database details.
 
-## Architecture
-
-Agglayer's architecture includes interactions with multiple CDK chains for ZKP verification. It uses PostgresDB for storage and interacts with both L1 and L2 chains through configured RPC nodes.
-
 ## API
 
 Refer to the `cmd` and `client` directories for API implementation details. Documentation and specific API routes can be generated from these sources.

docs/cdk/agglayer/agglayer-rs.md

@@ -4,21 +4,22 @@ AggLayer is a Rust-based web service designed to enhance interoperability among
 
 The service verifies the soundness of proofs from various CDK chains before forwarding them to L1 for verification.
 
-It replaces the previous [Golang implementation](agglayer-go.md)
+It replaces the previous [Golang implementation](agglayer-go.md).
 
 ## Architecture
 
 ### Components
 
-1. Aggregator: Receives and verifies zk-proofs.
-
-2. Verifier: Confirms the soundness of proofs before submitting them to L1.
+- Aggregator: Receives and verifies zk-proofs.
+- Verifier: Confirms the soundness of proofs before submitting them to L1.
 
 ### Data flow
 
-1. Input: Proofs from various CDK chains.
-2. Processing: Verification of proofs.
-3. Output: Verified proofs sent to L1.
+- Input: Proofs from various CDK chains.
+- Processing: Verification of proofs.
+- Output: Verified proofs sent to L1.
+
+[pic-here]
 
 ## Getting started
 
@@ -36,17 +37,17 @@ It replaces the previous [Golang implementation](agglayer-go.md)
 
 1. Clone the repository:
 
-   ```sh
-   git clone https://github.com/AggLayer/agglayer-rs.git
-   cd agglayer-rs
-   ```
+      ```sh
+      git clone https://github.com/AggLayer/agglayer-rs.git
+      cd agglayer-rs
+      ```
 
 2. Build and run:
 
-   ```sh
-   cargo build
-   cargo run
-   ```
+      ```sh
+      cargo build
+      cargo run
+      ```
 
 ## How to
 
@@ -64,32 +65,34 @@ chain_id = "your_chain_id"
 
 1. Run unit tests:
 
-   ```sh
-   cargo test
-   ```
+      ```sh
+      cargo test
+      ```
 
 2. Run integration tests by first ensuring all necessary services are running, then execute:
 
-   ```sh
-   cargo test -- --ignored
-   ```
+      ```sh
+      cargo test -- --ignored
+      ```
 
 ## API reference
 
 ### Endpoints
 
-1. **Submit proof**:
-   - **Endpoint**: `/submit_zkp`
-   - **Method**: POST
-   - **Payload**: 
+#### Submit proof
+
+- **Endpoint**: `/submit_zkp`
+- **Method**: POST
+- **Payload**: 
 
      ```json
      {
        "zkp": "base64_encoded_zkp",
        "chain_id": "cdk_chain_id"
      }
      ```
-   - **Response**:
+
+- **Response**:
 
      ```json
      {

docs/cdk/agglayer/balance-tracking.md

@@ -1 +1,75 @@
-https://github.com/AggLayer/lxly-bridge-and-call
+## Current unified bridge functionality
+
+The unified bridge allows users/contracts to independently bridge an asset or bridge a message between AggLayer connected chains.
+
+More complex operations such as bridge an asset and swap it for another asset, or bridge an asset and deposit it into a vault, require implementing custom logic. 
+
+## Interim step
+
+[chain indexer framework ??]
+
+## New bridge and call functionality
+
+The `bridgeAndCall` functionality supports these more complex operations by bridging a token with call data that is executed once bridged. A single call to bridge an asset also sends a message which executes a function.
+
+<center>
+![CDK architecture](../../img/cdk/agglayer/bridge-and-call.png)
+</center>
+
+## The `bridgeAndCall` function
+
+```solidity
+IBridgeAndCall(caller).bridgeAndCall(
+  token, // the asset to bridge
+  amount, // how much
+  optionalPermitData, // instead of using approve
+  destinationNetwork, // destination chain LxLy id
+  callAddress, // target contract in the destination chain
+  fallbackAddress, // in case of call error, fallback receives the asset
+  callData, // the "message" (function+args)
+  forceUpdateGlobalExitRoot // true to send this "ASAP"
+);
+```
+
+The new [`BridgeExtension.sol`](https://github.com/AggLayer/lxly-bridge-and-call/blob/main/src/BridgeExtension.sol) contract exposes the [`bridgeAndCall(...)`](https://github.com/AggLayer/lxly-bridge-and-call/blob/2d83e96ff120fae7f1c8bb1fc1a6cb7f74afa4aa/src/BridgeExtension.sol#L33) function which has the logic for bridging an asset and, at the same time, passing `callData` which includes the logic for receiving the message and making the call to the target contract.
+
+### Requirements and assumptions
+
+- Instances of `BridgeExtension` must have the same address in all chains (because of how `CREATE2` works and we need to pre-compute the `JumpPoint` address).
+  - This is achieved manually by making sure we deploy the proxy to the same address in all chains.
+  - Non-manually, we have to keep track of all instances in all supported chains - for all instances of the `BridgeExtension`.
+
+### Bridge and call process flow
+
+#### `BridgeExtension.bridgeAndCall(...)`
+
+1. Check what kind of asset is being bridged (i.e. is it more complex than a fungible asset).
+2. Bridge the asset to a precomputed address (the `JumpPoint` address).
+3. Create the message with the `callData` (and some additional information).
+4. Bridge the message to the destination chain.
+
+#### `claimAsset(...)` and `claimMessage(...)`
+
+1. Claimer performs the claims (`claimAsset` must be executed before `claimMessage` or an error is thrown).
+2. `claimAsset` transfers the asset to the `JumpPoint` address.
+3. `claimMessage` calls the unified bridge's `BridgeExtension.onMessageReceived(...)` function.
+
+#### `BridgeExtension.onMessageReceived(...)`
+
+1. Decode the message.
+2. Instantiate the `JumpPoint` for this execution (the address matches the precomputed one by using the same salt, arguments, and deployer address).
+
+#### `new JumpPoint(...)`
+
+1. Check what kind of asset was bridged.
+
+  - If it is an ERC20, approve spending by the target contract.
+  - Call the target contract with the callData.
+  - Send the native gas token if it's not an ERC20.
+
+2. In case of error, the asset is sent to a fallback address.
+3. `JumpPoint` self-destructs (leaves no trace).
+
+---
+
+For more information, visit the [AggLayer bridge and call repository](https://github.com/AggLayer/lxly-bridge-and-call).

docs/cdk/agglayer/bridge-and-call.md

@@ -0,0 +1,3 @@
+- Balance tracking.
+- Decentralization.
+- Etc.

docs/cdk/agglayer/current-state-func.md

@@ -1,12 +1,22 @@
+!!! info "Disclaimer"
+    - Much of the content in this section is discussing technology in development and not ready for release.
+    - Please check against the main documentation site for any live releases.
+    - Feel free to experiment with any code in public repos.
 
 ## Welcome to AggLayer documentation
 
-AggLayer is an evolving ecosystem of zk-based (zero-knowledge) interacting chains. It addresses the current industry focus on interoperability and shared liquidity.
+The culmination of Polygon innovation and design, AggLayer is an evolving ecosystem of zk-based (zero-knowledge) interacting chains. It addresses the current industry focus on interoperability and shared liquidity.
 
-AggLayer is a culmination of Polygon innovation and design. While most rollup environments follow a modular approach, where developers pick-and-choose components such as execution and data availability layers for example, the Agglayer vision is uniquely centered around zk-proof technology.
+While most rollup environments follow a modular approach, where developers pick-and-choose components such as execution and data availability layers for example, the Agglayer vision is uniquely centered around zk-proof technology.
+
+<center>
+![CDK architecture](../../img/cdk/agglayer/mono-modu.png)
+</center>
 
 ## AggLayer components
 
+AggLayer connects CDK chains and provides a zero-knowledge prover for validity and security.
+
 <center>
 ![CDK architecture](../../img/cdk/cdk-architecture.png)
 </center>
@@ -19,14 +29,14 @@ AggLayer is a culmination of Polygon innovation and design. While most rollup en
 
 ### AggLayer
 
+- Running now on the unified bridge technology, AggLayer takes a many-to-many approach to CDK chain interactions which focuses on validity, interoperability, and security.
+- It aggregates and batches proofs from multiple CDK chains into a single proof, significantly lowering the verification cost across chains as the ecosystem grows.
+
 <center>
 ![AggLayer overview](../../img/cdk/agglayer/agg-layer-overview.png)
 </center>
 
-- Evolving from the unified bridge technology, AggLayer takes a many-to-many approach to CDK chain interactions which focuses on validity, interoperability, and security.
-- It aggregates and batches proofs from multiple CDK chains into a single proof, significantly lowering the verification cost across chains as the ecosystem grows.
-- AggLayer ensures seamless and correct ordering of cross-chain transaction execution.
-- Implements securely shared liquidity across zk-based chains.
+- AggLayer ensures seamless and correct ordering of cross-chain transaction execution and securely-shared liquidity across all zk-based chains.
 
 ### Provers
 
@@ -39,4 +49,10 @@ AggLayer is a culmination of Polygon innovation and design. While most rollup en
 ![AggLayer overview](../../img/cdk/agglayer/prover.png)
 </center>
 
-These documents introduce you to the current unified bridge technology that inspires and underpins AggLayer. We also document some of AggLayer's key technology in development now; such as the Go and Rust libraries, and Plonky prover technology. We also document a little about what the future has in store.
+## What to expect
+
+These documents introduce you to the current unified bridge technology that inspires and underpins AggLayer. 
+
+We also document some of AggLayer's key technology in development now; such as the Go and Rust libraries, the bridge and call API, and Plonky prover technology. 
+
+We also document a little about what the future has in store.