Tempo Testnet Harness

Production-style Python and DevOps harness for testing the current Tempo public testnet.

This repository is built for people who want:

• a clear Tempo testnet automation project they can actually run
• a public Web3 + DevOps reference project with Docker, CI, metrics, and Kubernetes examples
• a safe multi-wallet workflow where each wallet is handled independently

The harness uses only official Tempo surfaces and the stack stays inside your resume profile:

• Python
• Solidity
• DevOps tooling

Why This Project Is Useful

You can use this repository to:

• test Tempo’s public Moderato testnet from faucet funding through on-chain actions
• discover current official testnet tokens and recently verified contracts
• deploy a Tempo-native TIP-20 token with one wallet
• test swaps on Tempo’s Stablecoin DEX
• test maker liquidity placement, cancellation, and withdrawal on Tempo’s DEX
• test Fee Manager liquidity mint and burn cycles
• optionally deploy a simple Solidity contract with Foundry
• study how to package a Web3 automation service with Docker, Prometheus, GitHub Actions, and Kubernetes

Current Official Tempo Surface Used

The repository is aligned to the current public Tempo testnet as checked on March 2, 2026:

• network: Tempo Testnet (Moderato)
• chain ID: 42431
• RPC: https://rpc.moderato.tempo.xyz
• explorer: https://explore.tempo.xyz
• token list: https://tokenlist.tempo.xyz/list/42431
• contract verification API: https://contracts.tempo.xyz

Official predeployed contracts used by this repo:

• TIP-20 Factory: 0x20fc000000000000000000000000000000000000
• Fee Manager: 0xfeec000000000000000000000000000000000000
• Stablecoin DEX: 0xdec0000000000000000000000000000000000000

Official built-in testnet tokens currently discovered from the Tempo token list:

• pathUSD
• alphaUSD
• betaUSD
• thetaUSD

Important Scope Boundary

This repository is intentionally limited to documented and public Tempo flows.

It does:

• use the official Tempo faucet RPC method
• use the official token list API
• use the official contract verification API
• interact with official Tempo system contracts
• interact with a wallet’s own deployed TIP-20 token

It does not:

• transfer funds between your own wallets
• merge balances or reuse wallet state across wallets
• auto-interact with arbitrary random contracts from explorer scraping
• pretend unsupported integrations exist

As of March 2, 2026, this repo does not include staking or lending modules because I did not find a stable public Tempo staking or lending flow in the official Tempo docs and repos. I would rather leave that out than fake it.

Multi-Wallet Safety Rule

Each private key is treated as a fully independent wallet.

That means:

• one wallet is loaded from each TEMPO_PRIVATE_KEY_* environment variable
• every wallet gets its own cached state file under data/state
• the workflow never sends tokens from one wallet to another wallet
• the workflow never uses one wallet as liquidity counterparty for another wallet

What The Harness Does

For each wallet, the live workflow currently performs:

1. call Tempo’s faucet funding RPC method
2. fetch current Tempo token list and recent verified contract data
3. deploy one deterministic TIP-20 token for that wallet through the official factory
4. grant issuer role to that wallet on its own TIP-20 token
5. mint test tokens to that wallet
6. perform an official swap from alphaUSD to betaUSD
7. create a DEX pair for the wallet’s TIP-20 token
8. place a maker order on the Stablecoin DEX
9. cancel that maker order
10. withdraw the returned DEX internal balance
11. mint Fee Manager liquidity using the wallet’s TIP-20 token and alphaUSD
12. burn that liquidity back out

Optional extra path:

• deploy a plain Solidity sample contract with Foundry

Transaction Count Per Wallet

Current live-mode estimate per wallet:

• first fresh live cycle: 14 wallet-signed transactions
• steady-state live cycle after setup is already done: 6 wallet-signed transactions
• optional sample Solidity contract deploy: +1 on the first cycle only when enabled

Important faucet note:

• the faucet request is an RPC call, not a wallet-signed transaction
• Tempo may still create 0 or 1 external funding transaction on chain for that faucet request

First fresh live cycle breakdown:

• TIP-20 factory flow: 3
• official swap flow: 2
• DEX liquidity cycle: 5
• Fee Manager liquidity cycle: 4

Steady-state live cycle breakdown:

• TIP-20 factory flow: 0
• official swap flow: 1
• DEX liquidity cycle: 3
• Fee Manager liquidity cycle: 2

These estimates assume:

