Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

12.5 KB
Raw Blame
/**
 * Grind-to-earn pool protocol — `three-grind-pool/v1`.
 *
 * The pure, isomorphic rules of the decentralized grinding pool: how the offset
 * keyspace is sharded across workers, how a worker proves real contributed work
 * (proof-of-contribution shares), and how a bounty's escrow is split fairly among
 * the winner and every honest contributor. The server (claim/settlement handler),
 * the Colyseus coordination room, the browser/agent workers, and the tests all
 * import this one module so there is a single verified implementation of every
 * economic and anti-cheat rule.
 *
 * ── Sharding (no duplicated effort, resumable) ────────────────────────────────
 * For split-key grinding the keyspace is the space of offset scalars a2. A worker
 * is handed a distinct base offset derived deterministically from
 * (bountyId, workerId, shardIndex); it then walks a2, a2+1, a2+2, … by single
 * point additions. Two random 256-bit base offsets cannot collide within any
 * feasible attempt budget, so workers never grind the same region. Determinism
 * lets the room reassign a shard after a disconnect and lets a worker resume
 * exactly where a fresh shard begins.
 *
 * ── Proof-of-contribution shares (anti-freeloader, anti-sybil) ────────────────
 * You cannot trust a worker's self-reported attempt count. Like a mining pool, a
 * worker proves work by submitting *shares*: offsets whose derived address clears
 * an easy target — `leadingZeroBits(sha256(address)) >= shareBits`. Each share is
 * a verifiable proof that the worker evaluated ~2^shareBits candidates *against
 * this bounty's P1* (a share is bound to P1, so it can't be precomputed or reused
 * on another bounty). The server verifies a share with one secret-free point check
 * plus a hash, then credits the worker proportionally. Splitting into many sybil
 * identities yields the same total shares as one identity — payout tracks real
 * work, not identity count — so sybils gain nothing.
 *
 * ── Fair, conservative payout split ───────────────────────────────────────────
 * On a verified win the escrow is divided: a transparent platform fee, a winner
 * bonus to the finder (who did the decisive work and bore the submit), and the
 * remainder distributed pro-rata across ALL share-holders. Refund-on-expiry returns
 * the full escrow to the requester (the platform fee is only ever taken on success).
 * All arithmetic is integer atomics and provably conserves the escrow to the last
 * unit (rounding dust is assigned to the winner), pinned by tests.
 *
 * Pure + isomorphic: @noble hashing + the split-key primitives only.
 */

import { sha256 } from '@noble/hashes/sha256.js';
import { hmac } from '@noble/hashes/hmac.js';
import { bytesToHex, utf8ToBytes, concatBytes } from '@noble/hashes/utils.js';
import bs58 from 'bs58';

import { scalarToBytes, bytesToScalar, verifySplitKeyClaim } from './split-key.js';
import { expectedAttempts } from './validation.js';

export const POOL_PROTOCOL = 'three-grind-pool/v1';

// USDC / $THREE atomic units (both 6 decimals on the platform).
export const ATOMICS = 1_000_000;

/**
 * Economic constants — published, bounded, and shown in the UI so the market is
 * transparent. The fee funds the platform + payout gas; the winner bonus rewards
 * the decisive find; the rest flows to contributors by share.
 */
export const ECONOMICS = Object.freeze({
	platformFeeBps: 500, //  5.0% platform fee, taken on success only
	winnerBonusBps: 6000, // 60% of the post-fee pool to the finder
	minShareBits: 8, //      a share is never easier than 1-in-256
	maxShareBits: 24, //     nor harder than 1-in-16.7M (keeps share cadence sane)
	// Target number of shares a full expected grind should yield, used to pick the
	// per-bounty share difficulty so contribution accounting has useful resolution
	// without flooding the server with share submissions.
	targetSharesPerGrind: 256,
	feeBps: 500,
});

const TAG_SHARD = utf8ToBytes('three-grind-pool/shard/v1');

// ── share difficulty ──────────────────────────────────────────────────────────

/**
 * Choose the share difficulty (in leading-zero bits of sha256(address)) for a
 * bounty, so a full expected grind yields ~targetSharesPerGrind shares — enough
 * resolution to apportion fairly, few enough to not flood the network. Clamped to
 * [minShareBits, maxShareBits].
 * @param {{prefix?:string,suffix?:string,ignoreCase?:boolean}} pattern
 * @returns {number} shareBits
 */
