Skip to content

Commit ce9a0dc

Browse files
jhfnetboyjhfnetboy
committed
docs(sdk): sync v0.16.23 updates from sdk repo
1 parent fc44961 commit ce9a0dc

8 files changed

Lines changed: 900 additions & 21 deletions

File tree

‎api/@aastar/analytics.md‎

Lines changed: 204 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,207 @@
1-
# 📊 AAStar Gas Analytics & Experimentation
1+
# Analytics Package (AAStar Gas Analytics & Experimentation)
2+
3+
> **Status**: Active | **Version**: 3.0 (PhD Research Edition)
4+
5+
This module is the core data intelligence engine for the AAStar ecosystem. It supports **Scientific Data Collection** for the "Asset-Oriented Abstraction" thesis with rigorous, on-chain ground truth verification.
6+
7+
```bash
8+
# 快速入口（从 aastar-sdk 根目录运行）
9+
10+
# 收集 OP Mainnet paymaster 基线
11+
pnpm tsx packages/analytics/scripts/collect_paymaster_baselines.ts --network op-mainnet --n 50
12+
13+
# 收集 Paper7 专属数据
14+
bash packages/analytics/scripts/run_paper7_exclusive_data.sh --network anvil --cycles 5
15+
16+
# 全流程协调器
17+
pnpm tsx packages/analytics/scripts/run_analytics_coordinator.ts --network sepolia
18+
19+
# Gas 分析报告文档
20+
packages/analytics/docs/OP_Mainnet_Gas_Analysis_Report.md
21+
```
22+
23+
---
24+
25+
## System Architecture
26+
27+
The Analytics module operates on a **Pipeline Architecture** composed of three distinct stages: **Generation**, **Collection**, and **Analysis**.
28+
29+
```mermaid
30+
graph TD
31+
subgraph "Phase 1: Traffic Generation"
32+
TG[Traffic Coordinator] -->|Trigger| G1[EOA Generator]
33+
TG -->|Trigger| G2[Standard AA Generator]
34+
TG -->|Trigger| G3[SuperPaymaster Generator]
35+
TG -->|Trigger| G4[Paymaster V4 Generator]
36+
G1 & G2 & G3 & G4 -->|Execute Tx| BLOCKCHAIN((Blockchain))
37+
end
38+
39+
subgraph "Phase 2: Data Collection"
40+
BLOCKCHAIN -->|Receipts| HF[Historical Fetcher]
41+
HF -->|Raw Data| CACHE[(Data Store / JSON)]
42+
style HF fill:#f9f,stroke:#333
43+
end
44+
45+
subgraph "Phase 3: Analysis Engine"
46+
CACHE -->|Load| DC[DataCollector]
47+
DC -->|Enrich| CC[CostCalculator]
48+
CC --> AA[Attribution Analyzer]
49+
CC --> CA[Comparison Analyzer]
50+
CC --> TA[Trend Analyzer]
51+
AA & CA & TA --> REPORT[Final Academic Report]
52+
end
53+
```
54+
55+
---
56+
57+
## Directory Structure
58+
59+
```text
60+
packages/analytics/
61+
├── src/
62+
│ ├── generators/ # Traffic Generation Logic
63+
│ ├── collectors/ # Etherscan/RPC Fetchers
64+
│ │ └── EventFetcher.ts # On-chain UserOperationEvent collector
65+
│ ├── core/ # Core Analysis Engines
66+
│ ├── analyzers/ # Specific Analysis Strategies
67+
│ └── gas-analyzer.ts # Main Entry Point
68+
├── scripts/ # ← All data collection scripts (consolidated)
69+
│ ├── collect_paymaster_baselines.ts # OP mainnet V4/SuperPM baselines
70+
│ ├── collect_eoa_erc20_baseline.ts # EOA ERC20 transfer baseline
71+
│ ├── collect_industry_baseline.ts # Alchemy/Pimlico baselines
72+
│ ├── compute_cost_summary.ts # Aggregated cost breakdown table
73+
│ ├── gasless-collect.ts # Gasless data collector (OP mainnet)
74+
│ ├── paper7-exclusive-data.ts # Paper7 closed-loop data (anvil)
75+
│ ├── paper7_credit_loop.ts # Credit→Debt→Repay cycle runner
76+
│ ├── paper7_reputation_credit.ts # Reputation→Credit mapping runner
77+
│ ├── run_analytics_coordinator.ts # Full pipeline coordinator
78+
│ ├── run_paper7_exclusive_data.sh # Paper7 shell wrapper (CI-friendly)
79+
│ ├── fetch-tx-hashes.ts # TX hash fetcher utility
80+
│ └── scrape-tx.ts # Puppeteer Etherscan scraper
81+
├── docs/ # ← Research reports and analysis documents
82+
│ └── OP_Mainnet_Gas_Analysis_Report.md # Paper3/Paper7 gas cost evidence
83+
├── data/ # Raw data store
84+
│ ├── gasless_data_collection.csv # T1/T2/T2.1/T5 baseline (v1)
85+
│ ├── gasless_data_collection_v2.csv # Controlled single-UserOp (v2)
86+
│ ├── gasless_metrics_detailed.csv # Full L1/L2 fee decomposition
87+
│ ├── industry_paymaster_baselines.csv # Alchemy, Pimlico on-chain baselines
88+
│ ├── eoa_erc20_baseline.csv # Raw EOA transfer baseline
89+
│ ├── paper7_exclusive/ # Paper7 credit/reputation/liquidity
90+
│ └── paper_gas_op_mainnet/ # Paper3 per-date controlled datasets
91+
│ ├── 2026-02-17/ # V4 n=36, SuperPM n=43
92+
│ └── 2026-02-18/ # V4/SuperPM with sender (n=50)
93+
└── reports/ # HTML/Markdown summaries
94+
```
95+
96+
---
97+
98+
## Workflows
99+
100+
### A. Collect OP Mainnet Paymaster Baselines (Paper3)
101+
```bash
102+
# V4 baseline: strict single UserOp + ERC20 transfer filter
103+
pnpm tsx packages/analytics/scripts/collect_paymaster_baselines.ts \
104+
--network op-mainnet --type v4 --n 50 --strict-transfer --single-userop
105+
106+
# SuperPaymaster baseline
107+
pnpm tsx packages/analytics/scripts/collect_paymaster_baselines.ts \
108+
--network op-mainnet --type super --n 50
109+
```
110+
111+
### B. Run Full Experiment (Coordinator)
112+
```bash
113+
# 1. Fetch History -> 2. Generate Missing Traffic -> 3. Analyze
114+
pnpm tsx packages/analytics/scripts/run_analytics_coordinator.ts --network sepolia
115+
```
116+
117+
### C. Fetch Historical Data Only
118+
```bash
119+
pnpm tsx packages/analytics/scripts/run_analytics_coordinator.ts --fetch-only --network op-sepolia
120+
```
121+
122+
### D. Transaction Scraper (Etherscan)
123+
Reads from `data/gasless_data_collection.csv`, outputs to `data/gasless_metrics_detailed.csv`.
124+
```bash
125+
pnpm tsx packages/analytics/scripts/scrape-tx.ts
126+
```
127+
128+
---
129+
130+
## Data Directory
131+
132+
| File | Description |
133+
|------|-------------|
134+
| `data/gasless_data_collection.csv` | T1/T2/T2.1/T5 records with TxHash + Label |
135+
| `data/gasless_data_collection_v2.csv` | High-fidelity controlled dataset (single-UserOp, ERC20) |
136+
| `data/gasless_metrics_detailed.csv` | L1 Fee, L2 Fee, Gas Used (Puppeteer scraped) |
137+
| `data/industry_paymaster_baselines.csv` | Alchemy (mean=257k) + Pimlico (mean=387k) on-chain baselines |
138+
| `data/eoa_erc20_baseline.csv` | Raw EOA ERC20 transfer baseline |
139+
| `data/paper7_exclusive/` | Credit cycle + reputation + liquidity simulation (Anvil) |
140+
| `data/paper_gas_op_mainnet/2026-02-17/` | V4 n=36, SuperPM n=43 (strict filter) |
141+
| `data/paper_gas_op_mainnet/2026-02-18/` | V4/SuperPM with sender field (n=50) |
142+
143+
---
144+
145+
## Paper7 Exclusive Data (Credit / Reputation / Liquidity)
146+
147+
Paper7 requires a distinct set of evidence to prove **CommunityFi closed-loop semantics**:
148+
149+
- **Reputation → Credit**: contribution/reputation synced into Registry, credit limit observed to change
150+
- **Credit → Debt → Repay**: debt recorded in Paymaster/Registry, cleared via xPNTs
151+
- **Liquidity (Baseline)**: simulation curve showing gas-redeemable vs non-redeemable points over time
152+
153+
### Running
154+
155+
```bash
156+
# Unified entry (Anvil auto-start, deploy, sync, run all subtasks)
157+
pnpm exec tsx packages/analytics/scripts/paper7-exclusive-data.ts --network anvil --cycles 5
158+
159+
# Shell wrapper (CI-friendly)
160+
bash packages/analytics/scripts/run_paper7_exclusive_data.sh --network anvil --cycles 5
161+
```
162+
163+
### Output Structure
164+
165+
```text
166+
data/paper7_exclusive/<timestamp>/
167+
credit_cycle_1.json # credit→debt→repay per account
168+
...
169+
reputation_credit.json # reputation sync → credit limit mapping
170+
liquidity_velocity_simulation.csv
171+
synced_config.anvil.json
172+
```
173+
174+
#### `credit_cycle_*.json` fields
175+
- `creditLimitWei / creditLimitEth`: credit limit in Registry
176+
- `debtBeforeWei / debtAfterRecordWei / debtAfterRepayWei`: debt lifecycle
177+
- `gasUsed.*`: per-step gas units (approve, setCreditTier, recordDebt, mint)
178+
179+
#### `reputation_credit.json` fields
180+
- `score` / `globalReputation` / `creditLimitWei`: reputation → credit mapping
181+
- `gasUsed.*`: setRule, syncToRegistry, etc.
182+
183+
#### `liquidity_velocity_simulation.csv` columns
184+
- `day`: simulation step
185+
- `points_gas_redeemable`: points stock when gas-redeemable
186+
- `points_baseline`: points stock without gas redemption
187+
188+
---
189+
190+
## Key Modules
191+
192+
### 1. Traffic Generators (`src/generators/`)
193+
- **EOAGenerator**: Baseline ETH transfers for network cost measurement.
194+
- **SuperPaymasterGenerator**: Treatment group — credit/asset-oriented gasless model.
195+
- **PaymasterV4Generator**: Treatment group B — deposit model for comparison.
196+
197+
### 2. Data Collectors (`src/collectors/`)
198+
- **HistoricalFetcher**: Etherscan/OptimismScan API for full transaction histories.
199+
- **EventFetcher**: On-chain `UserOperationEvent` log collector with strict filtering.
200+
201+
### 3. Analysis Engine (`src/core/` & `src/analyzers/`)
202+
- **Attribution**: L1 Security | L2 Execution | Protocol Overhead breakdown.
203+
- **Comparison**: T1 vs T2 vs T2.1 vs T5 vs industry baselines.
204+
2205

3206
> **Status**: Active | **Version**: 3.0 (PhD Research Edition)
4207

0 commit comments

Comments
 (0)