> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.prividium.com/api/mcp` to find what you need.
>
> **Have feedback?** Use `submit_feedback` on the same MCP server.

This document provides a high-level overview of the Prividium™ architecture and its components.

## Prividium Products

Prividium is a blockchain platform for institutions to build and operate digital-asset services with privacy and
control. Two Prividium products are available today.

| Product             | Definition                                                                                                                                                                        |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Prividium Commander | Prividium's control plane for managing access, permissions and governed application operations on Prividium Ledger or a supported existing private EVM blockchain.                |
| Prividium Ledger    | Prividium's high-performance ZK blockchain for private financial applications, combining execution-integrated controls, integrity enforced by ZK proofs and selective disclosure. |

### Prividium Commander

Prividium Commander gives teams reusable access and permission controls for the financial applications they build and
operate. Each Commander deployment governs one chain, either Prividium Ledger or a supported existing private EVM chain
(e.g. Hyperledger Besu). Teams with existing applications adopt Commander's controls without rewriting their smart
contracts.

Commander provides four capabilities:

* Administrators onboard users and applications, set which roles can call a contract function, restrict its arguments,
  and change or revoke access.
* Users sign in through an enterprise identity provider (OIDC) or a wallet signature (SIWE).
* The Prividium API authorizes every JSON-RPC request before forwarding it to the chain and filters each response to
  the caller's permissions.
* Every administrative change, such as a new role or an edited contract permission, is written to an audit log that records
  who made the change and what it altered.

Commander consists of the Prividium API, the Admin Panel, the User Panel, and the Prividium SDK & CLI, each described
under [Prividium Core Components](#prividium-core-components).

:::note[NOTE]
Commander enforces its controls on operations that pass through the Prividium API. On an existing chain, the underlying
chain determines execution and privacy. Prividium Ledger supplies private execution, participant isolation, and
ZK-proof enforcement.
:::

## High Level Architecture

<img alt="High Level Components" decoding="async" fetchPriority="high" loading="eager" src="/images/prividium_components.svg" />

:::note[NOTE]
For Validium Chain details, please refer to
[ZKsync Validium documentation.](https://docs.zksync.io/zk-stack/running/validium).
:::

## Actors & Auth Model

Prividium™ distinguishes three types of actors that interact with the system:

| Actor             | What it represents                                                                                         | Auth Mechanism                                             | Functionality                                                                                                         |
| ----------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Organizations** | A third-party organization.                                                                                | None (admin-managed)                                       | Group users under a shared identity, configure org-level settings, and scope roles/permissions per organization.      |
| **User Apps**     | A registered client application that end-users interact with (e.g. a dApp, a web portal, or a mobile app). | No direct app auth — relies on the user's OIDC/SIWE token. | Provide "Login with Prividium" functionality, appear in the User Panel for discovery, and define OAuth redirect URIs. |
| **M2M Apps**      | A backend system or machine integration (e.g. an indexer, a CI pipeline, or a monitoring service).         | API keys                                                   | Authenticate without a user session, call the API with app-level permissions, and perform automated operations.       |

### Migrating from the Legacy Model

The previous model used **Tenants**, **Apps**, and **Services**. Tenants handled both user grouping and machine
authentication, while Services provided a separate M2M mechanism using SIWE. This created overlap and confusion —
particularly between tenants and multi-tenancy, which are unrelated concepts.

The new model cleanly separates concerns: **Organizations** only group users, **User Apps** only handle user-facing
OAuth, and **M2M Apps** are the single model for all machine access using API keys.

**Legacy model:**

| Actor        | What it represents         | Auth Mechanism                       | Functionality                      |
| ------------ | -------------------------- | ------------------------------------ | ---------------------------------- |
| **Tenants**  | A third-party organization | SIWE, API keys                       | Manage users, read data from them  |
| **Apps**     | A registered client app    | No direct app auth (uses user token) | Login with Prividium functionality |
| **Services** | M2M integration            | SIWE                                 | M2M API and service RPC access     |

**Migration mapping:**

| Legacy pattern                                         | New model                                    |
| ------------------------------------------------------ | -------------------------------------------- |
| Tenant grouping (organizing users under an entity)     | Organizations                                |
| Tenant machine operations (create user, attach wallet) | M2M Apps with organization-level permissions |
| Service integrations (RPC reads, contract metadata)    | M2M Apps with system permissions             |

:::note[NOTE]
Tenants and Services remain available during the migration window but will be removed in a future release. New
integrations should use M2M Apps.
:::

## Authorization Model

Prividium™ implements a **Zero-Trust, per-request authorization** model using industry-standard patterns. Every request
is evaluated by a single **Policy Decision Point (PDP)** — the Prividium™ API — and enforced at the **Policy
Enforcement Points (PEPs)**: the RPC proxy (and additional enforcement layers depending on deployment). Nothing is
implicitly trusted by network location.

The model combines two complementary mechanisms:

* **Role-Based Access Control (RBAC)** for *platform actions* — what a principal may do in the system. Roles carry
  **system permissions** (e.g. read access, contract deployment, admin access), following the standard users → roles →
  permissions model.
* **Attribute-Based Access Control (ABAC)** for *fine-grained conditions* — e.g. a function rule that only permits a
  call when an address argument equals the caller's own wallet, or an event rule scoped to the caller's address. These
  are attribute predicates evaluated per request.

### Identity vs. authority

**Authentication** (OIDC or SIWE) establishes *who* the caller is. **Authorization** (roles + permissions) determines
*what* they may do. A wallet is an attribute the caller must own to act from a given on-chain address — it is not the
principal.

### Delegation

* **Transaction authorizations** are **single-use, short-lived capabilities**: an authenticated user pre-authorizes one
  specific transaction (exact wallet, recipient, nonce, calldata, and value) for a limited time, so an unattended client
  such as a browser wallet can submit exactly that transaction and nothing else. This is distinct from an ERC-20 token
  allowance.
* **M2M Apps** act on behalf of a backend system using API keys with app-level permissions.

### Vocabulary mapping

For teams accustomed to standard access-control terminology:

| Prividium™ term                           | Standard equivalent                            |
| ------------------------------------------ | ---------------------------------------------- |
| System permissions (on roles)              | RBAC roles & permissions                       |
| Contract function / event / argument rules | ABAC attribute predicates                      |
| Prividium™ API authorization check        | Policy Decision Point (PDP)                    |
| RPC proxy enforcement                      | Policy Enforcement Point (PEP)                 |
| Transaction authorization                  | Single-use bearer capability (least authority) |
| OIDC / SIWE login                          | OpenID Connect / Sign-In with Ethereum         |

## Prividium™ Core Components

### User Panel

Vue 3 application for users to:

* Authenticate via OIDC or Web3 wallet.
* Associate wallets and manage user profile.
* View assigned permissions.

### Prividium™ API

Fastify-based backend service providing:

**REST API:**

* Authentication via OIDC and Web3 (SIWE)
* User, role, and permission management
* Contract and template configuration

**RPC Proxy:**

* Permission-enforced JSON-RPC proxy to ZKsync node
* Wallet RPC for Per-User RPC URLs

**Permission System (PostgreSQL):**

* Role-based access control
* Function-level contract permissions with argument validation
* Event-level permissions
* Reusable permission templates

### Admin Panel

Vue 3 application for administrators to:

* Manage contract metadata and permissions
* Configure function-level permissions with argument validation
* Assign user roles and manage user-role relationships

### Prividium™ Block Explorer

Specialized implementation of the ZKsync Block Explorer for Prividium™ authentication and privacy support.

For more details, please refer to ZKsync Block Explorer [repository](https://github.com/matter-labs/block-explorer).

### Prividium™ SDK & CLI

A TypeScript SDK and CLI for integrating with the Prividium™ authorization system.

**SDK:**

* Popup-based OAuth authentication
* Token management with automatic expiration handling
* Viem transport with auth headers
* Wallet integration (network setup, transaction authorization)

**CLI:**

* Local authenticated JSON-RPC proxy (`prividium proxy`)
* Configuration management

See: [Prividium™ SDK & CLI](https://www.npmjs.com/package/prividium).

## Example Flow: User accessing a contract function with restricted access

1. **Client** makes RPC call via dApp, wallet or Explorer.
2. **SDK** adds access token to Authorization header
3. **Prividium™ API** receives the RPC call and, acting as the **Policy Decision Point (PDP)**, performs the
   authorization check based on the configured permissions for the contract function stored in the **Prividium™
   Permission System Database**.
4. If authorized, **Prividium™ API** forwards requests to ZKsync node.
5. **Prividium™ API** applies response filtering based on user permissions.
6. **Prividium™ API** returns filtered response to client.