Skip to content

Commit 5da16f4

Browse files
nadeemb53nadeemb53
authored
Merge pull request #40 from status-im/feat/gasless-doc
feat: add docs for gasless transactions and update dependencies
2 parents 502efa8 + 4f72d23 commit 5da16f4

File tree

12 files changed

+3887
-821
lines changed

12 files changed

+3887
-821
lines changed

‎docs/general-info/gasless-transactions.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
sidebar_label: '⛽ Gasless Transactions'
3+
title: Gasless Transactions on Status Network
4+
description: Learn how Status Network implements gasless transactions using RLN (Rate Limiting Nullifier), and Karma tiers for spam prevention and fair usage.
5+
keywords: [Status Network, Gasless Transactions, Linea, RLN, Rate Limiting Nullifier, Karma, Zero-Knowledge Proofs, ZKP, Soulbound Tokens, Blockchain, Layer 2, L2, Spam Prevention]
6+
---
7+
8+
# Gasless Transactions in Status Network
9+
10+
11+
Status Network aims to introduce gasless transactions at scale. The key component of this gasless approach is Vac's Rate Limiting Nullifier, which permits transaction rate limitation without the need for traditional gas fees. The document describes the architecture and integration elements needed to safely enable gasless transactions.
12+
13+
### 1.2 RLN
14+
15+
RLN is a zero-knowledge system designed to prevent spam without compromising user privacy unless a violation occurs. It replaces traditional gas fees with cryptographic rate limits enforced via ZKPs and Shamir's Secret Sharing.
16+
17+
RLN characteristics:
18+
19+
- **Zero-Knowledge Proofs:** Users generate ZKPs verifying their RLN group membership without revealing their identity. The group membership indicates the maximum gasless transaction throughput for each tier.
20+
- **Shamir's Secret Sharing and Nullifiers:** Users hold a secret key used to generate unique nullifiers for transactions. If a user exceeds their transaction limit within an epoch (e.g., block or timestamp), their secret key becomes recoverable, exposing them.
21+
- **Spam Detection:** Users exceeding limits effectively reveal their secret, leading to penalties like Deny List inclusion, higher future gas costs, or potential token slashing.
22+
23+
### 1.3. RLN Membership Management
24+
25+
RLN uses Sparse Merkle Trees to efficiently handle large-scale membership proofs. A benchmarking study determined that a tree height of 20, supporting 1 million accounts, provides optimal performance for proof generation and verification. For scalability beyond 1 million accounts, multiple SMTs can be used with a registry to direct users to the appropriate tree.
26+
27+
The Prover includes a Registrar Service that listens for events from the Karma Contract, where Karma is allocated to new addresses. Upon detecting such an event, the Registrar Service onboards the user to the RLN Membership Contract by generating and registering their RLN credentials (identitySecretHash and identityCommitment). The RLN Prover Service generates proofs for transactions, which are streamed via gRPC to the RLN Verifier in the Sequencer. The Verifier stores these proofs in memory and matches them with incoming transactions based on transaction hashes, as the process is asynchronous.
28+
29+
```mermaid
30+
graph TD
31+
A[User Wallet] -->|First L2 Action via Whitelisted App| B(Karma Issued)
32+
A -->|Bridges into SN| B
33+
B -->|Soulbound Token| C{Tier Assignment}
34+
35+
subgraph "Tier Limits"
36+
D[Basic]
37+
E[Active]
38+
F[Regular]
39+
G[Power User]
40+
H[High-Throughput]
41+
I[S-Tier]
42+
end
43+
44+
C --> D
45+
C --> E
46+
C --> F
47+
C --> G
48+
C --> H
49+
C --> I
50+
51+
%% RLN Flow
52+
A -->|Submits Gasless Tx| J[RPC Node]
53+
J -->|Forwards Tx Data| K[Prover]
54+
subgraph "Prover Services"
55+
K --> K1[Registrar Service]
56+
K --> K2[RLN Prover Service]
57+
K --> K3[Karma API Service]
58+
K1 -->|Listens for Karma Events| L[Karma Contract]
59+
K1 -->|Onboards User| M[RLN Membership Contract]
60+
K2 -->|Generates RLN Proof| N[gRPC Stream]
61+
K3 -->|Tracks Tx and Karma Tiers| O[Storage]
62+
end
63+
J -->|Sends Tx| P[Sequencer]
64+
N -->|Streams RLN Proof| P
65+
66+
%% Sequencer Section
67+
subgraph "Sequencer Operations"
68+
P --> Q[RLN Verifier Plugin]
69+
Q -->|Subscribes to gRPC Stream| N
70+
Q -->|Stores Proofs In-Memory| R{Match Tx Hash}
71+
R -->|Validates RLN Proof| S{Quota Check}
72+
S -->|Within Limit| T[Add to Mempool]
73+
S -->|Exceeds Limit| U[Deny List]
74+
U -->|Flags Address| V[Premium Gas Required]
75+
Q -->|Spam Detected| W[Slash RLN Stake]
76+
end
77+
78+
%% Gas Estimation Flow
79+
A -->|Requests Gas Estimate| X[Modified linea_estimateGas RPC]
80+
X -->|Queries| U
81+
U -->|Address Listed| Y[Apply Premium Gas Multiplier]
82+
Y -->|Pay Premium Gas| Z[Remove from Deny List]
83+
Z -->|Earn Karma| B
84+
U -->|Address Not Listed| AA[Standard Gas Estimate]
85+
86+
%% Styling
87+
classDef wallet fill:#FFD700,stroke:#DAA520,color:#333
88+
classDef karma fill:#98FB98,stroke:#2E8B57,color:#333
89+
classDef tier fill:#87CEFA,stroke:#4682B4,color:#333
90+
classDef tierNode fill:#ADD8E6,stroke:#4682B4,color:#333
91+
classDef rln fill:#FFB6C1,stroke:#DB7093,color:#333
92+
classDef sequencer fill:#DDA0DD,stroke:#BA55D3,color:#333
93+
classDef gas fill:#FFA07A,stroke:#FF4500,color:#333
94+
95+
class A wallet
96+
class B,L karma
97+
class C tier
98+
class D,E,F,G,H,I tierNode
99+
class J,K,K1,K2,K3,M,N,O rln
100+
class P,Q,R,S,T,U,V,W sequencer
101+
class X,Y,Z,AA gas
102+
```
103+
104+
## 3. System Components
105+
106+
### 3.1 Prover
107+
108+
The Prover is a system comprising three services:
109+
110+
1. **Registrar Service**: Listens for Karma allocation events from the Karma Contract. When a new address receives Karma, it onboards the user to the RLN Membership Contract by generating RLN credentials and registering them.
111+
2. **RLN Prover Service**: Generates RLN proofs for transactions using the Zerokit library. Proofs are streamed directly to the RLN Verifier in the Sequencer via a gRPC stream.
112+
3. **Karma API Service**: Tracks transactions made by users within an epoch and maintains their Karma tier status. It stores transaction data in an internal database for efficient querying and tier management.
113+
114+
These services ensure secure credential management, proof generation, and transaction tracking, with gRPC enabling low-latency communication with the Sequencer.
115+
116+
### 3.2 RLN Verifier
117+
118+
The RLN Verifier is a besu plugin inside the sequencer, leveraging RLN's Zerokit Rust library via Java Native Interface.
119+
The Verifier:
120+
121+
- Subscribes to the gRPC stream from the RLN Prover Service to receive RLN proofs as they are generated.
122+
- Stores proofs in memory and matches them with incoming transactions based on transaction hashes, accounting for the asynchronous arrival of transactions (via RPC Node) and proofs (via gRPC).
123+
- Verifies proof authenticity, nullifier uniqueness, and user transaction quotas.
124+
125+
Transactions failing verification are rejected, and users may be temporarily added to the Deny List.
126+
127+
### 3.3 Deny List
128+
129+
The Deny List temporarily restricts users exceeding quotas or engaging in spam:
130+
131+
- Entries expire after a set duration (e.g., hours or days) based on the throughput tiers
132+
- Users can bypass restrictions by paying premium gas fees
133+
- Paying premium fees removes users from the list and earns additional Karma
134+
135+
### 3.4 `linea_estimateGas` RPC Modification
136+
137+
The linea_estimateGas method is customised to account for users on the Deny List:
138+
139+
- Checks user's Deny List status
140+
- Adds premium gas multipliers if needed
141+
- Provides transparency and accurate gas estimations to the users

