feat(bridge): cross-chain ROSE bridge with modular Accounting proxy

Add a trustless cross-chain ROSE bridge between Oasis Sapphire and EVM
chains, and restructure the Accounting contract into delegated modules
behind its UUPS proxy.

Bridge:
- Lock/mint and burn/release flows for native ROSE <-> xERC20 xROSE,
  authorized by EIP-712 BridgeWithdraw signatures and settled by the
  ROFL TEE.
- Vendored xERC20 (defi-wonderland) with provenance README; CREATE3
  deployment of xROSE and ROFLBridge on the destination chain.
- Config-driven chain ids, gas pricing, and route registration via a
  generic addBridgeAssetToken task; deposit verification reuses the
  existing receipt/proof path.

Accounting modularization:
- Extract history into a delegated AccountingHistoryModule and the lock
  subsystem into a delegated LockModule; lift shared history and
  withdrawal internals into AccountingStorage.
- Wire both modules through the upgrade task and harden custody and
  bridge-out fund safety.

Custody-tx executor:
- Durable per-chain queue for every tx signed by Accounting.evmAddress(),
  with auto-recovery for stuck transactions and an owner-authorized
  clear surface.
- Skip non-record sidecar files in the state-dir scan so the executor
  no longer aborts startup on the clear-watcher cursor.

Ops:
- Serve the API via the ROFL auto proxy hostname, record the fresh
  bridge deployment addresses, and ship the container image at v31.

Verified end-to-end on testnet: Sapphire ROSE -> Base xROSE and back,
with steady-state value conservation.

Author: rube-de

.env.example

@@ -26,6 +26,20 @@ SAPPHIRE_RPC_URL=https://testnet.sapphire.oasis.io
 # SAPPHIRE_CHAIN_ID=23294
 # SAPPHIRE_RPC_URL=https://sapphire.oasis.io
 
+# =============================================================================
+# ROSE Bridge configuration
+# =============================================================================
+
+# ROFLBridge contract (CREATE3)
+ROFL_BRIDGE_ADDRESS=
+# xROSE token (CREATE3)
+XROSE_ADDRESS=
+# Mint/burn limits in wei — must match the values configured on ROFLBridge.
+BRIDGE_MINT_LIMIT_WEI=250000000000000000000000
+BRIDGE_BURN_LIMIT_WEI=250000000000000000000000
+# Reconciler tick (seconds) for ROFL-TEE-driven route writes.
+BRIDGE_ROUTE_RECONCILE_INTERVAL=30
+
 # Gas configuration
 ACCOUNTING_GAS_LIMIT=500000
 
@@ -71,6 +85,13 @@ SIWE_DOMAINS=http://localhost:8000
 # Uses SQLite via diskcache for process-safe storage
 # AUTH_TOKEN_STORAGE_DIR=.auth_tokens
 
+# Durable per-chain queue for every tx signed by Accounting.evmAddress()
+# (bridge mint/burn, sapphire release, normal withdrawals). Default
+# /data/custody-tx-executor maps to the named volume declared in compose.yaml.
+# Setting this to a tmpfs path is a fail-closed gate, not a usable default —
+# the executor needs disk persistence so nonce reservations survive restarts.
+# CUSTODY_TX_STATE_DIR=/data/custody-tx-executor
+
 # SIWE nonce expiration time in seconds (default: 300 = 5 minutes)
 # Bounds the window for SIWE message replay at the API level
 # SIWE_NONCE_EXPIRY_SECONDS=300

.github/workflows/ci.yml

@@ -87,6 +87,14 @@ jobs:
         run: |
           test -f solidity/artifacts/contracts/Accounting.sol/Accounting.json || (echo "Solidity artifacts not found!" && exit 1)
 
+      - name: Storage layout invariants (delegatecall safety)
+        # Pre-flight the Accounting<->module delegatecall invariants (storage
+        # layout, fallback dispatcher, signer/secret isolation) with --bail, so a
+        # slot mismatch fails fast instead of being masked by the full suite below.
+        run: cd solidity && bun run test:hardhat -- --bail --grep "storage|fallback dispatcher|setBridgeModule|signer isolation"
+        env:
+          BASE_SEPOLIA_RPC_URL: ${{ secrets.BASE_SEPOLIA_RPC_URL }}
+
       - name: Run Solidity tests
         run: make solidity-test
 

