Skip to content

Commit 0d20857

Browse files
feat: added permission system configuration docs (#452)
# Description Added sections to describe configuration options for Prividiums
1 parent dda1312 commit 0d20857

File tree

13 files changed

+610
-79
lines changed

13 files changed

+610
-79
lines changed

content/10.zk-stack/00.index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Overview
3-
description: This section provides an overview of the ZK Stack as a key tool to launch and operate ZKsync chains.
3+
description: This section provides an overview of the ZK Stack as a key tool to launch and operate ZKsync chains
44
---
55

66
ZK Stack is a developer friendly modular framework that makes it easy for you to customize & deploy your own interoperable ZK-powered blockchains.

content/10.zk-stack/35.prividium/00.index.md

Lines changed: 39 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22
title: Overview
33
description: Learn about ZKsync Prividium.
44
---
5-
65
ZKsync Prividium lets institutions operate a **private**, permissioned blockchain within their own infrastructure or cloud,
76
while still **anchoring every transaction to Ethereum** for security and finality.
87

@@ -16,47 +15,67 @@ This design solves a core challenge in enterprise blockchain adoption:
1615
![ZKsync Prividium architecture diagram](/images/zk-stack/how-prividium-works.png)
1716
::
1817

18+
---
19+
1920
### Key Differentiators of ZKsync Prividium
2021

2122
**Privacy with Control:**
2223
Transaction data remains offchain, so internal details such as trades and balances stay confidential.
2324
Each block is verified on Ethereum using zero-knowledge proofs.
24-
Chain operators can selectively disclose data to auditors or regulators without exposing the full ledger.
25+
Chain operators can selectively disclose specific data (for example, bytecode or token supply) to auditors or regulators without exposing the full ledger.
26+
27+
**Role-Based Permissioning:**
28+
Prividium introduces a dynamic permissioning system managed through the **Admin Dashboard**, replacing static YAML files.
29+
Administrators can:
30+
31+
- Add and manage users with Okta or crypto-native (SIWE) authentication
32+
- Create roles such as *Trader*, *Auditor*, or *Admin*
33+
- Assign permissions for contracts and functions directly in the UI
34+
- Configure selective disclosure for public endpoints
35+
36+
Access control is enforced by the **Proxy RPC**, which validates user tokens against the **Permissions API** before any on-chain call is executed.
2537

2638
**Built-in Compliance:**
27-
Role-based access controls, single sign-on integration, and support for KYC, KYB, and AML workflows are built in.
28-
Only authenticated and authorized users can interact with the chain, enabling policy enforcement from day one.
39+
Single sign-on with Okta, address-level identity binding, and fine-grained access policies are integrated out of the box.
40+
Only authenticated and authorized users can interact with the network, enabling compliance with KYC, KYB, and AML requirements from day one.
2941

3042
**Ethereum Anchoring and Interoperability:**
3143
Each batch of transactions is finalized on Ethereum using a validity proof, ensuring tamper-proof integrity and trustless settlement.
3244
Assets and data can move between Ethereum and other public or private ZKsync Chains
33-
using native zero-knowledge-based bridges without relying on external custodians.
45+
using native zero-knowledge-based bridges without external custodians.
3446

3547
**Scalability and Performance:**
36-
As a Validium chain, ZKsync Prividium stores state off-chain, enabling high throughput and low transaction costs.
37-
It supports latency-sensitive use cases like trading and payments without compromising on security.
48+
As a Validium chain, ZKsync Prividium stores state off-chain, achieving high throughput and low latency.
49+
It supports trading, payments, and settlement use cases that demand both privacy and speed.
50+
51+
---
3852

3953
### What Data Is Public
4054

41-
Only the state root hashes and zero-knowledge proofs are posted to Ethereum.
42-
No transaction inputs, addresses, or calldata are visible or inferable from public chain data.
55+
Only the **state roots** and **zero-knowledge proofs** are posted to Ethereum.
56+
No transaction inputs, addresses, or calldata are visible or inferable from public data.
4357

44-
The only additional public data appears when interacting with non-private chains, such as deposits or withdrawals to Ethereum or other rollups.
45-
These interactions will be visible on the receiving chain.
58+
Selective disclosure can optionally expose verified metrics such as total and circulating token supply, or contract bytecode,
59+
through public read-only endpoints.
4660

47-
All other transaction and state data remains inside the private chain database, accessible only to the operator.
61+
Interactions with public networks such as deposits or withdrawals remain visible on the receiving chain,
62+
but all other state data is kept private within the Prividium database.
4863

4964
To learn more about data availability in the ZK Stack, visit the [Validium page](/zk-stack/customizations/validium).
5065

66+
---
67+
5168
### How It Works
5269

53-
ZKsync Prividium enforces privacy and access control at the API layer, using infrastructure built into the ZK Stack.
70+
ZKsync Prividium enforces privacy and access control using built-in infrastructure within the ZK Stack.
5471

55-
- Access control is configured in a YAML file that defines which users or groups can call specific contracts and methods.
56-
- Users and applications connect through a Private RPC proxy, which enforces access policies on every request.
57-
- Authenticated users receive access tokens tied to their role, giving them a filtered view of the chain.
58-
- Full RPC and explorer access is restricted to chain operators and internal systems.
72+
- Users authenticate through **Okta SSO** or **Sign-in With Ethereum (SIWE)**.
73+
- All calls pass through the **Proxy RPC**, which checks the user’s token and permissions against the **Permissions API**.
74+
- Roles and permissions are defined in the **Admin Dashboard**, not static YAML files.
75+
- Access is controlled at the contract-function level, with optional restrictions based on function arguments.
76+
- Auditors and regulators can use **Selective Disclosure** to view approved on-chain data without accessing the private ledger.
77+
- Full RPC and explorer access remain restricted to chain operators and internal systems.
5978

60-
The chain runs as a Validium. It executes transactions privately and stores state off-chain in a secure database.
61-
Each batch of transactions produces a zero-knowledge proof and a new state root that are submitted to Ethereum.
62-
This anchors the private chain to Ethereum, ensuring security and finality without exposing sensitive data.
79+
The chain runs as a Validium. It executes transactions privately and stores its state off-chain in a secure database.
80+
Each batch of transactions produces a zero-knowledge proof and a new state root submitted to Ethereum.
81+
This anchors the private chain to Ethereum, ensuring verifiable security and finality without revealing sensitive data.

content/10.zk-stack/35.prividium/02.features.md

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Only cryptographic commitments—state roots and STARK-based proofs—are submit
1515
**Key capabilities:**
1616

1717
- Keep all data inside your infrastructure (no transaction details on Ethereum)
18-
- Selectively mark contracts/methods as public, private, or role-gated via a policy file
18+
- Configure contract access policies through the Prividium Admin Dashboard, defining which functions are public, private, or role-restricted
1919
- Update access settings without redeploying contracts
2020
- Supply Merkle proofs or DB extracts for selective disclosure (e.g., audits, investigations)
2121

@@ -28,18 +28,19 @@ Only cryptographic commitments—state roots and STARK-based proofs—are submit
2828

2929
## Fine-Grained Access Control
3030

31-
All interactions with the chain are routed through a **Proxy RPC** that enforces access policies defined in a YAML configuration.
32-
31+
All interactions with the chain are routed through a Proxy RPC that enforces access policies managed in the Prividium Permissioning System.
32+
Administrators configure roles, users, and permissions through the Admin Dashboard, which stores policies dynamically in the Permissions API.
3333
**Features:**
3434

35-
- Wallet address whitelisting.
36-
- Define groups (e.g., traders, clients, auditors) and map them to specific methods and contracts
37-
- Unauthorized calls are blocked with HTTP 403 and logged for audit
38-
- Applies to all user calls, application traffic, explorer queries, and bridge operations
39-
- Authenticate users using corporate IdPs (Azure AD, Okta, Ping) via OIDC/SAML tokens - (coming soon)
35+
- Manage access using roles (e.g., Trader, Auditor, Admin) and assign them to users in the dashboard
36+
- Restrict contract functions by role, argument match, or both
37+
- Enforce access at the RPC layer; unauthorized calls return HTTP 403 and are logged for audit
38+
- Apply consistent access control across user calls, dApps, explorers, and bridges
39+
- Support for Okta and crypto-native Sign-in With Ethereum (SIWE) authentication
40+
- Configure and update permissions without redeploying contracts or editing files
4041

4142
**Request Path:**
42-
Client → Proxy RPC → Sequencer RPC
43+
Client → Proxy RPC (permission validation) → Permissions API (policy check) → Sequencer RPC
4344

4445
## Compliance & Audit Support
4546

@@ -50,7 +51,7 @@ Regulated entities require visibility, traceability, and selective access. ZKsyn
5051
- A private block explorer shows only what each user is authorized to view (gated via Proxy)
5152
- System logs from all core components are available for integration with enterprise logging and analytics tools
5253
- Chain operators can export inclusion proofs or filtered ledger views on-demand
53-
- Auditors can be granted scoped access without exposing unrelated user data
54+
- Auditors can be granted scoped roles through the Permissioning System, enabling view-only access without exposing unrelated data.
5455

5556
## Ethereum-Grade Finality
5657

@@ -73,3 +74,10 @@ With shared settlement and ZK proofs, institutions can move assets securely and
7374
all without consortium agreements, third-party bridges, or compromises to customization.
7475

7576
Daily operations remain private, but interoperability is opt-in and cryptographically verified.
77+
78+
---
79+
80+
### Next Step
81+
82+
See [Configure Prividium](./config/authentication.md)
83+
for detailed steps on setting up authentication, users, roles, permissions, and selective disclosure.

content/10.zk-stack/35.prividium/05.architecture.md

Lines changed: 54 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -3,40 +3,70 @@ title: Architecture Overview
33
description: Understand how ZKsync Prividium works under the hood.
44
---
55

6-
ZKsync Prividium is built on a **permissioned Validium chain** enhanced with robust access control.
6+
ZKsync Prividium is built on a **permissioned Validium chain** with integrated, role-based access control.
77
It runs a private instance of the ZKsync Chain, complete with its own sequencer and prover, inside an organization’s infrastructure or cloud.
8-
All transaction data and state are stored off-chain in a secure database, preserving confidentiality by design.
8+
All transaction data and state are stored off-chain in a secure database, ensuring privacy by design.
99

10-
A **Proxy RPC layer** acts as the system’s entry point. All interactions—whether from users, enterprise applications, block explorer queries,
11-
or bridge transactions—must go through this proxy. It enforces fine-grained access policies,
10+
A **Proxy RPC layer** serves as the single entry point to the network.
11+
All interactions — from users, enterprise applications, block explorers, or bridge operations — must pass through this proxy.
12+
It enforces fine-grained access rules using the **Prividium Permissioning System**,
1213
ensuring that only authenticated and authorized requests reach the chain.
13-
By separating the public interface from the internal blockchain components, ZKsync Prividium prevents unauthorized access and protects sensitive data.
14+
By separating the public interface from internal blockchain components, Prividium prevents unauthorized access and safeguards sensitive data.
1415

15-
State updates are finalized on Ethereum via the **ZKsync Gateway**, which receives the ZKsync Prividium chain’s state roots and zero-knowledge proofs.
16-
This anchors the chain’s state to Ethereum, providing L1-grade security and enabling interoperability with other chains in the ZKsync ecosystem.
16+
State updates are finalized on Ethereum through the **ZKsync Gateway**, which receives the chain’s state roots and zero-knowledge proofs.
17+
This anchors the chain to Ethereum, providing L1-grade security and enabling interoperability with other ZKsync Chains.
1718

18-
This architecture delivers privacy and control at the L2 level while inheriting security from Ethereum,
19-
making ZKsync Prividium well-suited for institutional use cases such as trading, payments, asset issuance, and compliance-sensitive workflows.
19+
This architecture delivers **privacy, compliance, and auditability** at the L2 level while inheriting the trust and finality of Ethereum,
20+
making ZKsync Prividium ideal for institutional use cases such as trading, settlement, asset issuance, and compliance-sensitive workflows.
2021

2122
::centered-container
2223
*Figure: High-level architecture of ZKsync Prividium.*
2324
![ZKsync Prividium architecture diagram](/images/zk-stack/prividium-architecture.png)
2425
::
2526

27+
---
28+
2629
### Components
2730

28-
Adding privacy to a ZKsync chain is possible by making changes
29-
to the RPC API and block explorer.
30-
The ZK Stack CLI provides a production-ready implementation
31-
of these changes for you, but they can be customized as needed.
32-
33-
- [Access Controls](/zk-stack/prividium/permissioning): Fine-grained, role-based permissions ensure that only authorized personnel can
34-
view or interact with your private chain.
35-
- [Proxy RPC](/zk-stack/prividium/proxy) that filters requests based on the configured permissions. Authenticated JSON-RPC endpoints apply
36-
your internal access policies to every request, maintaining full control over data access and interactions
37-
- [Private Block Explorer](/zk-stack/prividium/explorer) with privacy protections enabled. This self-hosted interface gives authorized users
38-
visibility into transactions, blocks, and state without exposing sensitive data to the public
39-
- [Validium Chain](/zk-stack/customizations/validium): A dedicated ZKsync Chain deployed within your infrastructure.
40-
It includes a built-in sequencer and prover to handle transaction processing and proof generation privately.
41-
- [ZKsync Gateway](/zksync-protocol/gateway/overview): Receives ZK proofs from your permissioned chain and publishes commitments to Ethereum.
42-
This anchors integrity, ensures finality, and enables future interoperability.
31+
ZKsync Prividium extends the ZK Stack architecture with dedicated modules for privacy, governance, and access control.
32+
These components work together to provide secure, verifiable, and customizable network operations.
33+
34+
- [**Permissioning System**](/zk-stack/prividium/permissions-overview):
35+
A built-in role-based framework that manages **users**, **roles**, **permissions**, and **selective disclosure** through the **Admin Dashboard**.
36+
Administrators define who can read or write to contracts and configure disclosure settings without modifying code or YAML files.
37+
38+
- [**Proxy RPC**](/zk-stack/prividium/proxy):
39+
The secure interface that filters every request based on the policies defined in the Permissioning System.
40+
It validates user tokens issued via Okta or crypto-native (SIWE) login and enforces role and argument-level restrictions before forwarding to the sequencer.
41+
42+
- [**Private Block Explorer**](/zk-stack/prividium/explorer):
43+
A self-hosted explorer with access restrictions aligned to user roles.
44+
It allows authorized participants to view transactions, blocks, and state data while protecting sensitive information from public exposure.
45+
46+
- [**Validium Chain**](/zk-stack/customizations/validium):
47+
A private ZKsync Chain deployed within your infrastructure.
48+
It includes a dedicated sequencer and prover that execute transactions and generate zero-knowledge proofs locally.
49+
50+
- [**ZKsync Gateway**](/zksync-protocol/gateway/overview):
51+
Receives zero-knowledge proofs and publishes commitments to Ethereum.
52+
This ensures data integrity, anchors the private chain to Ethereum, and enables future cross-chain interoperability.
53+
54+
---
55+
56+
### How Access Control Works
57+
58+
1. Users authenticate via **Okta SSO** or **Sign-in With Ethereum (SIWE)** in the **User Dashboard**.
59+
2. The **Proxy RPC** forwards their request and token to the **Permissions API**.
60+
3. The **Permissions API** verifies the user’s identity, role, and function-level rules.
61+
4. Authorized requests are sent to the **Sequencer RPC**, which executes transactions privately.
62+
5. State updates are committed to Ethereum through the **ZKsync Gateway**.
63+
64+
This design ensures that access control, compliance, and selective disclosure are built directly into the network stack,
65+
not managed through static configuration files.
66+
67+
---
68+
69+
### Next Step
70+
71+
See [Configure Prividium](./config/authentication.md)
72+
for instructions on setting up authentication, users, roles, permissions, and selective disclosure.

content/10.zk-stack/35.prividium/10.run-prividium-chain.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Get started running a local ZKsync Prividium chain with ZKsync Stac
44
---
55

66
::callout{icon="i-heroicons-light-bulb"}
7-
This guide is not yet updated to use the latest [Permissions API](/zk-stack/prividium/permissioning) or Atlas upgrade.
7+
This guide is not yet updated to use the latest [Permissions API](/zk-stack/prividium/permissions-overview) or Atlas upgrade.
88
::
99

1010
This guide shows you how to use the ZKsync Stack CLI to run local a ZKsync Prividium chain.

content/10.zk-stack/35.prividium/30.permissioning.md renamed to content/10.zk-stack/35.prividium/30.permissions-overview.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Permissioning System
2+
title: Permissions Overview
33
description: Learn about the Prividium Permissioning API and Selective Disclosure.
44
---
55

0 commit comments

Comments
 (0)