‎docs/tools/testnet-faucets.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ The Status Network testnet faucet is available at [faucet.status.network](https:
1414

1515
### Details
1616
- **Faucet Contract**: [`0x06338B70F1eAbc60d7A82C083e605C07F78bb878`](https://sepoliascan.status.network/address/0x06338B70F1eAbc60d7A82C083e605C07F78bb878)
17-
- **Amount**: 0.1 ETH per request
17+
- **Amount**: 0.01 ETH per request
1818
- **Cooldown**: One request per address per day
1919

2020
### How to Get Testnet ETH

‎docusaurus.config.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,11 @@ const config: Config = {
169169
},
170170
},
171171

172+
markdown: {
173+
mermaid: true,
174+
},
175+
themes: ['@docusaurus/theme-mermaid'],
176+
172177
plugins: [
173178
[
174179
'@acid-info/docusaurus-umami',

‎i18n/ja/docusaurus-plugin-content-docs/current/general-info/gasless-transactions.md

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
sidebar_label: '⛽ ガスレストランザクション'
3+
title: Status Networkのガスレストランザクション
4+
description: Status NetworkがRLN（Rate Limiting Nullifier）とKarmaティアを使用してスパム防止と公正な使用のためのガスレストランザクションを実装する方法を学びます。
5+
keywords: [Status Network, ガスレストランザクション, Linea, RLN, Rate Limiting Nullifier, Karma, ゼロ知識証明, ZKP, ソウルバウンドトークン, ブロックチェーン, レイヤー2, L2, スパム防止]
6+
---
7+
8+
# Status Networkのガスレストランザクション
9+
10+
Status Networkは大規模なガスレストランザクションの導入を目指しています。このガスレスアプローチの主要コンポーネントは、VacのRate Limiting Nullifierで、従来のガス手数料を必要とせずにトランザクション速度制限を可能にします。この文書では、ガスレストランザクションを安全に有効にするために必要なアーキテクチャと統合要素について説明します。
11+
12+
### 1.2 RLN
13+
14+
RLNは、違反が発生しない限りユーザーのプライバシーを損なうことなくスパムを防ぐように設計されたゼロ知識システムです。ZKPとShamirの秘密分散を通じて実行される暗号化速度制限で従来のガス手数料を置き換えます。
15+
16+
RLNの特徴：
17+
18+
- **ゼロ知識証明：** ユーザーは自分のアイデンティティを明かすことなくRLNグループメンバーシップを検証するZKPを生成します。グループメンバーシップは各ティアの最大ガスレストランザクション処理能力を示します。
19+
- **Shamirの秘密分散とNullifier：** ユーザーはトランザクションの一意のnullifierを生成するために使用される秘密鍵を保持します。ユーザーがエポック（ブロックやタイムスタンプなど）内でトランザクション制限を超えると、秘密鍵が回復可能になり、露出します。
20+
- **スパム検出：** 制限を超えるユーザーは効果的に自分の秘密を明かすことになり、拒否リストへの追加、将来の高いガス費用、または潜在的なトークンスラッシングなどのペナルティを受けます。
21+
22+
### 1.3. RLNメンバーシップ管理
23+
24+
RLNは大規模なメンバーシップ証明を効率的に処理するためにスパースマークルツリーを使用します。ベンチマーク研究により、100万アカウントをサポートする高さ20のツリーが証明生成と検証に最適なパフォーマンスを提供することが判明しました。100万アカウントを超えるスケーラビリティのために、レジストリと共に複数のSMTを使用してユーザーを適切なツリーに誘導できます。
25+
26+
ProverにはKarmaが新しいアドレスに割り当てられるKarma Contractからのイベントを監視するRegistrar Serviceが含まれています。そのようなイベントを検出すると、Registrar ServiceはRLN認証情報（identitySecretHashとidentityCommitment）を生成して登録し、ユーザーをRLN Membership Contractにオンボーディングします。RLN Prover Serviceはトランザクションの証明を生成し、gRPCを介してSequencerのRLN Verifierにストリーミングされます。Verifierはこれらの証明をメモリに保存し、プロセスが非同期であるため、トランザクションハッシュに基づいて受信トランザクションと照合します。
27+
28+
```mermaid
29+
graph TD
30+
A[ユーザーウォレット] -->|ホワイトリストアプリ経由の最初のL2アクション| B(Karma発行)
31+
A -->|SNへのブリッジ| B
32+
B -->|ソウルバウンドトークン| C{ティア割り当て}
33+
34+
subgraph "ティア制限"
35+
D[Basic]
36+
E[Active]
37+
F[Regular]
38+
G[Power User]
39+
H[High-Throughput]
40+
I[S-Tier]
41+
end
42+
43+
C --> D
44+
C --> E
45+
C --> F
46+
C --> G
47+
C --> H
48+
C --> I
49+
50+
%% RLNフロー
51+
A -->|ガスレスTx送信| J[RPCノード]
52+
J -->|Txデータ転送| K[Prover]
53+
subgraph "Proverサービス"
54+
K --> K1[Registrar Service]
55+
K --> K2[RLN Prover Service]
56+
K --> K3[Karma API Service]
57+
K1 -->|Karmaイベント監視| L[Karma Contract]
58+
K1 -->|ユーザーオンボーディング| M[RLN Membership Contract]
59+
K2 -->|RLN証明生成| N[gRPCストリーム]
60+
K3 -->|TxとKarmaティア追跡| O[ストレージ]
61+
end
62+
J -->|Tx送信| P[Sequencer]
63+
N -->|RLN証明ストリーム| P
64+
65+
%% Sequencerセクション
66+
subgraph "Sequencer操作"
67+
P --> Q[RLN Verifierプラグイン]
68+
Q -->|gRPCストリーム購読| N
69+
Q -->|メモリに証明保存| R{Txハッシュマッチング}
70+
R -->|RLN証明検証| S{クォータチェック}
71+
S -->|制限内| T[Mempoolに追加]
72+
S -->|制限超過| U[拒否リスト]
73+
U -->|アドレスフラグ| V[プレミアムガス必要]
74+
Q -->|スパム検出| W[RLNステークスラッシュ]
75+
end
76+
77+
%% ガス推定フロー
78+
A -->|ガス推定リクエスト| X[修正されたlinea_estimateGas RPC]
79+
X -->|クエリ| U
80+
U -->|アドレスリスト済み| Y[プレミアムガス倍率適用]
81+
Y -->|プレミアムガス支払い| Z[拒否リストから削除]
82+
Z -->|Karma獲得| B
83+
U -->|アドレス未リスト| AA[標準ガス推定]
84+
85+
%% スタイリング
86+
classDef wallet fill:#FFD700,stroke:#DAA520,color:#333
87+
classDef karma fill:#98FB98,stroke:#2E8B57,color:#333
88+
classDef tier fill:#87CEFA,stroke:#4682B4,color:#333
89+
classDef tierNode fill:#ADD8E6,stroke:#4682B4,color:#333
90+
classDef rln fill:#FFB6C1,stroke:#DB7093,color:#333
91+
classDef sequencer fill:#DDA0DD,stroke:#BA55D3,color:#333
92+
classDef gas fill:#FFA07A,stroke:#FF4500,color:#333
93+
94+
class A wallet
95+
class B,L karma
96+
class C tier
97+
class D,E,F,G,H,I tierNode
98+
class J,K,K1,K2,K3,M,N,O rln
99+
class P,Q,R,S,T,U,V,W sequencer
100+
class X,Y,Z,AA gas
101+
```
102+
103+
## 3. システムコンポーネント
104+
105+
### 3.1 Prover
106+
107+
Proverは3つのサービスで構成されるシステムです：
108+
109+
1. **Registrar Service**: Karma ContractからKarma割り当てイベントを監視します。新しいアドレスがKarmaを受け取ると、RLN認証情報を生成して登録し、ユーザーをRLN Membership Contractにオンボーディングします。
110+
2. **RLN Prover Service**: Zerokitライブラリを使用してトランザクションのRLN証明を生成します。証明はgRPCストリームを介してSequencerのRLN Verifierに直接ストリーミングされます。
111+
3. **Karma API Service**: エポック内でユーザーが行ったトランザクションを追跡し、Karmaティアステータスを維持します。効率的なクエリとティア管理のために内部データベースにトランザクションデータを保存します。
112+
113+
これらのサービスは安全な認証情報管理、証明生成、トランザクション追跡を保証し、gRPCがSequencerとの低遅延通信を可能にします。
114+
115+
### 3.2 RLN Verifier
116+
117+
RLN Verifierはsequencer内のbesuプラグインで、Java Native Interfaceを介してRLNのZerokit Rustライブラリを活用します。
118+
Verifierは：
119+
120+
- RLN Prover ServiceからgRPCストリームを購読して生成されるRLN証明を受信します。
121+
- 証明をメモリに保存し、トランザクション（RPCノード経由）と証明（gRPC経由）の非同期到着を考慮して、トランザクションハッシュに基づいて受信トランザクションと照合します。
122+
- 証明の真正性、nullifierの一意性、ユーザートランザクションクォータを検証します。
123+
124+
検証に失敗したトランザクションは拒否され、ユーザーは一時的に拒否リストに追加される場合があります。
125+
126+
### 3.3 拒否リスト
127+
128+
拒否リストはクォータを超過したりスパムに関与したりするユーザーを一時的に制限します：
129+
130+
- エントリは処理能力ティアに基づいて設定された期間（時間や日など）後に期限切れになります
131+
- ユーザーはプレミアムガス手数料を支払うことで制限を回避できます
132+
- プレミアム手数料を支払うとユーザーがリストから削除され、追加のKarmaを獲得します
133+
134+
### 3.4 `linea_estimateGas` RPC修正
135+
136+
linea_estimateGasメソッドは拒否リストのユーザーを考慮するようにカスタマイズされています：
137+
138+
- ユーザーの拒否リストステータスをチェックします
139+
- 必要に応じてプレミアムガス倍率を追加します
140+
- ユーザーに透明性と正確なガス推定を提供します

‎i18n/ja/docusaurus-plugin-content-docs/current/tools/testnet-faucets.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Status Networkテストネットフォーセットは[faucet.status.network](htt
88

99
### 詳細
1010
- **フォーセットコントラクト**: [`0x06338B70F1eAbc60d7A82C083e605C07F78bb878`](https://sepoliascan.status.network/address/0x06338B70F1eAbc60d7A82C083e605C07F78bb878)
11-
- **配布量**: リクエストあたり0.1 ETH
11+
- **配布量**: リクエストあたり0.01 ETH
1212
- **クールダウン**: アドレスあたり1日1回のリクエスト
1313

1414
### テストネットETHの入手方法

0 commit comments

Comments
 (0)