# Bloodstone Ecosystem Merge-Mining

**Status:** Policy + registry + operator toggles live (July 2026)  
**Doc version:** v1.1  
**Scope:** Fork Lab ecosystem · SHA256d / AuxPoW lane · pool/parent config  

---

## Rules (product lock — immutable)

### Core rule

> **Forks MUST merge-mine STONE once created and mining.**  
> **Forks may not turn off STONE merge-mine.**  
> **Bloodstone controls may turn a fork off as a *child* target only** (parent-side checkbox). That does **not** authorize the fork to stop merge-mining STONE.

| Actor | STONE (Bloodstone) parent | Sister forks | Child forks on Bloodstone |
|-------|---------------------------|--------------|---------------------------|
| **Fork chain operators** | **Mandatory + locked** (cannot disable) | **Optional**, each selectable | n/a |
| **Bloodstone operators** | Always mine self | n/a | **Optional**, each child selectable (default **off**) — may disable |

- Every Fork Lab coin includes a **SHA256d** lane so STONE parent merge-mine is always available (**true AuxPoW**).  
- CPU lanes (**NeoScrypt-Xaya**, **Yespower R16**) **dual-job** Bloodstone: parallel `creatework` on the fork **and** STONE for the same algo (headers are chain-specific — **not** AuxPoW).  
- Ecosystem parent merge toggles for **children** (Bloodstone → optional fork AuxPoW) still apply to the **SHA256d** path.  
- Bloodstone’s existing AuxPoW link to **SpaceXpanse ROD** (chain ID **1899**) is unchanged.

Manifest fields (enforced):

```json
"parent": {
  "required": true,
  "selectable": false,
  "enabled": true,
  "locked": true,
  "fork_may_disable": false
}
```

---

## Why this shape

1. **Forks buy parent security** — every ecosystem fork’s merge-mined work must bind to Bloodstone (STONE).  
2. **Forks cannot defect** — no fork-side toggle to drop STONE merge-mine after create/mining.  
3. **Bloodstone stays sovereign** — parent operators opt into each child; nothing is forced onto Bloodstone templates.  
4. **Sisters are optional** — cross-fork merge-mine is a checkbox, not a default mesh of everything.

---

## Operator surfaces

### APIs (portal)

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/ecosystem-merge-mine` | Full policy + enabled children |
| GET | `/api/ecosystem-merge-mine/bloodstone-children` | Available live forks + enabled flags |
| POST | `/api/ecosystem-merge-mine/bloodstone-children` | Set Bloodstone child enables |
| POST | `/api/ecosystem-merge-mine/fork-sisters` | Set optional sisters for a fork |

**POST auth:** `admin_token` body field / `X-Bloodstone-Admin-Token` header matching  
`ECOSYSTEM_MERGE_MINE_ADMIN_TOKEN` or `FORK_LAB_ADMIN_TOKEN`, **or** loopback.  
Fork sister updates also accept that fork’s `manage_token` + `fork_id`.

**Example — enable two children on Bloodstone:**

```bash
curl -sS -X POST https://bloodstone.rocks/api/ecosystem-merge-mine/bloodstone-children \
  -H 'Content-Type: application/json' \
  -d '{"admin_token":"…","enabled":["TICKERA","TICKERB"],"replace":true}'
```

### Config file

`/var/lib/bloodstone/ecosystem_merge_mine.json`  
(override path with `ECOSYSTEM_MERGE_MINE_CONFIG`)

### Fork Lab

- Every fork **manifest** includes `merge_mine` (parent mandatory, sisters optional, child-of-Bloodstone hint).  
- Create payload may include `merge_mine_sisters` / `sister_forks`.  
- Store / coin APIs expose `merge_mine` on each live fork.  
- UI: Fork Lab page section **Ecosystem merge-mining**.

### Mining dashboard

Admin panel lists live children with enable checkboxes (session admin).

---

## Implementation phases

| Phase | Status |
|-------|--------|
| Policy module + config file | **Done** |
| Fork Lab registry / manifest / APIs | **Done** |
| Portal + mining UI toggles | **Done** |
| **Additive economy formula** (mesh bps in fork ticker; STONE resource floor) | **Done** — see [Bloodstone-Ecosystem-Fork-Economy.md](./Bloodstone-Ecosystem-Fork-Economy.md) |
| Multi-aux stratum job wiring (templates carry N children) | **Next** |
| Payout accounting: mesh bps + per child aux share | **Next** |

---

## Related

- Fork Lab: `/fork-lab/`  
- API: `/api/ecosystem-merge-mine`  
- ROD AuxPoW labels: `merge_mining_info.py` (chain 1899)