zlysunshine/aave-bns-demo-HF

Aave Network Observatory

The Aave Network Observatory is a new, standalone Hugging Face Docker Space for exploring Aave and GHO through four independent scientific dimensions: participation, activity distribution, structural position, and infrastructure dependence.

It is a question-driven research interface—not a trading terminal or a composite decentralization score—and was implemented as a fresh Observatory codebase from the design branch. Its signature journey is:

Question → animated evidence → network exploration → theory/simulation context → interpretation boundary → provenance

[image]

MVP status

The working MVP includes:

• —an animated React Three Fiber observatory hero with reduced-motion and manual-pause support;
• —four interactive Decentralization Pulse cards, with no composite score;
• —four question-driven Evidence Stories with D3 analytical charts;
• —a 3D Ethereum/Arbitrum network explorer with action, role, week, and Full/Core controls;
• —an event-week Time Machine and evidence-gated node inspector;
• —a synchronized Core–Periphery Lab for k-core, Borgatti–Everett, Rombach, and PageRank;
• —a Theory → Simulation → Evidence bridge using released synthetic simulation rows;
• —an eleven-step Trace This Claim interaction;
• —a constrained, curated Ask the Observatory evidence lookup;
• —a versioned compact artifact, machine-readable manifest, schema/checksum validation, tests, and Docker deployment on port 7860.

The current source dataset snapshot is explicitly provisional. The app preserves that release boundary in the interface and does not present the dataset as a finalized public Hugging Face release.

Screenshots

Product interaction

The original design roadmap is preserved and implemented as a tighter evidence loop:

flowchart TD
    Q["Research question"] --> E["Animated Evidence Story"]
    E --> N["3D network + Time Machine"]
    E --> T["Theory + synthetic simulation"]
    N --> B["Interpretation boundary"]
    T --> B
    B --> P["Trace claim provenance"]
    P -. "reproduce or challenge" .-> E

Four-dimensional decentralization

The interface never averages these dimensions into a scalar score.

flowchart TD
    D["Decentralization question"] --> P["Participation"]
    D --> A["Activity distribution"]
    D --> S["Structural position"]
    D --> I["Infrastructure dependence"]
    P --> O["Observed / derived address evidence"]
    A --> O
    S --> M["Method-dependent network evidence"]
    I --> G["Evidence gated when routes are unavailable"]

Current MVP architecture

flowchart TD
    UI["Next.js 16 + React 19 UI"] --> V["R3F 3D + D3 charts + motion"]
    UI --> X["Question, Core, Theory, Ask modules"]
    V --> C["Typed compact observatory artifact"]
    X --> C
    C --> M["Artifact manifest + source checksums"]
    M --> D["Pinned data repository snapshot"]
    M --> K["Pinned code/configuration snapshot"]
    UI --> H["Standalone Node server"]
    H --> S["Docker Space · port 7860"]

Expensive graph construction, centrality, and simulation work is not recomputed in the browser. The Space ships only compact, versioned outputs suitable for the demo.

Evidence sources and artifact contract

The app artifact is observatory-v1.json. Its source paths, immutable commits, source blob hashes, source SHA-256 values, row counts, display-graph contract, and output checksum are recorded in artifact-manifest.json.

Current artifact SHA-256:

95208f3d2e8e0733728a1f98739915933f09564e39eb2e36fa7f9f7e3ec647a8

Display graph disclosure

No governed address-level node/edge web artifact is available in the pinned source release. The 3D canvases therefore use a deterministic abstract display backbone and never synthesize blockchain addresses, entity labels, core memberships, or identities.

Visualization uses a display backbone/sample; reported statistics use the full validated network.

Evidence status language

Addresses are protocol identifiers. They are not silently relabeled as people, independent users, independent economic actors, or verified entities. Pool-event-frequency HHI is not a measure of capital, liquidity, ownership, wealth, risk, welfare, or governance power.

Trace This Claim

Every major result exposes this provenance path in the product itself:

flowchart TD
    C["Claim"] --> V["Visualization"]
    V --> M["Metric definition"]
    M --> A["Aggregation / network construction"]
    A --> P["Processed data"]
    P --> E["Decoded protocol events"]
    E --> R["Raw / source evidence"]
    R --> D["Dataset version + Git commit"]
    D --> K["Code + configuration"]
    K --> H["Manifest + checksum"]

The interaction reveals both supporting evidence and the point where evidence stops. Missing provenance blocks stronger language; it is not replaced with an inferred fact.

Repository inventory

