Marionette Light

1. Requirements

• Python 3.10+ — from python.org (on Windows, check “Add Python to PATH”).
• Internet — queries go to Etherscan.
• Etherscan API key — free at etherscan.io/apis (v2 covers the other chains too).

2. Install

Option A — ZIP

1. Download the ZIP and unzip it.
2. Open a terminal inside the Marionette_Light-main folder.

Option B — Git

git clone https://github.com/Bottegatecnologica/Marionette_Light.git
cd Marionette_Light

Dependencies & start

pip install -r requirements.txt
python app.py

Your browser opens http://127.0.0.1:8766. Leave the terminal running while you use the app.

3. Etherscan API key

1. Create an Etherscan account and generate an API key.
2. In the app, paste it into Your Etherscan API key — stored only in this browser (localStorage).
3. Never commit the key or put it in source.

Free-tier rate limits: heavy scans may slow down; wait and retry.

4. First run (typical flow)

1. Chain — pick the contract’s chain (e.g. Ethereum).
2. Contract addresses — paste one or more contracts (one per line).
3. Expand control tree — builds the graph: deployer, owner, proxy admin, roles, Safe signers, etc.
4. Click a “hand” node (Controller / Signer / Safe) → Expand to find more contracts that hand controls.
5. Look for plotted addresses on other chains — searches the same EOAs on sibling chains. Check Include testnets for Sepolia & friends.
6. Hands tab — ranked controllers; filter with the chain chips.
7. Export — save the graph JSON; Import to reload later.

5. UI at a glance

• Layout — each chain is a column; seed contracts at the bottom, hands above (marionette strings).
• Panels — side arrows collapse left/right to widen the canvas.
• Search (top) — jump to a plotted address.
• Selection — Copy, Explorer, Expand; Edges / Hands tabs.
• SAME_AS (blue dashed arcs) — same address on another chain.
• Double-click a node/edge → Expand.

6. What edges mean

• DEPLOYED — deployed it (Etherscan creation).
• ADMIN_OF — owner / proxy admin / DEFAULT_ADMIN (on-chain checks).
• SIGNER_OF — Safe owner.
• IMPLEMENTATION_OF — proxy implementation (not a “hand”).
• FUNDED — first inbound ETH: context only, not control.
• SAME_AS — same address on another chain.

7. Troubleshooting

pip not found

Reinstall Python with “Add to PATH”, or use py -m pip install -r requirements.txt.

Page doesn’t open

Check the terminal shows Running on http://127.0.0.1:8766 and open that URL manually.

Few or no edges

Bad API key, rate limit, or the contract doesn’t expose standard owner() / Safe / proxy slots. Try Expand on a hand or another chain.

Firewall / antivirus

Outbound HTTPS to api.etherscan.io must be allowed.