docs(readme): update zones description, getting started commands. (#362)

Author: 0xKitsune

README.md

@@ -1,109 +1,96 @@
-# Tempo Zones
+<!-- TODO: add logo -->
+<!-- <p align="center"><a href="https://tempo.xyz/zones"><img src="assets/logo.png" alt="Tempo Zones" width="400"></a></p> -->
 
-Zones are sidechains anchored to Tempo. Each zone has its own sequencer, genesis state, and portal contract that escrows deposits and processes withdrawals.
+<h1 align="center">Tempo Zones</h1>
 
-**Explorers:** [Moderato](https://explore.moderato.tempo.xyz/)
+---
 
-This repository contains the `tempo-zone` node, zone-specific precompiles and RPC support, and the `just` workflows for deploying and operating zones on Tempo.
+Zones are private blockchains anchored to [Tempo](https://github.com/tempoxyz/tempo), with native support for confidential balances and transactions. Zones inherit compliance from Tempo L1 and support interoperability with Tempo for moving assets in and out of zones.
 
-For the main Tempo repository, see [tempoxyz/tempo](https://github.com/tempoxyz/tempo).
+You can get started today by [deploying a zone](#getting-started) on Tempo testnet, reading the [full zone documentation](docs/ZONES.md), or exploring the [Zone specs](https://docs.tempo.xyz/protocol).
 
-## Quick Start
 
-Prerequisites:
+## What Makes Zones Interesting
 
-- [Rust toolchain](https://rustup.rs/)
-- [Foundry](https://book.getfoundry.sh/getting-started/installation) (`cast`, `forge`)
-- [`just`](https://github.com/casey/just#packages)
-- [`jq`](https://jqlang.github.io/jq/download/)
+- **Private balances and transactions.** State access requires account authentication at the RPC layer. This ensures that only the authorized account holder can access balances and transaction history. The zone operator maintains full visibility into state for compliance.
 
-Deploy and start a zone on Moderato:
+- **Encrypted deposits and withdrawals.** When depositing into a zone, users can encrypt the recipient to not reveal who receives funds inside the zone. Encrypted withdrawals are also possible, allowing the sender to be replaced with a commitment, preserving recipient verifiability without exposing the sender when withdrawing to Tempo mainnet.
 
-```bash
-export L1_RPC_URL="wss://rpc.moderato.tempo.xyz"
-just deploy-zone my-zone
-```
+- **Zone to zone transfers.** Zones interoperate with Tempo Mainnet via withdrawals with optional calldata. Withdrawal calldata can execute on Tempo and deposit into another zone, enabling flows like zone to zone transfers or executing a swap between sending amounts to another zone.
 
-To choose a different initial TIP-20 on the portal at deploy time, pass it as the second positional argument:
+- **Compliance inherited from Tempo Mainnet.** [TIP-403](https://docs.tempo.xyz/protocol/tip403/overview) policies (whitelist, blacklist) are mirrored from Tempo and enforced on zones. Issuers set the policy once on Tempo and the zone picks it up automatically. If an issuer freezes an address or updates a blacklist on Tempo, the zone inherits the change in the next block.
 
-```bash
-just deploy-zone my-zone alphausd
-```
+- **Fast withdrawals.** The zone processes transactions every 250ms and submits batches of withdrawals to Tempo, where blocks are produced every ~500ms. Once batches are accepted and the attached proof is validated, withdrawals are processed and funds are released from escrow.
 
-`just deploy-zone` will:
 
-- Generate a fresh sequencer keypair
-- Fund the sequencer via `tempo_fundAddress`
-- Build the Solidity specs
-- Deploy a zone via `ZoneFactory`
-- Generate `generated/<name>/genesis.json` and `generated/<name>/zone.json`
-- Register the sequencer encryption key and start the zone node
+## Getting Started
 
-### Key Addresses
+Prerequisites: [Rust](https://rustup.rs/), [Foundry](https://book.getfoundry.sh/getting-started/installation), [`just`](https://github.com/casey/just#packages), [`jq`](https://jqlang.github.io/jq/download/)
 
-| Contract | Address | Explorer |
-|----------|---------|----------|
-| ZoneFactory (moderato) | `0x7Cc496Dc634b718289c192b59CF90262C5228545` | [View on Moderato explorer](https://explore.moderato.tempo.xyz/address/0x7Cc496Dc634b718289c192b59CF90262C5228545) |
 
-`just create-zone`, `just deploy-zone`, and `just zone-info` default to this Moderato `ZoneFactory`. `just deploy-router` also falls back to it when `zone.json` does not already include `zoneFactory`.
+## Deploying a Zone
 
-`zone.json` stores the deployed portal address, zone ID, anchor block, and sequencer metadata used by later commands such as `just zone-up` and `just deploy-router`.
+```bash
+# Deploy and start a zone on Moderato testnet
+export L1_RPC_URL="wss://rpc.moderato.tempo.xyz"
+just deploy-zone my-zone
+```
 
-To restart the same zone later:
+The `deploy-zone` command generates a sequencer keypair, funds it on L1, deploys the portal via `ZoneFactory`, generates genesis, and starts the node.
 
 ```bash
-just zone-up my-zone false release
+# Start/restart a zone after initial deployment
+just zone-up my-zone
 ```
 
-## Query the Private RPC
+## Depositing into a Zone
 
-With `PRIVATE_KEY` set to your zone wallet, you can hit the private RPC on `http://localhost:8544` with a one-liner. `just zone-auth-token` reads `generated/<name>/zone.json`, signs a short-lived auth token, and `cast rpc` passes it through the `X-Authorization-Token` header:
+```bash
+export L1_PORTAL_ADDRESS=$(jq -r '.portal' generated/my-zone/zone.json)
+just max-approve-portal
+
+# deposit into the zone
+just send-deposit 1000000                       # deposit to your own address
+just send-deposit 1000000 <recipient-address>   # deposit to a specific address
+```
 
 ```bash
-cast rpc zone_getAuthorizationTokenInfo \
-  --rpc-url http://localhost:8544 \
-  --rpc-headers "X-Authorization-Token: $(just zone-auth-token my-zone)"
+# send an encrypted deposit
+just send-deposit-encrypted 1000000                       # to your own address
+just send-deposit-encrypted 1000000 <recipient-address>   # to a specific address
 ```
 
-See [docs/ZONES.md](docs/ZONES.md) for more private RPC examples, including reusable tokens and `eth_call` queries.
+## Withdrawing from Zone to Tempo
 
-## How Zones Work
+```bash
 
-- A zone sequencer subscribes to Tempo for headers, deposits, and token-enablement events, including backfill from the zone's anchor block.
-- The zone builds one sidechain block per Tempo block, processing Tempo-driven state transitions through system transactions before app transactions.
-- The zone monitor batches zone blocks back to Tempo and processes withdrawals from the zone back to Tempo users.
+# withdraw from the zone
+just max-approve-outbox
+just send-withdrawal 1000000 <recipient-address>  # withdraw to a specific address
+```
 
-## More Docs
+The sequencer includes the withdrawal in the next batch submission to L1 and processes it automatically.
 
-See [docs/ZONES.md](docs/ZONES.md) for:
 
-- Step-by-step setup and deployment
-- Deposits, withdrawals, and private RPC usage
-- Router demos and TIP-403 policy flows
-- Architecture, configuration, and command reference
+## Querying the Private RPC
 
-## Development
+Zone balances are private by default. Every RPC request must include a signed authorization token that proves you control the querying account.
+
+`just zone-auth-token` reads `generated/<name>/zone.json` and signs a short-lived auth token:
 
 ```bash
-git clone https://github.com/tempoxyz/zones.git
-cd zones
-cargo build --bin tempo-zone
-cargo test --workspace
-```
 
-The main binary in this repository is `tempo-zone`:
+# generate an auth token
+export PRIVATE_KEY=<zone-wallet-private-key>
+export TOKEN=$(just zone-auth-token my-zone)
 
-```bash
-cargo run --bin tempo-zone -- node --help
+# query your TIP-20 balance 
+just check-balance-private my-zone <token-address>
 ```
 
-## Contributing
-
-Our contributor guidelines can be found in [`CONTRIBUTING.md`](https://github.com/tempoxyz/tempo?tab=contributing-ov-file).
 
-## Security
+See [docs/ZONES.md](docs/ZONES.md) for the full guide on deposits, withdrawals, private RPC, router demos, TIP-403 policy flows, and command references.
 
-See [`SECURITY.md`](https://github.com/tempoxyz/tempo?tab=security-ov-file). Note: Tempo is still undergoing audit and does not have an active bug bounty. Submissions will not be eligible for a bounty until audits have concluded.
 
 ## License