Apppublic

zlysunshine/aave-bns-playground

sourceHugging Facemitupdated 1mo agoView on Hugging Face

1likes

App README

Aave-BNS Simulation Playground

A guided, interactive exhibit for the theorem-consistent Aave network simulation.

Open the Hugging Face Space · Simulation source · Full 720p walkthrough

</div>

Evidence boundary: every result shown here is a synthetic theorem-validation output. The app does not display observed Aave transactions, estimate historical GHO effects, or make causal claims.

25-second walkthrough

Click the animation to open the interactive Space. The same walkthrough is embedded as a controllable 720p video inside the Hugging Face app.

The animation is rendered with Manim Community from the original RC23 simulation functions. It presents, in order:

1.stable network-feedback choices κ = 0.25, 0.75, and 0.95;
2.the separately labeled κ = 1.05 divergent stress test;
3.actual simultaneous-activation convergence paths: 18, 79, and 438 iterations;
4.equal-mass growth allocations and their median activity/HHI outcomes;
5.the difference between a 10% route loss and a 40% shared-component loss.

User experience walkthrough

1. Enter the lab

Open the Space and choose Begin guided experiment. The hero animation is only an orientation layer; all reported values in the lab are tied to the RC23 parameter set below.

2. Choose one research question

Module	What the user selects	What changes on screen
Network amplification	`κ = 0.25`, `0.75`, `0.95`, or the separate `1.05` stress test	Network pulse, stability label, and iterations to tolerance
Growth × concentration	Peripheral, proportional, or incumbent allocation	Median activity change and median HHI change
Cross-chain resilience	Four independent routes or four routes with a shared core	Largest route loss versus largest shared-component loss

3. Run the synthetic experiment

Select Run synthetic experiment after changing a parameter. The central network animation and live interpretation update together. Pause/resume motion remains available for accessibility and close reading.

4. Read the result and its boundary together

Each module keeps three things visible at the same time:

—the selected assumption;
—the computed mechanism-level result;
—what the result does not establish empirically or causally.

5. Interrogate the assumptions

The grounded Q&A explains why feedback near one matters, why activity growth can coexist with increasing concentration, and why nominal route diversity can conceal a shared failure domain. Answers are fixed to the documented model boundary rather than generated dynamically.

Current RC23 results

Mechanism	Scenario	Result shown in the Space
Network feedback	`κ = 0.25`	converges in 18 iterations
Network feedback	`κ = 0.75`	converges in 79 iterations
Network feedback	`κ = 0.95`	converges in 438 iterations
Network feedback	`κ = 1.05`	divergent stress test; no stable linear benchmark
Growth × concentration	Peripheral expansion	activity `+14.78%`, HHI `−4.17%`
Growth × concentration	Proportional benchmark	activity `+18.85%`, HHI `≈ 0%`
Growth × concentration	Incumbent amplification	activity `+26.34%`, HHI `+4.77%`
Cross-chain resilience	Four independent routes	route loss `10%`, component loss `10%`
Cross-chain resilience	Four nominal routes, shared core	route loss `10%`, component loss `40%`

Run the Space locally

Node 22 or newer is required. The repository uses port 7860 for both development and production previews.

Recommended local deployment workflow

Stop an existing development server with Ctrl+C, then update and validate the checkout:

bash

git checkout main
git restore next-env.d.ts
git pull --ff-only origin main
rm -rf .next

npm ci
npm run typecheck
npm run build

next-env.d.ts is generated by Next.js and may appear as a local modification after development. Restoring it before pulling keeps the checkout clean.

Clear port 7860 safely

First inspect the process using the port:

bash

lsof -nP -iTCP:7860 -sTCP:LISTEN

If a process appears, inspect its command before stopping it:

bash

PORT_PID="$(lsof -tiTCP:7860 -sTCP:LISTEN || true)"
[ -z "$PORT_PID" ] || ps -fp $PORT_PID