• first fresh cycle means no existing TIP-20 token, no approvals, and no DEX pair yet
• steady state means the token, approvals, and DEX pair already exist
• Tempo contract behavior remains the same

Validated Locally

This repo was validated locally before publishing with:

• make ci-local
• docker build -t tempo-testnet-harness .
• container startup check against GET /health
• real live smoke test on the current Tempo Moderato testnet using a throwaway wallet

The live smoke test succeeded for:

• faucet funding
• TIP-20 token deployment
• issuer role grant
• TIP-20 mint
• official alphaUSD -> betaUSD swap
• DEX pair creation
• DEX place / cancel / withdraw cycle
• Fee Manager mint / burn cycle
• generic Foundry deployment of the sample Solidity contract

API Endpoints

When the service is running, it exposes:

• GET /health
• GET /state
• GET /report
• GET /metrics

Example checks:

curl http://localhost:8000/health
curl http://localhost:8000/state
curl http://localhost:8000/report
curl http://localhost:8000/metrics

/state and /report now include:

• per-wallet cycle numbers
• per-wallet signed transaction counts for the last cycle
• total signed transactions for the last run
• cumulative runtime totals across all completed runs

Quick Start For Beginners (macOS / Linux)

1. Download the repository.
2. Open a terminal inside the project folder.
3. Run:

chmod +x easy_start.sh
./easy_start.sh

easy_start.sh will:

• create .venv
• upgrade pip
• install development dependencies
• copy .env.example to .env if needed
• start the API service

By default, the repo starts in:

• WORKFLOW_MODE=dry-run

That means the service loads discovery data and the workflow shape safely, but it does not send live transactions until you opt in.

Manual Setup

macOS / Linux

cp .env.example .env
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements-dev.txt
python -m app.main

Run one dry-run workflow and exit:

python -m app.main --run-once

Run one live workflow and exit:

WORKFLOW_MODE=live python -m app.main --run-once

Print the current transaction plan and exit:

python -m app.main --print-plan

Run live forever until you stop it:

WORKFLOW_MODE=live python -m app.main --run-forever --interval-seconds 900

Windows PowerShell

Copy-Item .env.example .env
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install --upgrade pip
py -m pip install -r requirements-dev.txt
py -m app.main

Run one live workflow:

$env:WORKFLOW_MODE="live"
py -m app.main --run-once

Run live forever:

$env:WORKFLOW_MODE="live"
py -m app.main --run-forever --interval-seconds 900

Windows Command Prompt

copy .env.example .env
py -m venv .venv
.\.venv\Scripts\activate.bat
py -m pip install --upgrade pip
py -m pip install -r requirements-dev.txt
py -m app.main

Run one live workflow:

set WORKFLOW_MODE=live
py -m app.main --run-once

Run live forever:

set WORKFLOW_MODE=live
py -m app.main --run-forever --interval-seconds 900

Docker Desktop Quick Start

1. Copy the environment file:

cp .env.example .env

2. Add at least one private key if you want live execution:

TEMPO_PRIVATE_KEY_1=0xyourprivatekeyhere

3. Start the service and Prometheus:

docker compose up -d --build

4. Check:

docker compose ps
curl http://localhost:8000/health
curl http://localhost:8000/report

Open:

• API health: http://localhost:8000/health
• workflow state: http://localhost:8000/state
• latest report: http://localhost:8000/report
• Prometheus: http://localhost:9090

Stop the stack:

docker compose down

Environment Variables

Copy .env.example to .env and then adjust only what you need.

Main values:

TEMPO_RPC_URL=https://rpc.moderato.tempo.xyz
TEMPO_CHAIN_ID=42431
TEMPO_EXPLORER_URL=https://explore.tempo.xyz
TEMPO_CONTRACTS_API_URL=https://contracts.tempo.xyz
TEMPO_TOKENLIST_URL=https://tokenlist.tempo.xyz/list/42431
API_HOST=0.0.0.0
API_PORT=8000
LOG_LEVEL=INFO
AUTO_RUN_ON_STARTUP=true
RUN_FOREVER=false
RUN_INTERVAL_SECONDS=0
WORKFLOW_MODE=dry-run
WORKFLOW_CONFIG_PATH=config/workflow.json
REPORT_PATH=data/reports/latest.json
STATE_DIRECTORY=data/state
REQUEST_TIMEOUT_SECONDS=20
RECEIPT_TIMEOUT_SECONDS=180
WALLET_DELAY_SECONDS=3
DISCOVERY_CONTRACT_LIMIT=12
DISCOVERY_RECENT_BLOCKS=15
ENABLE_DISCOVERY=true
ENABLE_TIP20_FACTORY_TEST=true
ENABLE_SAMPLE_CONTRACT_DEPLOY=false
TEMPO_PRIVATE_KEY_1=
TEMPO_PRIVATE_KEY_2=

