Documentation Index
Fetch the complete documentation index at: https://docs.arcpass.vibepas.xyz/llms.txt
Use this file to discover all available pages before exploring further.
ArcPass reads its entire configuration from environment variables at startup. There are no configuration files to edit — every behavior you need to change is controlled by setting the appropriate variable before launching the API or worker process. Copy .env.example from the repository root and fill in the required values before your first deployment.
Never commit SPONSOR_PRIVATE_KEY to version control. This key controls the relay operator account that holds and transfers gas funds on behalf of users. Treat it with the same care as a production wallet private key: store it in a secrets manager, CI secret, or encrypted vault — never in a .env file that is checked into a repository.
Database
| Variable | Required | Default | Description |
|---|
DATABASE_URL | Yes | — | PostgreSQL connection string for the ArcPass database. Example: postgresql://user:password@localhost:5432/arcpass |
Blockchain and network
These variables are required by the worker process. The API does not connect to the blockchain directly.
| Variable | Required | Default | Description |
|---|
CHAIN_RPC_URL | Worker | — | RPC endpoint for the Arc network. The worker connects here to submit relay transactions and verify the chain ID at startup. ARC_RPC_URL is accepted as a legacy fallback. |
SPONSOR_PRIVATE_KEY | Worker | — | Relay operator private key as 64 hex characters, with or without a 0x prefix. This account signs and pays for on-chain relay transactions. DEPLOYER_PRIVATE_KEY is accepted as a legacy fallback. |
CHAIN_ID | Worker | — | Chain ID of the target network. The worker checks this against the connected RPC endpoint at startup and exits if there is a mismatch. For the Arc testnet, use 5042002. |
CONTRACT_ADDRESS_SPONSOR_VAULT | Worker | — | Deployed address of the SponsorVault contract, which holds the gas treasury and executes authorized transfers. |
CONTRACT_ADDRESS_SPONSORSHIP_REGISTRY | Worker | — | Deployed address of the SponsorshipRegistry contract, which records on-chain sponsorship accounting. |
| Variable | Required | Default | Description |
|---|
SPONSORSHIP_AMOUNT_WEI | No | 1000000000000000 | Amount of native tokens to transfer per sponsorship, expressed in wei. The default is 0.001 tokens (1,000,000,000,000,000 wei). |
API
| Variable | Required | Default | Description |
|---|
PORT | No | 4000 | TCP port the Fastify API listens on. |
LOG_LEVEL | No | info | Pino log verbosity. Accepted values: trace, debug, info, warn, error, fatal, silent. |
CORS_ALLOWED_ORIGINS | No | — | Comma-separated list of origins the API accepts cross-origin requests from. When unset, CORS is not restricted. Example: https://app.example.com,https://staging.example.com |
Worker tuning
These variables control how aggressively the worker polls for work and how it handles timeouts and retries. The defaults are suitable for most deployments.
| Variable | Required | Default | Description |
|---|
POLL_INTERVAL_MS | No | 5000 | How often (in milliseconds) the worker checks for pending and stale sponsorship requests to process. |
BATCH_SIZE | No | 20 | Maximum number of sponsorship requests the worker processes in a single cycle. |
MAX_RETRIES | No | 5 | Maximum number of times the worker retries a failed relay attempt before marking the request as permanently failed. |
LOCK_TIMEOUT_MS | No | 30000 | Timeout in milliseconds for the internal processing transaction per sponsorship request. |
TX_TIMEOUT_MS | No | 120000 | Timeout in milliseconds for waiting on an on-chain transaction receipt after the relay transaction is broadcast. |
CONFIRMATION_BLOCKS | No | 2 | Number of block confirmations to wait for before treating a relay transaction as finalized. |
Rate limiting
| Variable | Required | Default | Description |
|---|
RATE_LIMIT_IP_MAX | No | 10 | Maximum number of sponsorship requests allowed from a single IP address within the rate limit window. |
RATE_LIMIT_WALLET_MAX | No | 5 | Maximum number of sponsorship requests allowed from a single wallet address within the rate limit window. |
RATE_LIMIT_WINDOW_MS | No | 3600000 | Duration of the rate limit sliding window in milliseconds. The default is one hour (3,600,000 ms). |
RATE_LIMIT_BLOCK_DURATION_MS | No | 900000 | How long (in milliseconds) an IP or wallet is automatically blocked after exceeding the rate limit threshold. The default is 15 minutes (900,000 ms). |