Merge pull request #36 from HorizenOfficial/as/wasm_common

As/wasm common

Author: alsala

runtime/wasm-go/README.md

@@ -1,8 +1,10 @@
 # WASM Go Module: Payment App
 
-This repository contains the Go implementation of the **Payment App** WASM module, an example application for handling deposits, transfers, and withdrawals for the Horizen PES project.
+This module contains the Go implementation of the **Payment App** WASM module — a privacy-preserving payment application for deposits, transfers, and withdrawals, built on the Horizen PES (Privacy Preserving Execution System) framework.
 
-**Note:** The WebAssembly (WASM) runtime itself is implemented and maintained in the `horizen-pes` repository. This module depends on that runtime for building and executing tests.
+The PES framework (`horizen-pes`) is **application-agnostic**: it provides a generic execution pipeline (EVM blockchain → Manager → Executor → WASM Runtime) that processes requests without ever parsing application payloads. This module is a specific application that plugs into that framework — the only layer that knows about payment logic. Any WASM module implementing the expected exports can replace it.
+
+**Note:** The WebAssembly (WASM) runtime itself (Wasmtime) is implemented and maintained in the `horizen-pes` repository. This module depends on that runtime for building and executing tests.
 
 ## Prerequisites
 
@@ -30,13 +32,19 @@ tinygo version
 
 ## Dependencies
 
-TODO: This will change when the github public repo will be available.
+This module depends on two external packages:
+
+- **`horizen-pes`** — The application-agnostic PES framework. Provides the generic WASM runtime (Wasmtime), common types (`common.Request`, `common.Event`, `common.Withdrawal`), and the `Runtime` interface. Used in tests to run the compiled WASM module.
+- **`horizen-cce-common-go/wasm`** — Shared WASM guest-side types and utilities. Provides `types.Uint256`, `types.Address`, `types.PlainEvent`, result types (`LoadModuleResult`, `DepositResult`, `ProcessResult`, `DeanonymizationResult`), memory allocator (`utils.Allocate`/`Deallocate`), logging, and pointer conversions. These are the shared data structures that the wallet also imports to ensure identical serialization.
 
-This module depends on the `horizen-pes` repository.
-Since it is a private repo, you need to set Go to access Github private repos:
+Both dependencies use `replace` directives in `go.mod`. For local development, uncomment the local path replaces pointing to sibling directories.
 
+Since these are private repos, you need to configure Go for private module access:
+
+```bash
 go env -w GOPRIVATE=github.com/HorizenOfficial/*
 git config --global url."git@github.com:".insteadOf "https://github.com/"
+```
 
 
 ## Building
@@ -54,9 +62,41 @@ tinygo build -o build/payment_app.wasm -target wasi main.go
 
 This will create the `build/payment_app.wasm` file.
 
+## Module Structure
+
+```
+runtime/wasm-go/
+├── main.go              # WASM export functions (bridge between runtime and app logic)
+├── app/
+│   ├── app.go           # Application logic (LoadModule, DepositFunds, ProcessRequest, GenerateDeanonymizationReport)
+│   └── types.go         # App-specific types (PayloadInstructions, TransferInstruction, WithdrawInstruction, AccountState)
+├── wasmtime_runtime_test.go  # Unit/integration tests against WASM runtime
+├── integration_test.go       # Integration tests for compiled WASM binary
+├── system_tests/             # E2E system tests (full PES stack simulation)
+├── build/                    # Dev WASM binary output
+├── production_build/         # Production WASM binary output
+└── Makefile
+```
+
+### WASM Exports
+
+The module exports these functions for the generic PES runtime to call:
+
+| Export | Purpose |
+|---|---|
+| `load_module(appId)` | Initialize application state |
+| `deposit(appId, sender, value, state)` | Credit sender account |
+| `process_request(appId, sender, payload, state)` | Handle transfers and withdrawals |
+| `generate_deanonymization_report(payload, state)` | Generate compliance reports |
+| `get_memory_stats()` | Return WASM memory allocation statistics |
+
+### Shared Data Structures
+
+The wallet (`wallet/`) constructs `PayloadInstructions` (defined in `app/types.go`) and encrypts them before submitting to the blockchain. This module receives and decrypts those instructions inside the TEE. Both sides import `types.Address` and `types.Uint256` from `horizen-cce-common-go/wasm/types` to ensure identical serialization.
+
 ## Development Workflow
 
-1.  **Modify WASM Module**: The core application logic is in `main.go` and `app/app.go`. Utility functions are located in `utils/`.
+1.  **Modify WASM Module**: The core application logic is in `app/app.go`. The WASM export bridge is in `main.go`. App-specific types are in `app/types.go`. Shared guest-side types and utilities come from `horizen-cce-common-go/wasm`.
 2.  **Rebuild Module**: After making changes, rebuild the WASM module using `make build` or the `tinygo` command directly.
 3.  **Update Tests**: Add or update corresponding tests in `wasmtime_runtime_test.go` or `integration_test.go` to reflect your changes.
 4.  **Verify Changes**: Run the test suite to ensure everything is working correctly:
@@ -69,9 +109,14 @@ This will create the `build/payment_app.wasm` file.
 To run the tests, use the standard `go test` command:
 
 ```bash
-go test ./...
+# Fast suite (skips Wasmtime-dependent tests)
+CI_FLAG=true go test -v ./...
+
+# Full suite (includes all Wasmtime integration tests)
+go test -v ./...
 ```
 
+Use `CI_FLAG=true` to skip tests that require the Wasmtime runtime or external dependencies.
 
 ### Test Files Overview
 
@@ -91,6 +136,9 @@ This project contains three distinct types of tests, each with a different focus
     *   **Type**: End-to-End (E2E) System Test
     *   **Scope**: Covers the entire application stack, including simulated components like an "Executor," a "Manager," a database, and a blockchain.
     *   **Purpose**: To validate that all components of the system work together correctly in a production-like environment. It tests the full user flow, including cryptographic operations, request submission, and state verification across the entire distributed system.
+    *   **Key tests**:
+        -   `TestPaymentAppFullFlow`: Deploys the app, registers user and auditor keys, deposits funds, withdraws funds, and generates a deanonymization report. Validates deposit and withdrawal event fields, verifies on-chain withdrawal recording, checks update payload signatures, and verifies the deanonymization report (framework envelope, base64-encoded report data, and expected user balance after all operations).
+    *   **Note**: Skipped when `CI_FLAG=true` due to long execution time.
 
 ## Resources