Initial commit

Author: mattsse

.cargo/config.toml

@@ -0,0 +1,4 @@
+[alias]
+x = "run --package tempo-xtask --"
+xtask = "run --package tempo-xtask --"
+docs = "doc --workspace --all-features --no-deps"

.codex/skills/zones-deploy-debug/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: zones-deploy-debug
+description: Deploy Tempo Zones, start zone nodes, validate router swap-and-deposit flows, and debug zone sync, portal ingestion, withdrawal, sequencer key, and generated zone artifact issues in this repository. Use when working with just deploy-zone, zone-up, deploy-router, demo-swap-and-deposit, or generated/<name>/zone.json.
+---
+
+# Zones Deploy Debug
+
+Use this skill for repo-local zone deployment, smoke tests, and sync debugging.
+
+## Start here
+
+1. If the zone already exists, read `generated/<name>/zone.json` first.
+2. For real smoke tests, prefer `release` for `tempo-zone`.
+3. Use the `Justfile` and `docs/ZONES.md` as the source of truth for user-facing commands.
+4. Read `references/commands.md` for concrete command patterns and troubleshooting checks.
+
+## Preferred workflow
+
+1. Build `tempo-zone` in release before judging sync speed.
+2. Deploy a fresh zone if you need a clean test surface.
+3. Start the zone node and confirm `http://localhost:8546` is answering.
+4. For a direct bridge smoke test, run `just max-approve-portal`, `just send-deposit`, `just max-approve-outbox`, then `just send-withdrawal`.
+5. Deploy the router for that zone.
+6. Run the same-zone swap-and-deposit demo.
+7. If the demo stalls, compare the L1 block of the relevant tx with the latest `l1_block=` in the zone log before assuming the router flow is broken.
+
+## What to inspect
+
+- `generated/<name>/zone.json`
+- `Justfile`
+- `docs/ZONES.md`
+- `/tmp/tempo-zone-<name>*/logs/*/reth.log`
+
+## Known sharp edges
+
+- Fresh `dev` nodes can look broken because they are still compiling and replaying L1; use `release` for meaningful validation.
+- Direct deposit/withdraw validation needs both approvals: `just max-approve-portal` before depositing and `just max-approve-outbox` before withdrawing.
+- The demo's first real wait point is token enablement on L2. If the zone is still replaying older L1 blocks, `demo-swap-and-deposit` can time out before the `TokenEnabled` event appears.
+- The current `just demo-swap-and-deposit` recipe takes optional overrides positionally, not as `amount=... tick=...`.
+- If a restarted zone crashes while seeding `transferPolicyId` for a temporary token, check `crates/tempo-zone/src/l1_state/tip403/cache.rs` and consider retesting with a fresh zone.

.codex/skills/zones-deploy-debug/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Zones Deploy Debug"
+  short_description: "Deploy Tempo Zones and debug sync issues"
+  default_prompt: "Use $zones-deploy-debug to deploy a zone, validate router flows, or debug zone sync and portal issues."

.codex/skills/zones-deploy-debug/references/commands.md

