> For the complete documentation index, see [llms.txt](https://whitepaper.litho.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.litho.ai/docs/quickstart/dev-setup.md).

# Developer Setup Guide

Get a fully working Lithosphere development environment — chain, indexer, API, and block explorer — running on your machine with a single command. No prior blockchain experience required.

***

## Prerequisites

You only need two things installed:

| Tool               | Download                                                                              |
| ------------------ | ------------------------------------------------------------------------------------- |
| **Docker Desktop** | [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/) |
| **VS Code**        | [code.visualstudio.com](https://code.visualstudio.com/)                               |

> **Windows users:** Docker Desktop will prompt you to enable WSL 2 during installation. Accept the defaults — everything works out of the box.

After installing VS Code, add the **Dev Containers** extension:

```
ext install ms-vscode-remote.remote-containers
```

That's it. Node.js, pnpm, Go, Solidity tooling, and all project dependencies are installed automatically inside the container.

***

## 1 — Open the DevContainer (The "Magic" Button)

1. Clone the repo and open it in VS Code:

   ```bash
   git clone https://github.com/KaJLabs/lithosphere.git
   code lithosphere
   ```
2. VS Code will detect the `.devcontainer` configuration and show a notification:

   > **Folder contains a Dev Container configuration file. Reopen folder to develop in a container?**

   Click **"Reopen in Container"**.

   *If you miss the notification, open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run:*

   ```
   Dev Containers: Reopen in Container
   ```
3. **Wait for the build.** The first launch pulls the base image, installs tooling, and runs `pnpm install` across the monorepo. This takes **10–15 minutes** on a typical connection. Subsequent opens are near-instant.

When the terminal shows `Done in …s`, your environment is ready.

### What You Get

The DevContainer pre-installs everything a Lithosphere contributor needs:

| Tool / Extension           | Purpose                                                |
| -------------------------- | ------------------------------------------------------ |
| Node.js 20 + pnpm          | Runtime & package manager                              |
| Go 1.23                    | For chain-level tooling                                |
| Docker CLI + Compose       | Run the local stack from inside VS Code                |
| GitHub CLI                 | PR workflows without leaving the terminal              |
| ESLint + Prettier          | Auto-format on save                                    |
| Hardhat Solidity extension | Syntax highlighting, go-to-definition for `.sol` files |

***

## 2 — Start the Network

Open the integrated terminal inside VS Code and run:

```bash
cd Makalu
make up
```

This builds and launches **six services** via Docker Compose:

| Service             | URL / Port              | Description                                         |
| ------------------- | ----------------------- | --------------------------------------------------- |
| **LithoVM (Anvil)** | `http://localhost:8545` | Local EVM chain (Chain ID `700777`, 2 s block time) |
| **API (GraphQL)**   | `http://localhost:4000` | Backend API with GraphQL playground                 |
| **Indexer**         | `http://localhost:3001` | Blockchain indexer (→ Postgres)                     |
| **Explorer**        | `http://localhost:3000` | Block explorer UI                                   |
| **PostgreSQL**      | `localhost:5432`        | Indexed chain data                                  |
| **Redis**           | `localhost:6379`        | Caching layer                                       |

Once `make up` finishes, open <http://localhost:3000> in your browser to see the block explorer.

***

## 3 — Seed the Devnet

With the stack running, seed it with test data:

```bash
make seed
```

This executes a seed script that does four things:

1. **Funds 5 mock wallets** with 1 000 LITHO each.
2. **Deploys a LEP100 token contract** (the Lithosphere multi-token standard).
3. **Mints 1 000 LEP100 tokens** to each mock wallet.
4. **Generates transfer activity** between wallets so the explorer has data to display.

You'll see 16 confirmed transactions in the terminal output. Refresh the explorer to see them.

***

## 4 — Connect MetaMask

Add the local Lithosphere devnet to MetaMask so you can interact with it from your browser.

### Add the Network

Open MetaMask → **Settings → Networks → Add Network → Add a network manually** and enter:

| Field              | Value                   |
| ------------------ | ----------------------- |
| Network Name       | `Lithosphere Devnet`    |
| RPC URL            | `http://localhost:8545` |
| Chain ID           | `700777`                |
| Currency Symbol    | `LITHO`                 |
| Block Explorer URL | `http://localhost:3000` |

### Import a Funded Wallet

After seeding, five wallets are pre-funded with 1 000 LITHO and 1 000 LEP100 tokens. Import any of them into MetaMask via **Import Account → Private Key**:

| Wallet | Address                                      | Private Key                                                          |
| ------ | -------------------------------------------- | -------------------------------------------------------------------- |
| Mock 1 | `0x9965507D1a55bcC2695C58ba16FB37d819B0A4dc` | `0x8b3a350cf5c34c9194ca85829a2df0ec3153be0318b5e2d3348e872092edffba` |
| Mock 2 | `0x976EA74026E726554dB657fA54763abd0C3a0aa9` | `0x92db14e403b83dfe3df233f83dfa3a0d7096f21ca9b0d6d6b8d88b2b4ec1564e` |
| Mock 3 | `0x14dC79964da2C08b23698B3D3cc7Ca32193d9955` | `0x4bbbf85ce3377467afe5d46f804f221813b2bb87f24d81f60f1fcdbf7cbf4356` |
| Mock 4 | `0x23618e81E3f5cdF7f54C3d65f7FBc0aBf5B21E8f` | `0xdbda1821b80551c9d65939329250298aa3472ba22feea921c0cf5d620ea67b97` |
| Mock 5 | `0xa0Ee7A142d267C1f36714E4a8F75612F20a79720` | `0x2a871d0798f97d79848a013d4936a73bf4cc922c825d33c1cf7073dff6d409c6` |

> **Warning:** These are deterministic Anvil keys. **Never send real funds to these addresses.** They are publicly known and used by every developer running this stack.

***

## 5 — Day-to-Day Commands

All Makefile targets run from the `Makalu/` directory:

| Command        | What It Does                                                             |
| -------------- | ------------------------------------------------------------------------ |
| `make up`      | Build and start all services (waits for health checks)                   |
| `make down`    | Stop all services (volumes are preserved)                                |
| `make restart` | Stop → Start                                                             |
| `make seed`    | Fund wallets + deploy LEP100 contract                                    |
| `make logs`    | Tail live logs from all services (`Ctrl+C` to stop)                      |
| `make status`  | Show container status                                                    |
| `make clean`   | **Factory reset** — removes all containers, volumes, and build artifacts |
| `make help`    | Print the command reference                                              |

***

## Troubleshooting

### "The install is taking forever…"

The first `pnpm install` inside the DevContainer downloads \~1 300 packages for the entire monorepo. On a slower connection this can take **10–15 minutes**. This is normal — subsequent container starts reuse the cached `node_modules`.

### "Port 8545 (or 3000, 4000…) is already in use"

Another process is binding that port. Stop the stack and check:

```bash
make down

# On Linux / macOS / WSL:
lsof -i :8545

# On Windows (PowerShell):
netstat -ano | findstr :8545
```

Kill the conflicting process, then `make up` again.

### "Docker commands don't work inside the container"

The DevContainer mounts the host Docker socket. If you see permission errors:

```bash
# Verify the socket is mounted
ls -la /var/run/docker.sock

# Check your user is in the docker group
groups
```

If `docker` is missing from the groups list, restart the container via the Command Palette → **Dev Containers: Rebuild Container**.

### "make seed fails with 'connection refused'"

The chain isn't running yet. Start the stack first:

```bash
make up
# Wait for "Stack is up" message, then:
make seed
```

### "I want to start fresh"

```bash
make clean   # Wipes everything: containers, volumes, build artifacts
make up      # Rebuild from scratch
make seed    # Re-seed the devnet
```

***

## Next Steps

* [CLI Tools Reference](https://github.com/KaJLabs/lithosphere/blob/main/docs/quickstart/quickstart/cli-tools.md) — Explore the `lithod` binary and `create-litho-app` scaffolding tool.
* [Smart Contracts](https://github.com/KaJLabs/lithosphere/blob/main/docs/quickstart/developers/smart-contracts.md) — Write and deploy LEP100 contracts on Lithosphere.
* [Hardhat Example](https://github.com/KaJLabs/lithosphere/blob/main/docs/quickstart/developers/examples/hardhat-example.md) — A step-by-step Hardhat project targeting the local devnet.
* [Architecture Overview](https://github.com/KaJLabs/lithosphere/blob/main/docs/quickstart/introduction/architecture-overview.md) — Understand how the chain, indexer, and API fit together.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whitepaper.litho.ai/docs/quickstart/dev-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.