# polybase/payy architecture

> Architecture diagram of the GitHub repository polybase/payy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/polybase/payy
- Repository: https://github.com/polybase/payy

## Overview

Payy is a privacy-preserving, Ethereum-compatible ZK rollup. Its principal transaction path is a client preparing privacy proofs and interacting with the rollup, with aggregation and node services supporting rollup operation; the README identifies Ethereum contracts and the prover as core services. The tree also shows a wallet onboarding vault, payment-link frontend, and network explorer. Some core Rust implementations are not in the supplied tree, so subsystem paths and relationships not demonstrated by excerpts or README are left broad or unconnected.

Main entry points: [`pkg/aggregator-cli/src/main.rs`](https://github.com/polybase/payy/blob/main/pkg/aggregator-cli/src/main.rs) (Aggregator entry), [`app/packages/payy-client/src/client.ts`](https://github.com/polybase/payy/blob/main/app/packages/payy-client/src/client.ts) (Payy client), [`pkg/node`](https://github.com/polybase/payy/tree/main/pkg/node) (Rollup node), [`app/packages/privacy-vault/src/App.tsx`](https://github.com/polybase/payy/blob/main/app/packages/privacy-vault/src/App.tsx) (Privacy vault)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and wallet"]
  node_payy_client["Payy client<br/>[client.ts]"]
  node_client_bridge["Bridge access<br/>[bridge.ts]"]
  node_client_crypto["Privacy cryptography<br/>[crypto.ts]"]
  node_client_links["Link utilities<br/>[links.ts]"]
end

subgraph group_web["Web applications"]
  node_vault["Privacy vault<br/>[App.tsx]"]
  node_wallet_auth["Wallet authentication<br/>[useWalletAuth.ts]"]
  node_link_app["Payment links"]
  node_explorer["Network explorer"]
end

subgraph group_rollup["Rollup services"]
  node_aggregator_cli["Aggregator entry<br/>[main.rs]"]
  node_aggregator_config["Aggregator config<br/>[config.rs]"]
  node_aggregator_runner["Aggregation runtime<br/>[runner.rs]"]
  node_node["Rollup node"]
end

subgraph group_chain["Ethereum and proofs"]
  node_prover["Proof generation"]
  node_contracts["Ethereum contracts"]
  node_ethereum(("Ethereum"))
end

node_wallet_user(("Wallet user"))

node_wallet_user -->|"uses"| node_vault
node_vault -->|"authenticates"| node_wallet_auth
node_payy_client -->|"computes proofs"| node_client_crypto
node_payy_client -->|"reads bridge"| node_client_bridge
node_payy_client -->|"uses link helpers"| node_client_links
node_aggregator_cli -->|"loads config"| node_aggregator_config
node_aggregator_cli -->|"starts runtime"| node_aggregator_runner
node_aggregator_cli -->|"connects to node"| node_node
node_aggregator_cli -->|"loads rollup contract"| node_contracts
node_payy_client -.->|"requests proofs"| node_prover
node_node -.->|"uses proving service"| node_prover
node_contracts -.->|"verifies transitions"| node_ethereum
node_aggregator_cli -.->|"aggregates rollup"| node_node

click node_vault "https://github.com/polybase/payy/blob/main/app/packages/privacy-vault/src/App.tsx"
click node_wallet_auth "https://github.com/polybase/payy/blob/main/app/packages/privacy-vault/src/features/auth/useWalletAuth.ts"
click node_link_app "https://github.com/polybase/payy/tree/main/app/packages/link/src/app"
click node_explorer "https://github.com/polybase/payy/tree/main/app/packages/network/src/app"
click node_payy_client "https://github.com/polybase/payy/blob/main/app/packages/payy-client/src/client.ts"
click node_client_bridge "https://github.com/polybase/payy/blob/main/app/packages/payy-client/src/bridge.ts"
click node_client_crypto "https://github.com/polybase/payy/blob/main/app/packages/payy-client/src/crypto.ts"
click node_client_links "https://github.com/polybase/payy/blob/main/app/packages/payy-client/src/links.ts"
click node_aggregator_cli "https://github.com/polybase/payy/blob/main/pkg/aggregator-cli/src/main.rs"
click node_aggregator_config "https://github.com/polybase/payy/blob/main/pkg/aggregator-cli/src/config.rs"
click node_aggregator_runner "https://github.com/polybase/payy/blob/main/pkg/aggregator-cli/src/runner.rs"
click node_node "https://github.com/polybase/payy/tree/main/pkg/node"
click node_prover "https://github.com/polybase/payy/tree/main/pkg/prover"
click node_contracts "https://github.com/polybase/payy/tree/main/eth"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_payy_client,node_client_bridge,node_client_crypto,node_client_links,node_wallet_user toneBlue
class node_vault,node_wallet_auth,node_link_app,node_explorer toneAmber
class node_aggregator_cli,node_aggregator_config,node_aggregator_runner,node_node toneMint
class node_prover,node_contracts,node_ethereum toneRose
```

## Components

### Client and wallet

- [Payy client](https://github.com/polybase/payy/blob/main/app/packages/payy-client/src/client.ts): `app/packages/payy-client/src/client.ts`
- [Bridge access](https://github.com/polybase/payy/blob/main/app/packages/payy-client/src/bridge.ts): `app/packages/payy-client/src/bridge.ts`
- [Privacy cryptography](https://github.com/polybase/payy/blob/main/app/packages/payy-client/src/crypto.ts): `app/packages/payy-client/src/crypto.ts`
- [Link utilities](https://github.com/polybase/payy/blob/main/app/packages/payy-client/src/links.ts): `app/packages/payy-client/src/links.ts`

### Web applications

- [Privacy vault](https://github.com/polybase/payy/blob/main/app/packages/privacy-vault/src/App.tsx): `app/packages/privacy-vault/src/App.tsx`
- [Wallet authentication](https://github.com/polybase/payy/blob/main/app/packages/privacy-vault/src/features/auth/useWalletAuth.ts): `app/packages/privacy-vault/src/features/auth/useWalletAuth.ts`
- [Payment links](https://github.com/polybase/payy/tree/main/app/packages/link/src/app): `app/packages/link/src/app`
- [Network explorer](https://github.com/polybase/payy/tree/main/app/packages/network/src/app): `app/packages/network/src/app`

### Rollup services

- [Aggregator entry](https://github.com/polybase/payy/blob/main/pkg/aggregator-cli/src/main.rs): `pkg/aggregator-cli/src/main.rs`
- [Aggregator config](https://github.com/polybase/payy/blob/main/pkg/aggregator-cli/src/config.rs): `pkg/aggregator-cli/src/config.rs`
- [Aggregation runtime](https://github.com/polybase/payy/blob/main/pkg/aggregator-cli/src/runner.rs): `pkg/aggregator-cli/src/runner.rs`
- [Rollup node](https://github.com/polybase/payy/tree/main/pkg/node): `pkg/node`

### Ethereum and proofs

- [Proof generation](https://github.com/polybase/payy/tree/main/pkg/prover): `pkg/prover`
- [Ethereum contracts](https://github.com/polybase/payy/tree/main/eth): `eth`
- **Ethereum**

### Other components

- **Wallet user**

## Connections

- Wallet user → Privacy vault: uses (evidence: `app/packages/privacy-vault/src/App.tsx`)
- Privacy vault → Wallet authentication: authenticates (evidence: `app/packages/privacy-vault/src/App.tsx`)
- Payy client → Privacy cryptography: computes proofs (evidence: `app/packages/payy-client/src/client.ts`)
- Payy client → Bridge access: reads bridge (evidence: `app/packages/payy-client/src/client.ts`)
- Payy client → Link utilities: uses link helpers (evidence: `app/packages/payy-client/src/client.ts`)
- Aggregator entry → Aggregator config: loads config (evidence: `pkg/aggregator-cli/src/main.rs`)
- Aggregator entry → Aggregation runtime: starts runtime (evidence: `pkg/aggregator-cli/src/main.rs`)
- Aggregator entry → Rollup node: connects to node (evidence: `pkg/aggregator-cli/src/main.rs`)
- Aggregator entry → Ethereum contracts: loads rollup contract (evidence: `pkg/aggregator-cli/src/main.rs`)
- Payy client → Proof generation: requests proofs
- Rollup node → Proof generation: uses proving service
- Ethereum contracts → Ethereum: verifies transitions (evidence: `README.md`)
- Aggregator entry → Rollup node: aggregates rollup (evidence: `README.md`)