export function shareDifficultyBits(pattern) {
	const attempts = Math.max(1, expectedAttempts(pattern?.prefix || '', pattern?.suffix || '', !!pattern?.ignoreCase));
	// shares ≈ attempts / 2^bits ⇒ bits = log2(attempts / targetShares)
	const raw = Math.floor(Math.log2(attempts / ECONOMICS.targetSharesPerGrind));
	return Math.max(ECONOMICS.minShareBits, Math.min(ECONOMICS.maxShareBits, Number.isFinite(raw) ? raw : ECONOMICS.minShareBits));
}

/** Count leading zero bits of a byte array. */
export function leadingZeroBits(bytes) {
	let bits = 0;
	for (let i = 0; i < bytes.length; i++) {
		const b = bytes[i];
		if (b === 0) {
			bits += 8;
			continue;
		}
		bits += Math.clz32(b) - 24; // clz32 of a byte counts from a 32-bit word
		break;
	}
	return bits;
}

/** Does an address clear the share target? (sha256(address) has ≥ shareBits leading zeros) */
export function meetsShareTarget(address, shareBits) {
	const h = sha256(utf8ToBytes(String(address || '')));
	return leadingZeroBits(h) >= shareBits;
}

/**
 * Verify a submitted share with NO secret: the offset must derive the claimed
 * address from P1 (anti-cheat, same point check as a win) and the address must
 * clear the share target. A valid share proves ~2^shareBits real attempts on this
 * bounty's P1.
 * @param {object} p
 * @param {string} p.p1
 * @param {Uint8Array|string} p.offset
 * @param {string} p.address
 * @param {number} p.shareBits
 * @returns {{ ok:boolean, reason:string }}
 */
export function verifyShare({ p1, offset, address, shareBits }) {
	const d = verifySplitKeyClaim({ p1, offset, address });
	if (!d.derivationOk) return { ok: false, reason: d.reason || 'offset does not derive the claimed address' };
	if (!meetsShareTarget(address, shareBits)) return { ok: false, reason: `address does not clear the share target (${shareBits} bits)` };
	return { ok: true, reason: '' };
}

/** Weight (expected attempts) one share represents at a given difficulty. */
export function shareWeight(shareBits) {
	return Math.pow(2, shareBits);
}

// ── sharding ────────────────────────────────────────────────────────────────

/**
 * Deterministic, collision-free base offset scalar for a worker's shard. Derived
 * via HMAC-SHA256 keyed on the bounty id so shards differ across bounties; the
 * worker increments from here. Returns LE 32-byte scalar hex (the `startOffset`
 * grindSplitKeyOffset accepts).
 * @param {string} bountyId
 * @param {string} workerId
 * @param {number} shardIndex
 * @returns {string} hex offset scalar
 */
export function deriveShardOffset(bountyId, workerId, shardIndex = 0) {
	const msg = concatBytes(
		TAG_SHARD,
		utf8ToBytes(`${bountyId}|${workerId}|${shardIndex >>> 0}`),
	);
	const digest = hmac(sha256, utf8ToBytes(String(bountyId || 'pool')), msg);
	// Reduce into a scalar; the LE bytes are the worker's base offset.
	return bytesToHex(scalarToBytes(bytesToScalar(digest)));
}

// ── payout math ────────────────────────────────────────────────────────────

function toBig(n) {
	if (typeof n === 'bigint') return n;
	return BigInt(String(n).split('.')[0] || '0');
}

/**
 * Split a bounty's escrow on a verified win. Conserves the escrow exactly:
 *   reward = fee + winnerBonus + Σ contributor distributions   (+ dust → winner)
 *
 * @param {object} p
 * @param {bigint|number|string} p.rewardAtomics  total escrowed reward
 * @param {string} p.winnerId                     worker id credited with the find
 * @param {Array<{workerId:string, shares:number|bigint}>} [p.contributions]  validated shares per worker
 * @param {number} [p.feeBps=ECONOMICS.platformFeeBps]
 * @param {number} [p.winnerBonusBps=ECONOMICS.winnerBonusBps]
 * @returns {{ feeAtomics:bigint, winnerId:string, winnerAtomics:bigint,
 *   distributions:Array<{workerId:string, atomics:bigint, shares:bigint}>, totalPaid:bigint }}
 */
