Hyphae
Hyphae is a proof-of-contribution layer for token communities. Members do real work for a community, an AI scores it against public guidelines and shows its reasoning, and each epoch's payouts are committed to Solana as a merkle root, next to the hash of the epoch's full audit record. Each community has a SOL vault; a contributor claims their share from it with a merkle proof, signed by their own wallet, once.
Built solo for Colosseum's Crypto World's Fair (2026-09-14 → 2026-10-12), under the Organic/MYCEL umbrella. The build log is docs/BUILDLOG.md.
Quick tour
Live demo · Paid epoch 2 · Mainnet receipts · Development milestones · Public rules
Start with the paid epoch: inspect a contribution's score and reasoning, its allocation, and its confirmed claim. The wallet record connects the signed identity to its payment history. The homepage setup prompt helps another community prepare an operator-assisted setup.
Telegram member path
Use the official bot from your community's registered group. Ask its owner for the verified group invite.
| Step | Command or button | Result |
|---|
| 1. Set up | /setup in the group | Open your guided checklist privately; /link verifies your wallet with a readable message. |
| 2. Learn the rules | /rules in the group | Open this community's rules quiz privately; /help explains scores and payment conditions. |
| 3. Find work | /help brief | Read the current raid brief and its audit link. |
| 4. Submit | The exact raid's Submit button | Send your own reply/quote URL privately; retain its receipt to inspect the result. |
| 5. Check progress | /me → Open my private checklist | See your wallet and eligibility privately. Published allocations and confirmed claims are on the audit site. |
Optional alerts use /notifications; privately refresh a result with /receipt <receipt ID> or report a scoring issue with /issue <receipt ID> <reason>. Points do not promise payment.
Public rules and version history
Epoch 2 used MYCEL 1.2.0. The rubric and scorer changelog, whitepaper, and each epoch's public audit expose the applicable rules and amendments. Published rubric files retain prior versions. MYCEL 1.3.0 is a candidate, not the live epoch-2 rule set. Rules are public; individual rules-test and hold checklists are private.
Status
October 10, 2026: epoch 2 paid on Solana mainnet. All four payees claimed 1,238,881,509 lamports, with 0 unclaimed; three of the four payees are non-founder community members. Finalized payout and claim receipts.
Set up a community
Each token community uses its own registered Telegram group and /c/<mint> audit page. The shared bot provides community-specific welcome/help, rules, submissions and progress. Adding the bot alone does not register a group.
The operator setup guide describes the local community-setup tool: offline plan, read-only checks, then an explicitly approved registration that starts paused with a pinned epoch and no payment eligibility. Current setup is operator-assisted; an Organic owner-authorized integration and a self-service administrator interface are not built. No new production community or Telegram setting is changed by publishing this code.
Read API
Public, read-only, unauthenticated JSON at https://hyphae-api.fly.dev/v1. The reference is at /docs, which renders the OpenAPI 3.1 document at /v1/openapi.json. The document is generated from the same schemas the API's tests check its responses with. To run it locally, see Develop.
For the locally packed standalone TypeScript read SDK, a runnable reader and community/launchpad adoption boundaries, see the integration guide. Package installation is verified in a separate Node/browser consumer; npm publication and self-service setup remain separate.
- A section the API cannot confirm is
{ "status": "unavailable", "reason": … }, never a zero.
- Settlement and payments are read against Solana. A transaction is shown only when the chain proves it created the account it names.
- Every response carries
RateLimit-* headers. Past 300 requests a minute from one address, the API answers 429 with Retry-After.
Integrate in 10 lines
A wallet's leaves in every community, newest first, each with its proof and its payment status (paid with the claim transaction, claimable, or unavailable with a reason). This reads the first 100; total_claims counts them all, and offset pages on. A wallet with no leaf in a published epoch gets total_claims: 0 and an empty claims, not a 404.
const API = process.env.HYPHAE_API ?? "https://hyphae-api.fly.dev/v1";
const wallet = process.argv[2];
const { claims } = await (await fetch(`${API}/wallets/${wallet}/claims?limit=100`)).json();
Check each proof yourself: rebuild the 89-byte leaf, then hash up the sorted pairs to the root. It is the same computation the program runs before it pays.
import { createHash } from "node:crypto";
import { getAddressEncoder } from "@solana/kit";
const sha = (...parts) => createHash("sha256").update(Buffer.concat(parts)).digest();
const u64 = (v) => { const b = Buffer.alloc(8); b.writeBigUInt64LE(BigInt(v)); return b; };
for (const c of claims) {
let node = sha(Buffer.of(0), Buffer.from(getAddressEncoder().encode(wallet)), u64(c.epoch.index),
u64(c.score), u64(c.amount_lamports), Buffer.from(c.evidence_hash, "hex"));
for (const p of c.proof.map((h) => Buffer.from(h, "hex")))
node = sha(Buffer.of(1), ...(Buffer.compare(node, p) <= 0 ? [node, p] : [p, node]));
console.log(c.community.mint, c.epoch.index, c.amount_lamports, c.payment.status, node.toString("hex") === c.root);
}
root is the root of the epoch account at epoch_address. Read that account to check it without trusting the API. To claim, read /v1/communities/{mint}/epochs/{index}/claims/{wallet} right before signing: it adds a recent blockhash.
Funding a community's vault (for Organic and other integrators)
A community is the pair (token mint, the admin key that publishes its epochs). Its vault is a program-derived address, so an integrator derives it without calling Hyphae, and funds it with an ordinary SOL transfer:
import { address, getAddressEncoder, getProgramDerivedAddress } from "@solana/kit";
const HYPHAE = address("EAz8WkyUbGqr3ewSLpk94GWEoiWsvMENE5zV7Tvh4d6E");
const enc = getAddressEncoder();
const [community] = await getProgramDerivedAddress({ programAddress: HYPHAE, seeds: ["community", enc.encode(mint), enc.encode(admin)] });
const [vault] = await getProgramDerivedAddress({ programAddress: HYPHAE, seeds: ["vault", enc.encode(community)] });
- The vault's seeds are
["vault", community], where community is the program-derived address of ["community", mint, admin]. The admin is a seed, so a community is the pair, not the mint alone.
- SOL leaves the vault only through the program: each published epoch sends the 3% Hyphae fee to the recipient fixed when the community was created, and each claim pays one leaf of a published root, once. Who is trusted with what is under Custody during the pilot.
- An epoch can only allocate SOL that no earlier epoch has allocated and nobody has claimed yet.
- The program is on mainnet and on devnet at the same address, so a vault's address is the same on both, and it exists only on a network where its community was created. Check that the community exists on the network you use before sending anything.
Organic's bagworker sweep can target this address. Nothing in this repository changes Organic's code.
Custody during the pilot
Pilot policy. Hyphae's publisher key sets each epoch's payout list, so you trust it with that epoch's pot. We keep that key on a hardware wallet and fund one epoch at a time, just before it pays. The program has no withdraw instruction: SOL leaves the vault only through member claims and the 3% fee. The program can still be upgraded. The upgrade key is held the same way, and any upgrade is announced here before it is used.
Develop
Requires pnpm 10 and Node 22. The Solana program builds in WSL or Linux with Anchor 1.0.1 and Solana CLI 3.1.
pnpm install
pnpm test && pnpm typecheck && pnpm lint
pnpm --filter @hyphae/api test:pg # Postgres 17 in Docker
anchor build && cargo test -p hyphae --tests
python3 tests/h_contract_vectors.py # the commitment vectors, with Python's standard library
CI runs the same checks on every push. The program builds weekly.
To run the read API locally on a disposable database with the demo community:
docker run -d --rm --name hyphae-pg -p 55433:5432 -e POSTGRES_PASSWORD=local -e POSTGRES_DB=hyphae postgres:17
export DATABASE_URL=postgres://postgres:[email protected]:55433/hyphae
pnpm --filter @hyphae/db exec drizzle-kit migrate
cd apps/api && node --import tsx src/http/demo-seed.ts && pnpm build
# The bot and scoring variables must be set but are not used by the read API.
TELEGRAM_BOT_TOKEN=000000000:local-placeholder-token TELEGRAM_WEBHOOK_SECRET=local-placeholder \
ANTHROPIC_API_KEY=unused LINK_ORIGIN=https://localhost PORT=8787 \
READ_RPC_URL=https://api.devnet.solana.com node dist/server.js
Then open http://localhost:8787/docs. publish.devnet.test.ts can add a real devnet publication to the same database (HYPHAE_DEVNET_DATABASE_URL).
License
Business Source License 1.1, converting to the GPL v2.0 or later on 2028-10-12. This repository is public; the program, its verifiable build and the rubrics are also published at FCisco95/hyphae-program under the same licence.
