Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/covenant-gov/pacto-app/llms.txt

Use this file to discover all available pages before exploring further.

Pacto uses a small set of environment variables to configure RPC providers and wallet-related UI behaviour. All variables are optional for basic development — the app ships curated public RPC fallbacks for every supported network and works without any keys set. For production deployments or chain-dependent features such as wallet sends and on-chain governance, you should supply at least ALCHEMY_RPC_KEY.

​
Getting started

Copy the example file to create your local environment file (it is already listed in .gitignore): 
cp .env.example .env
Open .env in your editor and uncomment the variables you need. The file ships empty by design — all settings are optional.

​
Environment variables

VariableRequiredDefaultDescription
ALCHEMY_RPC_KEYNo—Alchemy API key. When set, Pacto builds a per-chain RPC URL of the form https://{host}.g.alchemy.com/v2/{key} for every supported network, then appends curated public fallbacks. One key covers all supported chains.
POCKET_RPC_KEYNo—Pocket Network RPC key. Alternative provider following the same host-map pattern as Alchemy. Add this to extend RPC_PROVIDERS in rpc-providers.ts and the Rust provider module.
VITE_WALLET_RPC_DOCS_URLNo—URL surfaced inside the wallet UI as a documentation link for RPC configuration help. Exposed to the Vite frontend via the VITE_ prefix; has no effect on backend behaviour.
All three variables are optional during UI development. The app resolves public fallback RPC URLs automatically via rpc-catalog.ts (frontend) and wallet_chain_config.rs (Rust backend) whenever no provider key is present.

​
Alchemy per-chain URL mapping

When ALCHEMY_RPC_KEY is set, Pacto constructs the following URLs for each network:
Network keyAlchemy hostFull URL pattern
mainneteth-mainnethttps://eth-mainnet.g.alchemy.com/v2/{ALCHEMY_RPC_KEY}
sepoliaeth-sepoliahttps://eth-sepolia.g.alchemy.com/v2/{ALCHEMY_RPC_KEY}
arbitrumarb-mainnethttps://arb-mainnet.g.alchemy.com/v2/{ALCHEMY_RPC_KEY}
optimismopt-mainnethttps://opt-mainnet.g.alchemy.com/v2/{ALCHEMY_RPC_KEY}
gnosisgnosis-mainnethttps://gnosis-mainnet.g.alchemy.com/v2/{ALCHEMY_RPC_KEY}
The host-to-network mapping lives in src/lib/wallet/rpc-providers.ts (frontend) and src-tauri/src/evm/wallet_rpc_providers.rs (backend). Adding a new chain requires adding an entry in both files.

​
RPC resolution order

The effective RPC URL list for a given chain is assembled in priority order:
  1. Operator provider key — if ALCHEMY_RPC_KEY is set, the Alchemy URL for that chain is placed first, followed by curated public fallbacks as a safety net.
  2. User preferences — personal RPC URLs configured in Settings → EVM are always tier 2 in the resolution list. They override the curated public defaults but never override a key supplied by the operator. When an operator key is present, user preferences are effectively bypassed because the operator key (with curated fallbacks appended) already covers all chains.
  3. Curated public defaults — URLs from rpc-catalog.ts (frontend) and wallet_chain_config.rs (backend) are always appended as the final fallback tier.
The frontend merge point is getEffectiveRpcUrlsForChain(chainId) in src/lib/wallet/chains.ts. The backend equivalent is in wallet_rpc_providers.rs.

​
How environment variables are consumed

Pacto reads these variables in two separate layers: Frontend (Vite / TypeScript) Vite exposes variables matching the ALCHEMY_* prefix via envPrefix in vite.config.ts. The resolution logic lives in src/lib/wallet/rpc-providers.ts, which builds the per-chain URL map and passes it into getEffectiveRpcUrlsForChain. The VITE_WALLET_RPC_DOCS_URL variable is available as import.meta.env.VITE_WALLET_RPC_DOCS_URL anywhere in the Svelte layer. Backend (Rust / Tauri) The Rust backend reads ALCHEMY_RPC_KEY directly at runtime via std::env::var inside src-tauri/src/evm/wallet_rpc_providers.rs. The same key that serves frontend reads also drives the backend eth_sendRawTransaction path (Alloy-based signing and broadcasting). There is no separate backend-specific key variable.

​
Local development

For pure UI development — component work, layout, Nostr messaging — no keys are needed at all. The app uses public RPC fallbacks automatically. For chain-dependent features (wallet balance reads, transaction sends, governance contract deploys) you have two options: Option A — Set ALCHEMY_RPC_KEY Add your key to .env. This gives you stable, rate-limited access to all supported networks including Sepolia testnet, which is used for operator smoke testing. Option B — Run a local Anvil chain The pacto-dev-env Docker stack provides a local Anvil node (chain ID 31337) and a local Nostr relay. In Vite dev builds (import.meta.env.DEV) the app auto-wires the local stack once per session:
  • Adds ws://localhost:7000 as a custom Nostr relay.
  • Enables the Local Anvil chain in Settings → EVM.
  • Sets the default RPC for Local Anvil to http://localhost:8545.
cd dev-setup
mkdir -p data/relay
docker compose up -d --build
For full instructions including contract deployment on the local chain, see docs/wallet/PACTO-APP-LOCAL-CHAIN-SETUP.md.
Arbitrum is the product-default preferred network in Settings → EVM. For production-like testing on Arbitrum, ALCHEMY_RPC_KEY is strongly recommended — public RPC endpoints can be rate-limited under sustained use.

​
PACTO_* contract address overrides

Beyond RPC configuration, the Rust backend supports optional environment variables that override the deployed contract addresses normally read from src/lib/evm/pacto-protocol-addresses.json. These are useful for local Anvil experiments without editing the JSON file: 
export PACTO_NAVE_PIRATA_FACTORY=0x...
export PACTO_NAV_MASTER_QUARTERMASTER=0x...
export PACTO_NAV_MASTER_MUTINY=0x...
export PACTO_NAV_MASTER_TREASURY_AUTHORITY=0x...
export PACTO_NAV_MASTER_SQUAD_ADMIN=0x...
export PACTO_NAV_MASTER_SQUAD_ADMIN_EXT=0x...
export PACTO_HATS=0x...
export PACTO_ROLE_HAT_CLONES_FACTORY=0x...
export PACTO_ROLE_HAT_UPGRADER=0x...
export PACTO_NAVE_PIRATA_REGISTRY=0x...
Resolution order for each address field: PACTO_* env override → pacto-protocol-addresses.json → error (required fields) or safe-global defaults (Safe factory only).
PACTO_* overrides are resolved at runtime by the Rust backend. They are useful for one-off testing. For persistent local setups or shared environments, editing pacto-protocol-addresses.json directly is preferred — env overrides are not visible to other developers using the same build.
See Protocol Addresses for the full address book reference.

​
Security

Never commit .env to git. The file is listed in .gitignore for this reason. API keys committed to source control are a serious security incident.Never log full RPC URLs. RPC URLs constructed from ALCHEMY_RPC_KEY contain the API key in the path segment. The backend must not echo full URLs in returned errors or structured logs. Use src-tauri/src/wallet_security.rs when formatting any RPC-related error messages.Never log decrypted EVM private key hex. The EVM private key is decrypted only for approved signing operations inside the Tauri backend. The comment at the decrypt site in wallet_ops.rs documents this constraint explicitly.

Build docs developers (and LLMs) love

Get started for freeTalk to us