Contract Deployment

This guide is for users deploying their own contracts through the proxy. If you're an operator rolling out the Open Privacy Suite stack itself (compose manifests, secrets, trust zones), see Operator Deployment instead.

The proxy validates all transactions at runtime using debug_traceCall, so deploying is nearly identical to deploying on any public chain.

Prerequisites

• User account with deploy permission in an organization
• JWT access token (obtained from web UI after ZK proof authentication)
• Foundry or Hardhat installed

Steps

# Set the authorization header for all RPC requests
export ETH_RPC_HEADERS="Authorization: Bearer YOUR_JWT_TOKEN_HERE"

# Set the RPC URL
export ETH_RPC_URL="http://localhost:8080/rpc"

# Standard Foundry deployment -- no changes needed
forge script script/Deploy.s.sol \
  --rpc-url $ETH_RPC_URL \
  --broadcast \
  --private-key $PRIVATE_KEY

forge script script/Deploy.s.sol \
  --rpc-url $ETH_RPC_URL \
  --broadcast \
  --account myKeystore \
  --sender 0xYourAddress

Deploy with Hardhat (Alternative)

// hardhat.config.js
module.exports = {
  networks: {
    privacy: {
      url: process.env.ETH_RPC_URL,
      httpHeaders: {
        "Authorization": `Bearer ${process.env.PRIVACY_TOKEN}`
      },
      accounts: [process.env.PRIVATE_KEY]
    }
  }
};

export PRIVACY_TOKEN="YOUR_JWT_TOKEN_HERE"
npx hardhat run scripts/deploy.js --network privacy

Deploy with Cast (Alternative)

# Single contract deployment
cast send --create \
  --rpc-url $ETH_RPC_URL \
  --private-key $PRIVATE_KEY \
  $(cat out/MyContract.sol/MyContract.bin)

How It Works

When you send a transaction through the proxy:

Auto-Registration After Deployment

Contracts deployed through the proxy are automatically registered in the RBAC system. No manual registration step is required.

Prerequisites: The deployer must be a member of a group with the deploy claim in their org. An admin creates this group and adds deployers to it before they start deploying.

Plain CREATE deployments (eth_sendTransaction without to):

1. Proxy verifies the user has the deploy claim (403 if not).
2. Proxy computes the deterministic CREATE address from keccak256(rlp([sender, nonce])) before forwarding.
3. Address is immediately pre-registered to the deployer's org (closes the cross-org access window).
4. Transaction is forwarded to the node.
5. On successful mining: pre-registration is finalized as a full Contract record (auto_registered: true, via: plain_create). A contract_grant is added to the deployer's existing deploy group — no new group is created.
6. On revert: pre-registration is cleaned up.

Token Refresh

Access tokens expire after 5 minutes (production; dev/mockauth builds use 30 minutes). To refresh:

# Get a new token from the web UI, or use the refresh endpoint:
curl -X POST http://localhost:8080/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'

# Update your environment
export ETH_RPC_HEADERS="Authorization: Bearer NEW_ACCESS_TOKEN"

Troubleshooting

Security Model

• Cross-org calls: Contract in Org A cannot call contract in Org B.
• Intra-org calls: Contracts within the same org can call each other freely.
• Shared infrastructure: Approved shared contracts accessible to all orgs.
• Precompiles: Standard EVM precompiles (0x01--0x09) are always allowed.

Production Deployment

This section covers production hardening considerations beyond contract deployment. For the full production checklist, see Security. For environment variable reference, see Configuration.

HTTPS and Private Networks

The proxy enforces HTTPS for the FRONTEND_URL in production (ENVIRONMENT=production). However, private network addresses are exempt from this requirement -- HTTP is allowed when the URL points at:

• RFC1918 private addresses (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
• Tailscale addresses (100.64.0.0/10)
• IPv6 Unique Local Addresses (ULA, fc00::/7)

This allows local and VPN-based development/staging environments to run without TLS while still enforcing HTTPS for internet-facing deployments.

Frontend in Production

In production, the admin frontend is served by nginx (not the Vite development server). The nginx container listens on port 80 internally and serves the pre-built static assets. The production Docker Compose file configures this automatically. Do not use the Vite dev server (proxy-frontend on port 5173) in production -- it is not designed for production traffic and exposes debugging features.

Explorer Database Graceful Degradation

The backend starts successfully even if the explorer database is unavailable. It logs a warning and continues serving all non-explorer endpoints, retrying the connection in the background. Explorer API endpoints return errors until the connection is established.

This supports deployment scenarios where the explorer database is provisioned after the proxy.