.gitignore

@@ -83,3 +83,4 @@ temp/
 tmp/
 *.orc
 accounting-module
+solidity/.openzeppelin/

Dockerfile

@@ -12,6 +12,7 @@ COPY . .
 
 # Verify Solidity artifacts exist (run 'make solidity-build' locally if this fails)
 RUN test -f solidity/artifacts/contracts/Accounting.sol/Accounting.json \
+    && test -f solidity/artifacts/contracts/AccountingHistoryModule.sol/AccountingHistoryModule.json \
     && test -f solidity/artifacts/contracts/auth/AccountingSiweAuth.sol/AccountingSiweAuth.json \
     || (echo "ERROR: Solidity artifacts not found. Run 'make solidity-build' before building Docker image." && exit 1)
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: install dev run test lint typecheck clean solidity solidity-build solidity-test solidity-lib solidity-clean solidity-coverage format format-check openapi openapi-check
+.PHONY: install dev run test lint typecheck clean solidity solidity-build solidity-test solidity-ci solidity-lib solidity-clean solidity-coverage format format-check openapi openapi-check
 
 install:
 	uv sync --no-dev
@@ -50,6 +50,15 @@ solidity-build:
 solidity-test:
 	cd solidity && bun run test
 
+# Mirrors the solidity job in .github/workflows/ci.yml: clean compile,
+# size gate, upgrade-safety, targeted storage-layout pre-flight, full suite.
+# Run before pushing if you want CI-equivalent verification locally.
+solidity-ci: solidity-clean solidity-build
+	cd solidity && bun run check:size
+	cd solidity && npx hardhat run scripts/validate-upgrade.ts
+	cd solidity && bun run test -- --bail --grep "storage|fallback dispatcher|setBridgeModule|signer isolation"
+	cd solidity && bun run test
+
 solidity-clean:
 	cd solidity && rm -rf dist artifacts cache typechain-types ignition/deployments
 

README.md

@@ -10,7 +10,7 @@ A reusable library for apps running in ROFL that enables:
 
 | Path | What's there |
 |------|--------------|
-| [`solidity/`](solidity/README.md) | On-chain contracts (Accounting, EVMSignerAndVerifier, AccountingSiweAuth), deployment & Hardhat tasks. |
+| [`solidity/`](solidity/README.md) | On-chain contracts (Accounting, AccountingHistoryModule, EVMSignerAndVerifier, AccountingSiweAuth), deployment & Hardhat tasks. |
 | [`src/`](src/README.md) | Python service that runs in the ROFL TEE — deposit verification, sweep state machine, withdrawal resolution. |
 | [`docs/api-reference.md`](docs/api-reference.md) | HTTP API reference: request/response shapes, auth, error codes. |
 

compose.yaml

@@ -1,7 +1,7 @@
 services:
   accounting-module:
     build: .
-    image: "docker.io/ptrusr/accounting-module:staging"
+    image: "ghcr.io/rube-de/flexvaults:v31"
     platform: linux/amd64
     environment:
       - API_HOST=${API_HOST:-0.0.0.0}
@@ -18,6 +18,12 @@ services:
       - WITHDRAWAL_POLL_INTERVAL=${WITHDRAWAL_POLL_INTERVAL:-12}
       - WITHDRAWAL_RESOLUTION_TIMEOUT=${WITHDRAWAL_RESOLUTION_TIMEOUT:-60}
       - MIN_WITHDRAWAL_GAS_BALANCE=${MIN_WITHDRAWAL_GAS_BALANCE:-10000000000000}
+      - BRIDGE_ROUTE_RECONCILE_INTERVAL=${BRIDGE_ROUTE_RECONCILE_INTERVAL:-30}
+      # Bridge — destination (chain-agnostic via CREATE3)
+      - ROFL_BRIDGE_ADDRESS=${ROFL_BRIDGE_ADDRESS}
+      - XROSE_ADDRESS=${XROSE_ADDRESS}
+      - BRIDGE_MINT_LIMIT_WEI=${BRIDGE_MINT_LIMIT_WEI}
+      - BRIDGE_BURN_LIMIT_WEI=${BRIDGE_BURN_LIMIT_WEI}
       # JWT Authentication configuration
       - JWT_EXPIRY_HOURS=${JWT_EXPIRY_HOURS:-12}
       - JWT_REFRESH_EXPIRY_DAYS=${JWT_REFRESH_EXPIRY_DAYS:-7}