Meaning of each important value:

• TEMPO_RPC_URL: Tempo RPC endpoint
• TEMPO_CHAIN_ID: current Tempo Moderato chain ID
• TEMPO_EXPLORER_URL: explorer base URL
• TEMPO_CONTRACTS_API_URL: contract verification and lookup API base
• TEMPO_TOKENLIST_URL: official Tempo token list endpoint
• API_HOST: FastAPI bind host
• API_PORT: FastAPI port
• AUTO_RUN_ON_STARTUP: automatically execute the workflow when the service starts
• RUN_FOREVER: keep running until you stop the process
• RUN_INTERVAL_SECONDS: set a positive number to run the workflow on a fixed interval
• WORKFLOW_MODE: dry-run or live
• WORKFLOW_CONFIG_PATH: workflow amounts and toggles
• REPORT_PATH: latest JSON report file
• STATE_DIRECTORY: per-wallet state cache directory
• DISCOVERY_CONTRACT_LIMIT: how many recent verified contracts to include in the report
• DISCOVERY_RECENT_BLOCKS: how many recent blocks to scan for active known contracts
• ENABLE_TIP20_FACTORY_TEST: enable Tempo-native TIP-20 deployment and related tests
• ENABLE_SAMPLE_CONTRACT_DEPLOY: enable optional Foundry deployment of HelloTempo.sol
• TEMPO_PRIVATE_KEY_*: one independent wallet per environment variable

Repeat behavior:

• RUN_FOREVER=false with RUN_INTERVAL_SECONDS=0: one cycle only when auto-started
• RUN_INTERVAL_SECONDS>0: repeat forever with that interval
• RUN_FOREVER=true with RUN_INTERVAL_SECONDS=0: repeat forever using the built-in fallback interval of 900 seconds

Recommended continuous live test example:

WORKFLOW_MODE=live
RUN_FOREVER=true
RUN_INTERVAL_SECONDS=900
TEMPO_PRIVATE_KEY_1=0xyourprivatekeyhere

Workflow Configuration

The main workflow amounts live in config/workflow.json.

Current defaults:

• official swap: alphaUSD -> betaUSD
• swap amount: 1000000 raw units
• TIP-20 quote token: alphaUSD
• TIP-20 mint amount: 250000000
• DEX order amount: 100000000
• DEX order tick: 10
• Fee Manager validator token: alphaUSD
• Fee Manager validator amount: 1000000

You can tune those values without changing the code.

Optional Solidity Deployment

This repo also includes a plain Solidity contract at HelloTempo.sol.

Build it:

forge build

Deploy it with the helper script:

VERIFY=false ./scripts/deploy_sample_contract.sh https://rpc.moderato.tempo.xyz <PRIVATE_KEY> "Hello from Tempo"

If you want verification submission through Tempo’s contract verification service, set:

VERIFY=true

The helper script uses:

• forge create
• --broadcast
• Tempo’s RPC endpoint
• Tempo’s contract verification service when verification is enabled

DevOps Features Included

This repo includes:

• Docker image
• Docker Compose stack
• Prometheus scrape target
• GitHub Actions CI
• Kubernetes deployment example
• Makefile for common workflows
• structured JSON report output
• per-wallet local state caching

Makefile Commands

make install-dev
make run
make run-once
make run-live
make run-live-forever
make plan
make test
make lint
make forge-build
make docker-build
make ci-local

Project Layout

app/                        Python service and Tempo workflow logic
config/workflow.json        Workflow amounts and feature toggles
data/                       Runtime reports and wallet state
deploy/kubernetes/          Kubernetes example
prometheus/                 Prometheus scrape config
scripts/                    Helper scripts
src/                        Solidity sample contract
.github/workflows/          CI pipeline

Public Benefit Notes

This repository is meant to be understandable and reusable by normal developers who want a clean Tempo testnet example.

The goal is:

• clear setup
• clear environment handling
• safe wallet separation
• official contract usage
• public benefit through readable code and reproducible infrastructure