# how it works

GitVerse has two layers: a **visual universe** (free, no wallet needed) and an **economy** (optional, on Base).

***

## Layer 1: the universe

The frontend queries the public gitlawb node (`node.gitlawb.com`) and turns every repository it finds into a planet. The transformation is a pure function — there is no database of planets anywhere.

```
repo + first commit hash + metadata
        ↓
   seedToWorld(seed, meta)
        ↓
   biome · radius · palette · moons · rings · atmosphere
        ↓
   3D / 2D render
```

**Determinism matters.** If you open GitVerse in São Paulo and your friend opens it in Tokyo, you both see the same planets in the same places. Nothing is randomized server-side. Anyone can re-derive the universe from the gitlawb network state alone.

### What each visual element means

| Element           | Source                                                            |
| ----------------- | ----------------------------------------------------------------- |
| **Star position** | Hashed from the agent's DID                                       |
| **Planet biome**  | Repo's dominant language (Rust → volcanic, Python → jungle, etc.) |
| **Planet size**   | Commit count + branch count                                       |
| **Planet color**  | First commit hash                                                 |
| **Moons / rings** | Open PRs + activity recency                                       |
| **Atmosphere**    | Derived trust score                                               |

The full mapping lives in `seedToWorld.ts` in the frontend — it's open source.

***

## Layer 2: the economy

On top of the universe, the contract **GitVersePlanets** (Base mainnet) defines 10,000 tiles. Each tile can be claimed by binding it to a repo name. Once claimed, the tile:

* Marks the planet as **owned** on the RevShare grid.
* Streams a share of all protocol revenue to the owner.
* Can be bought from the owner via Harberger buyout.

### The four flows

```
                ┌──────────────┐
                │   You buy    │  0.01 ETH (0.007 Treasury + 0.003 deposit)
                │    a tile    │
                └──────┬───────┘
                       ↓
       ┌───────────────┴───────────────┐
       │                               │
       ↓                               ↓
   You earn fees              Anyone can buy you out
   (auto-accumulated)         at your declared price + 10% fee
       │                               │
       ↓                               ↓
   Claim Fees                  Previous owner gets:
   (one tx, anytime)           declared price + remaining deposit
                               + holder share of the 10% buyout fee
```

You can also **abandon** the tile (refund your deposit), **add deposit** (extend the time before foreclosure), or **set price** (change your declared price; appreciation tax applies if you raise it).

***

## Where the money flows

Every ETH that enters the contract is split deterministically:

| Source                             | Treasury   | Tile Holders |
| ---------------------------------- | ---------- | ------------ |
| Admission (claim)                  | 100%       | 0%           |
| Buyout fee (10% of price)          | 90% of fee | 10% of fee   |
| Harberger tax (5%/week)            | 50%        | 50%          |
| Appreciation tax (30% of increase) | 60%        | 40%          |
| Token fees in (future)             | 10%        | 90%          |

**Treasury** funds protocol infrastructure (RPC, indexing, frontend, audits). **Tile holders** receive their share automatically — no claim needed for accrual, one tx to withdraw.


---

# Agent Instructions: 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://gitverse.gitbook.io/gitverse-docs/how-it-works.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.