Permissions Overview

Prividium offers flexible and customizable ways for chain operators to have granular control over access to reading onchain data or calling contracts. There are two systems used to manage this control: the permissions API, and selective disclosure.

Permissions API

The permissions API is a layer in between the standard RPC API and the Proxy RPC API that controls who can call certain functions in a contract.

The API works as a central hub for access control definitions and managing filtering rules that both the block explorer's API and chain admins can easily access. The permission API is managed by the chain admins through the admin panel.

All permissions require user authentication. Users can authenticate via the user panel. Both corporate identity providers (e.g. Okta) and crypto-native login flows are supported. For unauthenticated access, you can use the selective disclosure feature.

Admin Panel

To configure access to different smart contracts on your chain, ZKsync Prividium offers an admin panel. The admin panel provides a user interface for permission management where admins can configure data access rules and monitor system access patterns.

Admins can view and edit users, roles, and contract permissions. Only designated admins are able to access the admin panel.

The initial admin is defined when the API is launched. To add more admins, the initial admin must manually grant other users the admin role.

Users

The admin panel allows admins to view and search through a list of all users and their emails, associated wallets, and roles. Users can be added and deleted via the admin panel.

Roles

A role is user type that can be assigned to any user to grant them certain access privileges. The admin status is itself a role.

In the admin panel, admins can create and manage user roles. For example, a role can be created for auditors or company employees.

Contract Permissions

Access to deployed contracts can be configured in the admin panel. Each contract function can be assigned the following permission types:

1. Forbidden: Prevents any user from calling the function. This is the default permission type for all functions after contract is created.
2. All users: Allows any authenticated user to call the function without role restrictions.
3. Check Role: Restricts function access to authenticated users with specific roles. The system checks roles stored in the database for the authenticated user.
4. Restrict Argument: Allows any authenticated user to call the function, but restricts specific function arguments. Users can only pass argument values that meet the configured restrictions.
5. Check Role AND Restrict Argument: Combines role-based access control with argument restrictions. Users must have the required role AND can only use permitted argument values. Both conditions must be satisfied for access.
6. Check Role OR Restrict Argument: Provides flexible access where users can gain authorization either through having a role OR by using restricted arguments. Role holders get unrestricted access, while regular users get limited access.

User Access

User Panel

The user panel is used for initial user registration. Users can login via an identity provider and add/manage wallets associated with their account. The registration flow looks like this:

1. On first login, the user authenticates with the identity provider in the User Panel.
2. The user receives a Prividium session, and is prompted to connect their wallet.
3. The User Panel issues an EIP-712 challenge, which the user signs to prove they control the wallet.
4. The Prividium Proxy API saves the user-address mapping in the Permissions API, enabling all future reads/writes to be authorized by both the identity provider and linked wallet address.

Login with Prividium

After initial registration, the user can login to other applications using the Prividium SDK. The SDK allows the user to connect either with the identity provider or the wallet they have previously linked with their account.

Calling Contracts

When a user calls a function from a contract, they sign an EIP-712 typed transaction that includes a JSON Web Token (JWT). This transaction is then sent to the proxy API, which verifies the user based on the JWT and wallet address. The proxy API then checks the permissions API to verify the user is able to call the requested function before sending the final request to the standard RPC API.

Selective Disclosure

Selective disclosure is a privacy feature that allows the chain operators to make specific pieces of information publicly accessible via the Proxy RPC API while maintaining the confidentiality of all other contract data.

Selective disclosure controls what data is publicly visible to anyone. When enabled, dedicated RPC endpoints become available to access certain data without authentication.

Lifecycle

1. Configuration: This is a one-time setup by the contract owner. The admin enables selective disclosure in the admin panel and selects which disclosure types to enable.
2. Request: A user calls a prividium_* RPC endpoint. No authentication token is needed.
3. Authorization: The Proxy RPC checks with the Permissions API and verifies if the requested disclosure is enabled. An error is returned if the disclosure is not authorized.
4. Retrieval: The Proxy RPC fetches the data from the blockchain, generates a proof if applicable, and returns a formatted response to user.

Available Disclosure Types

Currently, the disclosure of the following contract information is supported:

1. Contract bytecode
2. Total and circulating token supply

Contract Bytecode Disclosure

Reveals the bytecode hash of a deployed contract along with a cryptographic proof, enabling verification of contract code.

Contract bytecode disclosure allows:

• Verification that a contract's bytecode hash matches expected values.
• Transparency for critical contracts without revealing implementation details.
• Auditors to confirm deployment correctness.
• Contract verification without source code exposure.

It enables the prividium_bytecodeDisclosure endpoint, which returns the following data:

• byteCodeHash: The keccak256 hash of the contract's deployed bytecode
• batchNumber: The L1 batch number where the proof was generated
• proof: Merkle proof data for independent verification
  • path: Array of hashes forming the Merkle proof path
  • index: Position in the Merkle tree
  • key: The storage slot key being proved

Token Total & Circulating Supply Disclosure

Reveals ERC20 token supply information, enabling calculation of circulating supply by providing total supply along with balances held at configured lock addresses (treasury, vesting contracts, etc.).

Token supply disclosure allows:

• Transparency for token supply without exposing individual holder balances.
• The ability to calculate circulating supply by subtracting locked tokens from total supply.
• Auditors, DEXs and aggregators to accurately price tokens based on actual circulating supply.

It enables the prividium_tokenSupplyDisclosure endpoint, which returns the following data:

• totalSupply: The total minted supply of the token.
• decimals: The token decimal places for proper display formatting.
• lockedBalances: An array of balances at configured lock addresses.
  • Typically includes treasury, vesting contracts, team allocations.
  • Each entry shows the address and its balance.
  • Allows calculating: Circulating Supply = Total Supply - Sum(Locked Balances)