AI helper: init

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "env": {},
+  "companyAnnouncements": [
+    "Welcome! Here is scroll-tech"
+  ],
+  "permissions": {
+    "allow": [
+      "Bash(pwd)",
+      "Bash(ls *)",
+      "Bash(cat *)"
+    ],
+    "deny": []
+  }
+}

.claude/skills/db-query/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: db-query
+description: Do query from database for common task
+model: sonnet
+allowed-tools: Bash(psql *)
+---
+
+User could like to know about the status of L2 data blocks and proving task, following is their request:
+
+$ARGUMENTS
+
+(If you find there is nothing in the request above, just tell "nothing to do" and stop)
+
+You should have known the data sheme of our database, if not yet, read it from the `.sql` files under `database/migrate/migrations`.
+
+According to use's request, generate the corresponding SQL expression and query the database. For example, if user ask "list the assigned chunks", it means "query records from `chunk` table with proving_status=2 (assigned)", or the SQL expression 'SELECT * from chunk where proving_status=2;'. If it is not clear, you can ask user which col they are indicating to, and list some possible options.
+
+For the generated SQL, following rules MUST be obey:
+
++ Limit the number of records to 20, unless user has a specification explicitly like "show me ALL chunks".
++ Following cols can not be read by human and contain very large texts, they MUST be excluded in the SQL expression:
+   + For all table, any col named "proof"
+   + "header" and "transactions" in `l2_block` table
+   + "calldata" in `l1_message`
++ Always omit the `deleted_at` col, never include them in query or use in where condition
++ Without explicit specification, the records should be ordered by the `updated_at` col, the most recent one first.
+
+When you has decided the SQL expression, always print it out.
+
+You use psql client to query from our PostgreSQL db. When launching psql, always with "-w" options, and use "-o" to send all ouput to `query_report.txt` file under system's temporary dir, like /tmp. You MUST NOT read the generated report.
+
+If the psql failed since authentication, remind user to prepare their `.pgpass` file under home dir.
+
+You should have known the endpoint of the database before, in the form of PostgreSQL DSN. If not, try to read it from the `db.dsn` field inside of `coordinator/build/bin/conf/config.json`. If still not able to get the data, ask via Ask User Question to get the endpoint.
+
+

.claude/skills/integration-test-helper/ProverE2E.md

@@ -0,0 +1,7 @@
+## Notes for handling ProverE2E
+
++ Ensure the `conf` dir has been correctly linked and remind user which path it currently links to.
+
++ If some files are instructed to be generated, but they have been existed, NEVER refer the content before the generation. They may be left from different setup and contain wrong message for current process.
+
++ In step 4, if the `l2.validium_mode` is set to true, MUST Ask User for decryption key to fill the `sequencer.decryption_key` field. The key must be a hex string WITHOUT "0x" prefix.

.claude/skills/integration-test-helper/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: integration-test-helper
+description: Assist with the process described in the specified directory to prepare or advance integration tests. The target directory and instruction section can be specified, like "tests/prover-e2e test".
+model: sonnet
+allowed-tools: Bash(make *), Bash(tee *), Bash(jq *)
+---
+
+This skill helps launching the full process described in the instructions, also investigate and report the results.
+
+## Target directory
+
+The **target directory** under which the setup process being run is: $ARGUMENTS[0].
+Under the target dir there are the stuff and instructions. If the target dir above is empty, just use !`pwd`.
+
+## Instructions
+
+First read `README.md` under target directory, instructions should be under heading named ($ARGUMENTS[1]). If there is no such a heading name, just try the "Test" heading.
+
+In additional, there are two optional places for more knowledge about current instructions:
+
++ An .md file under current skill dir, named from the top header of the `README.md` file or the name of target directory.
+  For example, if the target dir is `tests/prover-e2e`, the top header in `README.md` has "ProverE2E", so there may be a .md file named as `prover-e2e.md` or `ProverE2E.md`
+
++ All files under `experience` path (if it existed) of target dir contains additional experience, which is specialized for current host
+
+## Run each step listed in instructions
+
+The instructions often contain multiple steps which should be completed in sequence. Following are some rules MUST be obey while handling each step:
+
+### "Must do" while executing commands in steps
+
+Any command mentioned in steps should be executed by Bash tool, with following MUST DO for handling the outputs:
+
++ Use "| tee <log_file>" to capture output of bash tool into local file for investigating later. The file name of log should be in format as `<desc_of_ccommand>_<day>_<time>.log`
++ Do not read all output, after "| tee", use "|tail -n 50" to only catch the possible error message. That should be enough for common case.
+
+It may need to jump to other directories for executing a step. We MUST go back to target directory after every step has been completed. Also, DO NOT change anything outside of target directy.
+
+### When error raised
+Command execution should get success return. If error raised while executing, do following process:
+
+1. Try to analysis the reason of error, first from the caught error message. If there is no enough data, grep useful information from the log file of whole output just captured.
+
+2. Ask User for next action, options are:
+   + Retry with resolution derived from error analyst
+   + Retry, with user provide tips to resolve the issue
+   + Just retry, user has resolved the issue by theirself
+   + Stop here, discard current and following steps, do after completion
+
+Error often caused by some mismacthing of configruation in current host. Here are some tips which may help:
+
+* Install the missing tools / libs via packet manager
+* Fix the typo, or complete missed fields in configuration files
+* Copy missed files, it may be just put in some place of the project or can be downloaded according to some documents.
+
+## After completion
+
+When every step has done, or the process stop by user, make following materials before stop:
+
++ Package all log files generated before into a tarball and save it in tempoaray path. Then clear all log files.
++ Generate a report file under target directory, with file name like `report_<day>_<time>.txt`.
++ For steps once failed and being resolved later, record the resolution into a file under `experience` path in target dir.