app/                         Next.js App Router shell and global visual system
components/                  3D, evidence, core, theory, provenance, and Ask modules
lib/                         typed artifact access and scientific view models
public/artifacts/            compact artifact and machine-readable manifest
public/screenshots/          seven rendered MVP views used in this README
scripts/                     artifact, link, browser, and screenshot validation
tests/                       schema/claim unit tests and Playwright journey test
docs/                        preserved product design, evidence rules, and roadmap
Dockerfile                   multi-stage standalone Space image
playwright.config.ts         reproducible rendered interaction QA
next.config.ts               standalone Next.js production configuration

Local development and preview

Requirements: Node.js 20.9+ (Node 22 recommended) and npm.

npm ci
npm run dev

Open http://localhost:7860.

Production preview—the same standalone server used by the Docker image:

npm ci
npm run build
PORT=7860 HOSTNAME=0.0.0.0 npm run start

Open http://localhost:7860. To capture the checked-in views from a running preview:

PLAYWRIGHT_BASE_URL=http://127.0.0.1:7860 npm run screenshots

Without PLAYWRIGHT_BASE_URL, screenshot/E2E tooling serves the production prerender through Playwright request interception. This avoids a second dev server while exercising the built HTML, CSS, JavaScript, Three.js canvases, and interactions.

Validation

Run the complete non-browser release gate:

npm run verify

Run the rendered journey and reduced-motion check:

npm run test:e2e

Run the standalone port-7860 HTTP smoke test:

npm run smoke:http

Individual checks:

Docker and Hugging Face deployment

Local Docker validation:

docker build -t aave-network-observatory .
docker run --rm -p 7860:7860 aave-network-observatory

The root metadata declares sdk: docker and app_port: 7860. The image:

1. 1.installs dependencies with npm ci;
2. 2.creates a production Next.js standalone build;
3. 3.copies only the standalone server, static chunks, and public assets;
4. 4.runs as a non-root user;
5. 5.binds 0.0.0.0:7860.

To publish, create or select the Hugging Face Space, add it as a remote, and push the reviewed release branch/commit. Do not publish a source dataset revision until the data repository’s release blockers are resolved.

Known limitations and scientific gates

• —Provisional source release: dataset version 0.2.0-rc26-provisional is still marked blocked/not ready for final public dataset publication in the pinned data repository. Dataset/license/namespace publication decisions remain upstream.
• —Abstract display backbone: address-level display nodes, longitudinal node memberships, and released layout snapshots are unavailable. Display nodes are explanatory geometry only.
• —Economic actors: address ownership/control resolution is not available; independent users/economic actors are not identified.
• —Core-method agreement: aggregate k-core and PageRank summaries are released, but Borgatti–Everett/Rombach memberships and cross-method agreement values are not packaged; those panels teach the methods and remain evidence gated.
• —Infrastructure routes: verified bridge/message-route dependencies, route concentration, and removal resilience are not identified empirically.
• —Causal effects: before/after and cross-chain views are comparative/descriptive. They do not identify causal effects of GHO activation or expansion.
• —Action-week coverage: governed weekly action detail is uneven across chain/action combinations; unavailable combinations remain visibly gated.
• —Deployment: the repository is Docker-Space ready, but production Hugging Face deployment and canonical dataset revision locking are separate release actions.
• —Licensing: the Space repository and provisional dataset need explicit owner-approved release licensing before a final public production release; the Space metadata therefore uses license: other.

Roadmap

The design-first roadmap is preserved, with the new MVP now covering stages 1–6 at an evidence-bounded depth. Stages 7–9 remain gated on new verified sources.

flowchart TD
    F["0 · Design + evidence grammar"] --> M["1–6 · Working Observatory MVP"]
    M --> Q["Richer temporal and structural artifacts"]
    Q --> I["7 · Verified infrastructure routes"]
    I --> A["8 · Economic-actor / decision provenance"]
    A --> G["9 · Reusable multi-protocol framework"]
    E["Persistent rule: no claim outruns evidence"] -.-> M
    E -.-> Q
    E -.-> I
    E -.-> A
    E -.-> G

Next release priorities:

1. 1.lock the public dataset namespace, revision, license, and checksums;
2. 2.release governed node/edge display-backbone snapshots and weekly layouts;
3. 3.package BE/Rombach memberships and cross-method agreement outputs;
4. 4.validate the Docker image in the production Hugging Face Space;
5. 5.add route/resilience or actor-level views only after their evidence gates pass.

Design documentation

• —MVP product and interaction design
• —Evidence and visualization principles
• —Product roadmap

Source repositories:

• —Data: aave-bns-data-HF
• —Code: aave-bns-code
• —Space: aave-bns-demo-HF