System Contracts

System contracts are contract records whose metadata comes from a hardcoded registry inside Prividium™. The system manages their address, ABI, name, and configuration automatically. Administrators cannot create, edit, or delete system contracts through the API or Admin Dashboard.

Permissions (function and event access rules) work exactly like regular contracts. Administrators can assign, modify, and remove permission rules on system contracts without restriction.

How system contracts work

Registry

Prividium™ ships with a built-in registry of system contract definitions. Each entry specifies a contract address, ABI, name, description, disclosure settings, and templateId: null. All registry contracts belong to the zone, with organizationId: null. The registry includes:

Strict sync at startup

On every startup, Prividium™ runs a strict sync before serving traffic:

1. Upserts all registry contracts into the database with isSystemContract=true.
2. Overwrites registry metadata (address, ABI, name, description, disclosure settings) and sets organizationId and templateId to null.
3. Preserves directly assigned function and event permissions.
4. Deletes any database rows marked isSystemContract=true whose address no longer appears in the registry.
5. Emits audit log entries for every create, update, or delete operation.

If sync fails for any reason, the server exits with code 1 and does not serve traffic. Check the application logs for the specific error.

Before upgrading, review existing registrations at registry addresses. Sync clears their template links, so template-derived permissions and argument restrictions no longer apply. Reconcile those rules before restarting; preserving direct permission rows does not preserve template-derived rules.

Immutable metadata

The API rejects metadata mutations on system contracts with HTTP 400:

• POST /api/contracts with a system contract address returns 400.
• PUT /api/contracts/:contractAddress on a system contract returns 400.
• DELETE /api/contracts/:contractAddress on a system contract returns 400.
• Template linking attempts on system contracts return 400.
• Creating or moving a contract into a system contract address returns 400.

The backend registry is authoritative. Even if client-side validation is bypassed, the API enforces these rules.

System contracts in the Admin Dashboard

System contracts appear in the regular contract listing with a System badge.

On the contract detail page:

• Edit and Delete buttons are hidden.
• Template linking is disabled.
• The Function Permissions and Event Permissions tabs remain fully functional.

The Add Contract form validates the address field against known system contract addresses and blocks submission if the address matches.

System contracts in API responses

All contract endpoints include the isSystemContract boolean field:

{
  "contractAddress": "0x0000000000000000000000000000000000010004",
  "name": "L2NativeTokenVault",
  "isSystemContract": true
  // ... other fields
}

Regular contracts return isSystemContract: false.

Managing permissions on system contracts

Direct calls to system contracts follow the same deny-by-default model as regular contracts. Sync creates no permission rules; functions without rules default to Forbidden. Configure permissions through the Admin Dashboard or API:

1. Open the contract detail page for the system contract.
2. Select the Function Permissions or Event Permissions tab.
3. Assign permission levels (All Users, Check Role, Restrict Argument) as needed.

Directly assigned function and event permission rules persist across restarts.

An umbrella permission can authorize calls made by a permitted entry point. In multi-org mode, six shared bridge dependencies limit this inherited access to code-listed methods. Other methods require their own permissions. See Umbrella Permissions in Multi-Org Mode for the method policy and optional accounting reads.

To enable ETH and ERC-20 bridging, see Enabling Bridging for the entry-point permissions and per-token setup.

Audit logs

Sync operations generate audit log entries with an anonymous identity (system-contracts-sync). Each create, update, and delete action during sync produces a separate audit record with trigger: system-contracts-sync metadata.