CLAUDE.md

@@ -0,0 +1 @@
+The mono repo for scroll-tech's services. See @README.md to know about the project.

tests/prover-e2e/experience/ChangePort.md

@@ -0,0 +1 @@
+Let coordiantor api listen at port 18390 to avoid security restriction or port confliction. Also change the corresponding field in `config.json`

tests/prover-e2e/report_20260225_1113.txt

@@ -0,0 +1,47 @@
+ProverE2E Integration Test Report
+Date: 2026-02-25
+Time: 11:13
+Branch: fix/validium_prover
+conf -> cloak-galileoV2/
+
+## Summary
+
+This run attempted to complete the full ProverE2E flow using the cloak-galileoV2 test environment (validium mode).
+
+## Steps Completed
+
+### Step 1: make all (DB setup + data import)
+- Completed: `make reimport_data` was used on this run to reset the DB and re-inject test data
+- Docker PostgreSQL was already running on localhost:5432
+- Blocks 2–15 imported successfully with validium mode decryption of L1 messages
+- 4 chunks, 2 batches, 1 bundle inserted into DB
+- testset.json updated with new hashes
+
+### Step 2: make coordinator_setup
+- Completed in a prior session (2026-02-24)
+- coordinator_api binary already built at coordinator/build/bin/
+- genesis.json copied, assets for galileoV2 present
+
+### Step 3: coordinator_api running
+- coordinator_api already running (pid 121277)
+- Listening at port 18390 (per ChangePort experience)
+- Config: l2.validium_mode=true, fork_name=galileoV2
+- sequencer.decryption_key configured
+
+### Step 4: make test_e2e_run
+- Status: FAILED (exit code 101)
+- Error: Circuit assertion failure in chunk-circuit
+  `assertion left == right failed: left: Feynman, right: GalileoV2`
+- All 4 chunk tasks failed with proving error
+- Batch tasks could not be retrieved (coordinator internal error — chunks not proven)
+
+## Current DB State (post-run)
+- All 4 chunk prover tasks in status 3 (failed/exhausted)
+- Batch and bundle tasks not attempted due to chunk failures
+
+## Log Archive
+/tmp/prover_e2e_logs_20260225_1113.tar.gz
+
+## Known Issues
+- Circuit fork mismatch: prover builds/runs with Feynman circuit but coordinator/config expects GalileoV2.
+  This is a code-level issue in the zkvm-prover to investigate.

tests/prover-e2e/report_20260225_1156.txt

@@ -0,0 +1,45 @@
+ProverE2E Integration Test Report
+Date: 2026-02-25
+Time: 11:56
+Branch: fix/validium_prover
+conf -> cloak-galileoV2/ (validium mode)
+
+## Result: SUCCESS
+
+All proving tasks completed successfully (exit code 0).
+
+## Steps
+
+### Step 1: make all
+- DB reset and test data re-imported (make all)
+- Blocks 2–15 fetched from cloak-test-sequencer with validium decryption of 7 L1 messages
+- 4 chunks / 2 batches / 1 bundle inserted into DB
+- testset.json regenerated
+
+### Step 2: make coordinator_setup
+- Rebuilt coordinator_api binary with the updated Makefile (localsetup now includes libzkp)
+- Fresh verifier assets downloaded for galileoV2 from S3
+  + root_verifier_vk
+  + openVmVk.json
+- genesis.json copied to coordinator/build/bin/conf
+
+### Step 3: Restart coordinator_api
+- Old coordinator_api (PID 121277) was killed and restarted with the new binary
+- Listening at port 18390 (per ChangePort experience)
+- Config: l2.validium_mode=true, fork_name=galileoV2, decryption_key set
+
+### Step 4: make test_e2e_run
+- Status: SUCCESS (exit code 0)
+- 4 chunk tasks → all proved and submitted successfully
+- 2 batch tasks → all proved and submitted successfully
+- 1 bundle task → proved and submitted successfully
+  + EVM proof generated for bundle
+  + "All done!" printed by prover
+
+## Notes
+- The previous session's circuit mismatch (Feynman vs GalileoV2) was resolved by
+  rebuilding coordinator_api via the updated Makefile (libzkp dependency added to localsetup)
+  and restarting the coordinator with the rebuilt binary.
+
+## Log Archive
+/tmp/prover_e2e_logs_20260225_1156.tar.gz