@@ -35,14 +41,19 @@ services:
       - AUTH_CLIENTS=${AUTH_CLIENTS:-[]}
       # Sweep engine state
       - SWEEP_STATE_DIR=/data/sweep-engine
+      # Custody-tx executor state — durable per-chain queue for every tx
+      # signed by Accounting.evmAddress() (bridge mint/burn, sapphire release,
+      # normal withdrawals). Persistence is fail-closed: tmpfs is not a usable
+      # default, the executor refuses to drain without a real disk-backed mount.
+      - CUSTODY_TX_STATE_DIR=${CUSTODY_TX_STATE_DIR:-/data/custody-tx-executor}
     volumes:
       - /run/rofl-appd.sock:/run/rofl-appd.sock
       - sweep-engine-data:/data/sweep-engine
+      - custody-tx-executor-data:/data/custody-tx-executor
     ports:
       - "8000:8000"
-    annotations:
-      net.oasis.proxy.ports.8000.custom_domain: testnet.privana.finance
     restart: on-failure
 
 volumes:
   sweep-engine-data:
+  custody-tx-executor-data:

docs/api-reference.md

@@ -97,13 +97,15 @@ POST /auth/token {grant_type=authorization_code, code, code_verifier, …}
 
 | Field | Description | History kind type(s) |
 | --- | --- | --- |
-| `kind` | Entry type. Known values are `deposit`, `withdraw`, `createLock`, `transferFromLock`, and `transferBalance`; undecoded entries return `unknown`. | all |
+| `kind` | Entry type. Known values are `deposit`, `withdraw`, `createLock`, `transferFromLock`, `transferBalance`, `modifyLock`, and `unlockLock`; undecoded entries return `unknown`. | all |
 | `timestamp` | Entry timestamp. | all |
-| `token_id` | Token identifier. | `deposit`, `withdraw`, `createLock`, `transferFromLock`, `transferBalance` |
-| `amount` | Token amount as a decimal string. | `deposit`, `withdraw`, `createLock`, `transferFromLock`, `transferBalance` |
-| `chain_id` | Source chain for `token_id`, when known. | `deposit`, `withdraw`, `createLock`, `transferFromLock`, `transferBalance` |
+| `token_id` | Token identifier. | `deposit`, `withdraw`, `createLock`, `transferFromLock`, `transferBalance`, `modifyLock`, `unlockLock` |
+| `amount` | Token amount as a decimal string. For `modifyLock`, this is the additional locked amount and can be `0` for expiry-only changes. For `unlockLock`, this is the amount returned to available balance. | `deposit`, `withdraw`, `createLock`, `transferFromLock`, `transferBalance`, `modifyLock`, `unlockLock` |
+| `chain_id` | Source chain for `token_id`, when known. | `deposit`, `withdraw`, `createLock`, `transferFromLock`, `transferBalance`, `modifyLock`, `unlockLock` |
 | `deposit_id` | Deposit identifier. | `deposit` |
-| `counterparty` | Address payload for non-deposit entries: withdrawal destination, lock service, or transfer recipient. | `withdraw`, `createLock`, `transferFromLock`, `transferBalance` |
+| `counterparty` | Address payload for non-deposit entries: withdrawal destination for `withdraw`, lock service for `createLock`/`modifyLock`/`unlockLock`, and the other side relative to the authenticated user for paired internal transfer rows. | `withdraw`, `createLock`, `transferFromLock`, `transferBalance`, `modifyLock`, `unlockLock` |
+| `from_address` | Sender/original user for paired internal transfer rows. | `transferFromLock`, `transferBalance` |
+| `to_address` | Recipient user for paired internal transfer rows. | `transferFromLock`, `transferBalance` |
 
 ## Deposit Flow