@@ -0,0 +1,141 @@
+# Zone Commands
+
+## Release-first smoke test
+
+```bash
+cargo build --bin tempo-zone --release
+```
+
+Create a fresh zone when you need a clean router test:
+
+```bash
+just deploy-zone my-zone
+```
+
+That recipe creates the zone, stores `sequencerKey` in `generated/my-zone/zone.json`, and starts the node immediately. If you need tighter control, run:
+
+```bash
+target/debug/tempo-xtask create-zone --output generated/my-zone --l1-rpc-url "$HTTP_RPC" --sequencer "$SEQUENCER_ADDR" --private-key "$SEQUENCER_KEY"
+target/debug/tempo-xtask set-encryption-key --l1-rpc-url "$HTTP_RPC" --portal "$PORTAL" --private-key "$SEQUENCER_KEY"
+```
+
+## Start a zone in release
+
+```bash
+RUST_LOG=warn just zone-up my-zone false release
+```
+
+Health check:
+
+```bash
+cast block-number --rpc-url http://localhost:8546
+```
+
+Read deployment metadata:
+
+```bash
+jq '{zoneId, portal, tempoAnchorBlock, zoneFactory, swapAndDepositRouter, sequencerAddress}' generated/my-zone/zone.json
+```
+
+## Direct deposit + withdrawal validation
+
+Set the active portal first:
+
+```bash
+export L1_PORTAL_ADDRESS="$(jq -r '.portal' generated/my-zone/zone.json)"
+```
+
+Approve the L1 portal before depositing:
+
+```bash
+just max-approve-portal
+```
+
+Send a deposit to the zone:
+
+```bash
+just send-deposit 1000000
+```
+
+Approve the L2 outbox before withdrawing:
+
+```bash
+just max-approve-outbox
+```
+
+Request a withdrawal back to L1:
+
+```bash
+just send-withdrawal 400000
+```
+
+`just send-withdrawal` only waits for L1 finalization if both `L1_RPC_URL` and `L1_PORTAL_ADDRESS` are set.
+
+## Router validation flow
+
+Deploy the router:
+
+```bash
+just deploy-router my-zone
+```
+
+Run the demo with defaults:
+
+```bash
+just demo-swap-and-deposit my-zone
+```
+
+If you need overrides, pass them positionally because the current recipe treats them as positional args:
+
+```bash
+just demo-swap-and-deposit my-zone 100000000 0 http://localhost:8546
+```
+
+Direct xtask equivalent:
+
+```bash
+target/debug/tempo-xtask demo-swap-and-deposit \
+  --zone-dir generated/my-zone \
+  --l1-rpc-url "$HTTP_RPC" \
+  --zone-rpc-url http://localhost:8546 \
+  --private-key "$PRIVATE_KEY" \
+  --amount 100000000 \
+  --tick 0
+```
+
+## Sync debugging
+
+Tail the zone log:
+
+```bash
+tail -f /tmp/tempo-zone-my-zone*/logs/*/reth.log
+```
+
+Useful patterns:
+
+```bash
+rg -n "Prepared L1 block deposits|Including advanceTempo|TokenEnabled|DepositProcessed|WithdrawalProcessed" /tmp/tempo-zone-my-zone*/logs/*/reth.log
+```
+
+When `demo-swap-and-deposit` stalls at token enablement:
+
+1. Get the L1 tx block for the `enableToken` tx:
+
+```bash
+cast receipt <tx-hash> --rpc-url "$HTTP_RPC"
+```
+
+2. Compare it with the latest processed L1 block in the log:
+
+```bash
+tail -n 200 /tmp/tempo-zone-my-zone*/logs/*/reth.log | rg "Prepared L1 block deposits|Including advanceTempo"
+```
+
+If the zone is still behind the tx block, wait longer or rerun the test with a `release` node.
+
+## Known failure modes
+
+- `swapAndDepositRouter not found`: run `just deploy-router <name>` or pass `--router`.
+- Missing sequencer key: read `sequencerKey` from `generated/<name>/zone.json` or set `SEQUENCER_KEY`.
+- Timeout waiting for `TokenEnabled`: the zone is usually still catching up.
+- Restart crash with `failed to seed transferPolicyId ... Uninitialized`: inspect `crates/tempo-zone/src/l1_state/tip403/cache.rs` and prefer a fresh zone for smoke tests involving temporary tokens.

.config/nextest.toml

@@ -0,0 +1,10 @@
+[profile.ci]
+fail-fast = false
+retries = 2
+test-threads = "num-cpus"
+
+# Integration tests spin up full reth nodes — limit concurrency to avoid
+# resource contention and flaky timeouts on CI runners.
+[[profile.ci.overrides]]
+filter = "test(/^(e2e|l1_e2e|restart_e2e)::/) | test(advance_tempo)"
+threads-required = 8

.config/zepter.yaml

@@ -0,0 +1,39 @@
+version:
+  format: 1
+  # Minimum zepter version that is expected to work. This is just for printing a nice error
+  # message when someone tries to use an older version.
+  binary: 0.13.2
+
+# The examples in the following comments assume crate `A` to have a dependency on crate `B`.
+workflows:
+  check:
+    - [
+        "lint",
+        # Check that `A` activates the features of `B`.
+        "propagate-feature",
+        # These are the features to check:
+        "--features=std,op,asm-keccak,jemalloc,jemalloc-prof,serde-bincode-compat,serde,test-utils,arbitrary,bench,reth-codec,min-error-logs,min-warn-logs,min-info-logs,min-debug-logs,min-trace-logs,otlp,js-tracer",
+        # Do not try to add a new section to `[features]` of `A` only because `B` exposes that feature. There are edge-cases where this is still needed, but we can add them manually.
+        "--left-side-feature-missing=ignore",
+        # Ignore the case that `A` is outside of the workspace. Otherwise it will report errors in external dependencies that we have no influence on.
+        "--left-side-outside-workspace=ignore",
+        # Auxiliary flags:
+        "--offline",
+        "--locked",
+        "--show-path",
+        "--quiet",
+      ]
+  default:
+    # Running `zepter` with no subcommand will check & fix.
+    - [$check.0, "--fix"]
+
+# Will be displayed when any workflow fails:
+help:
+  text: |
+    Tempo uses the Zepter CLI to detect abnormalities in Cargo features, e.g. missing propagation.
+
+    It looks like one or more checks failed; please check the console output.
+
+    You can try to automatically address them by installing zepter (`cargo install zepter --locked`) and simply running `zepter` in the workspace root.
+  links:
+    - "https://github.com/ggwpez/zepter"

.dockerignore

@@ -0,0 +1,5 @@
+**/.git
+contrib/
+docs/
+localnet/
+scripts/

.envrc

@@ -0,0 +1 @@
+export AMP_TOOLBOX=".amp/tools"

.gitattributes

@@ -0,0 +1,6 @@
+* text=auto
+.gitattributes !filter !diff
+
+.env.example linguist-language=Dotenv
+Dockerfile.* linguist-language=Dockerfile
+biome.json linguist-language=JSON-with-Comments

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @mattsse @0xKitsune