export function computePayouts({
	rewardAtomics,
	winnerId,
	contributions = [],
	feeBps = ECONOMICS.platformFeeBps,
	winnerBonusBps = ECONOMICS.winnerBonusBps,
}) {
	const reward = toBig(rewardAtomics);
	if (reward <= 0n) throw new Error('computePayouts: rewardAtomics must be > 0');
	if (!winnerId) throw new Error('computePayouts: winnerId required');

	const fee = (reward * BigInt(feeBps)) / 10_000n;
	const net = reward - fee;
	const winnerBonus = (net * BigInt(winnerBonusBps)) / 10_000n;
	const sharePool = net - winnerBonus;

	// Aggregate shares per worker (a worker may appear once; sum defensively).
	const byWorker = new Map();
	let totalShares = 0n;
	for (const c of contributions) {
		const s = toBig(c.shares);
		if (s <= 0n) continue;
		byWorker.set(c.workerId, (byWorker.get(c.workerId) || 0n) + s);
		totalShares += s;
	}

	const distributions = [];
	let distributed = 0n;
	if (totalShares > 0n && sharePool > 0n) {
		for (const [workerId, shares] of byWorker) {
			const atomics = (sharePool * shares) / totalShares; // floor
			if (atomics > 0n) {
				distributions.push({ workerId, atomics, shares });
				distributed += atomics;
			} else {
				distributions.push({ workerId, atomics: 0n, shares });
			}
		}
	}

	// Winner gets the bonus + any undistributed remainder (dust + the whole pool
	// when there were no shares at all). This conserves the escrow to the last unit.
	const winnerAtomics = winnerBonus + (sharePool - distributed);
	const totalPaid = fee + winnerAtomics + distributed;
	if (totalPaid !== reward) {
		throw new Error(`computePayouts: conservation violated (${totalPaid} ≠ ${reward})`);
	}
	return { feeAtomics: fee, winnerId, winnerAtomics, distributions, totalPaid };
}

/**
 * Honest difficulty → suggested reward, anchored to expected compute. Returns USDC
 * atomic units. Mirrors the bounty-protocol oracle's intent but lives here so the
 * pool board, post form, and worker estimates share one source.
 * @param {{prefix?:string,suffix?:string,ignoreCase?:boolean}} pattern
 * @returns {{ expectedAttempts:number, floorAtomics:number, suggestedAtomics:number, generousAtomics:number, expectedGrindSeconds:number }}
 */
export function suggestRewardAtomics(pattern) {
	const attempts = expectedAttempts(pattern?.prefix || '', pattern?.suffix || '', !!pattern?.ignoreCase);
	const refRatePerSec = 1_500_000; // reference fleet throughput (intuition only)
	const usdcPerGrindHour = 1 * ATOMICS;
	const floorAtomics = 50_000; // $0.05
	const maxAtomics = 5_000 * ATOMICS;
	const grindSeconds = attempts / refRatePerSec;
	const fair = (grindSeconds / 3600) * usdcPerGrindHour;
	const suggested = Math.max(floorAtomics, Math.min(maxAtomics, Math.round(fair)));
	return {
		expectedAttempts: Math.round(attempts),
		floorAtomics,
		suggestedAtomics: suggested,
		generousAtomics: Math.min(maxAtomics, Math.round(suggested * 2.5)),
		expectedGrindSeconds: Math.round(grindSeconds),
	};
}

/** Validate a reward amount is in the legal band; throws 400-tagged otherwise. */
export function validateRewardAtomics(atomics) {
	const v = Math.round(Number(atomics));
	const floor = 50_000;
	const max = 5_000 * ATOMICS;
	if (!Number.isFinite(v) || v < floor) {
		throw Object.assign(new Error(`reward must be at least ${floor} atomic units ($${(floor / ATOMICS).toFixed(2)})`), { status: 400, code: 'amount_too_low' });
	}
	if (v > max) {
		throw Object.assign(new Error(`reward exceeds the ${max}-atomic ceiling`), { status: 400, code: 'amount_too_high' });
	}
	return v;
}

/** Base58 sanity for an address (used at API boundaries). */
export function isBase58Address(s) {
	return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(String(s || ''));
}

/** Stable hex id for a contribution share (idempotency anchor). */
export function shareId({ bountyId, address }) {
	return bytesToHex(sha256(utf8ToBytes(`${bountyId}|${address}`))).slice(0, 32);
}

export { bs58 };