Only continue if the displayed process is the stale Node/Next.js server for this playground. Try a graceful shutdown first:

bash

PORT_PID="$(lsof -tiTCP:7860 -sTCP:LISTEN || true)"
if [ -n "$PORT_PID" ]; then
  kill $PORT_PID
  sleep 2
fi

lsof -nP -iTCP:7860 -sTCP:LISTEN

No output from the final lsof command means the port is free. If the confirmed stale Node process did not stop, use a forced shutdown only as the fallback:

bash

PORT_PID="$(lsof -tiTCP:7860 -sTCP:LISTEN || true)"
if [ -n "$PORT_PID" ]; then
  ps -fp $PORT_PID
  kill -9 $PORT_PID
  sleep 1
fi

lsof -nP -iTCP:7860 -sTCP:LISTEN

Do not kill an unfamiliar process. Use a different preview port instead:

bash

npx next dev -H 0.0.0.0 -p 7861

Start and inspect the preview

After port 7860 is free:

bash

npm run dev

Open:

text

http://localhost:7860/
http://localhost:7860/experiments/network-amplification
http://localhost:7860/experiments/growth-concentration
http://localhost:7860/experiments/cross-chain-resilience
http://localhost:7860/#theory-background

For a production-equivalent local preview after npm run build succeeds:

bash

npm run start

The npm audit report may list dependency vulnerabilities independently of local startup. Do not run npm audit fix --force merely to resolve a port conflict, because forced upgrades can change the tested dependency set.

Reproduce the Hugging Face Docker runtime

bash

docker build -t aave-bns-playground .
docker run --rm -p 7860:7860 aave-bns-playground

The production Docker image uses Next.js standalone output, listens on 0.0.0.0:7860, and serves the Manim MP4 directly from public/media/.

Regenerate the Manim media

The committed animation source is `media/manim_walkthrough.py`. It imports the original functions from a pinned checkout of sunshineluyao/aave-bns-simulation rather than reimplementing the figure logic.

bash

git clone https://github.com/sunshineluyao/aave-bns-simulation.git ../aave-bns-simulation
git -C ../aave-bns-simulation checkout 7f9a0d524be777858f25156c5fe892a3a7798b20

python -m venv .venv
. .venv/bin/activate
pip install -r media/requirements-manim.txt

AAVE_BNS_SIMULATION_DIR=../aave-bns-simulation \
  manim -qm media/manim_walkthrough.py AaveBNSWalkthrough

Manim's medium-quality preset produces a 1280×720 MP4 at 30 fps. The GitHub GIF is derived from that master:

bash

ffmpeg -i AaveBNSWalkthrough.mp4 \
  -vf "fps=10,scale=640:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=96:stats_mode=diff[p];[s1][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle" \
  -loop 0 docs/assets/aave-bns-walkthrough.gif

Provenance and reproducibility

—Simulation release: rc23_theory_simulation
—Simulation commit: 7f9a0d524be777858f25156c5fe892a3a7798b20
—Primary deterministic seed: 20260819
—Animation engine: Manim Community 0.20.1
—MP4 SHA-256: 47fa941038c8baa8b0d9c5bc195d8e228332a368f278e38624aeebdb0fe25191
—GIF SHA-256: e4a34db5e9e72f7f1f9bc8e35c8c6c34968fc6598712cf7a0940b7c2189a8215

The Space intentionally exposes only validated theorem-baseline mechanisms. Behavioral ABM, multi-agent reinforcement learning, empirical calibration, constrained LLM agents, and a digital twin remain future research stages—not selectable features in this release.

Repository map

text

app/                         interactive Next.js Space
public/media/                embedded MP4 and poster
docs/assets/                 README GIF and poster
media/manim_walkthrough.py   reproducible Manim scene
Dockerfile                   Hugging Face Docker entrypoint

Citation

If you reuse the interface or media, cite the simulation repository and preserve the synthetic/empirical/causal evidence boundary in downstream descriptions.