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. The initial 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 all registry-owned fields (address, ABI, name, description, disclosure settings, templateId).
3. Preserves existing 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.

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

System contracts follow the same deny-by-default model as regular contracts. After sync, all functions 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.

Permissions persist across restarts. The sync process preserves all existing function and event permission rules.

To enable ETH and ERC-20 bridging, see Enabling Bridging for the exact functions to permit on L2BaseToken, L2AssetRouter, and L2NativeTokenVault.

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.