Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions JUDGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ Current Familiar has one playable Phaser edition. The introduction stays first;
| Bell/Reed services, later discovery and companion interaction | `bun scripts/test-passage-browser.ts` | Prepared guest harbors; no human enjoyment claim |
| Recorded 15 transaction signatures/hashes and 58 connected receipts | `make evidence` | Captured dated testnet evidence, verified offline; not a current ledger query |
| TypeScript/Rust spatial transitions agree | `make test` | Shared fixture, solver and replay tests |
| Every listed pet keyless on pinned global code; replayed-court state and one-time Shells for the test player; player and admin keys disclosed | `make judge` | Live public-RPC state of `familiar-game.testnet`, not proof of deployed code (root code differs from the HEAD build); reports key permissions, cannot see custody |
| Doctored courts (historical and current rules), repeat Shell grants and out-of-scope signing are refused | `make break` | HEAD source in the contract unit runtime plus signer unit tests; full Wasm sandbox stays `bun run test:tidebound-sandbox` |
| Actual contract compatibility and original-operation invariants | `bun run build:contracts`, then `bun run test:tidebound-sandbox` | Separate same-layout local-chain test; deployed-byte upgrade mode additionally requires all five frozen original Wasm artifacts |

Only two report JSON files remain:
Expand Down
11 changes: 9 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
.DEFAULT_GOAL := help
.PHONY: help dev test typecheck build check browser evidence
.PHONY: help dev test typecheck build check browser evidence judge break

help:
@printf '%s\n' 'make dev Start the local game' 'make test Run Bun and Rust unit tests' 'make typecheck Check TypeScript' 'make build Type-check and build the browser game' 'make check Run tests and build' 'make browser Check desktop/mobile routes and saved progress' 'make evidence Verify recorded signatures and receipt graphs offline'
@printf '%s\n' 'make dev Start the local game' 'make test Run Bun and Rust unit tests' 'make typecheck Check TypeScript' 'make build Type-check and build the browser game' 'make check Run tests and build' 'make browser Check desktop/mobile routes and saved progress' 'make evidence Verify recorded signatures and receipt graphs offline' 'make judge Read the live testnet game and check its NEAR claims (no keys)' 'make break Show the contract and signer refusing doctored or out-of-scope requests'

dev:
bun run dev
Expand All @@ -24,3 +24,10 @@ browser:

evidence:
bun --no-env-file scripts/verify-game-evidence.ts

judge:
bun --no-env-file scripts/judge.ts

break:
cargo test --manifest-path contracts/Cargo.toml -p familiar-root break_ -- --nocapture
bun test services/relayer/src/auth/sign.test.ts
1 change: 1 addition & 0 deletions PROGRESS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,4 @@ Full earlier progress and acceptance records are preserved in the [archive](docs
| 2026-11-13 | Documentation trimmed; Make shortcuts added | `make check`, `make typecheck`, `make browser`, `make evidence` | Full233 Bun tests/15490 assertions,123 Rust passes, typecheck/build and Chromium/WebKit route/save checks pass. Ten remaining historical JSONs/535460 bytes and full earlier JUDGES/PROGRESS snapshots archived byte-for-byte outside Git. Only gameplay proof and original-deployment guard JSONs remain. Make forwards to Bun/Cargo without deploy/signing recipes. Game, contract, recovery and original-operation implementations unchanged. No push/deployment or history rewrite; prior physical/human validation gaps remain. |
| 2026-11-13 | GitHub source release prepared |235 Bun tests,123 Rust passes, type/build,15 recorded signatures/58 receipts; independent deployment review | Source build emits complete production game plus the same Node24 H1 handler; preview omits account functions. GitHub checks use pinned actions, read-only permissions, Bun/Rust tests, evidence and synthetic production/preview builds. Reachable history:788 blobs/56236965 bytes scanned against10 actual local secret values with zero matches;31 generic scanner findings independently verified public storage keys/block hashes/client ID/storage-key names. User explicitly authorized public repo; private environment/journals and untracked image excluded. Actual native Git trigger/alias checks remain to be recorded after connection. |
| 2026-11-13 | Public repository and native Git connection established | https://github.com/dadadave80/familiar; GitHub branch-protection readback; existing-project Git link | User explicitly chose public visibility. Initial source23a576d uploaded to main; required PR checks, strict up-to-date main and admin enforcement enabled, force pushes/deletion disabled. Existing Vercel project linked to this repository without replacing encrypted environment or current public alias. This documentation PR is the end-to-end trigger check; its production result is not yet claimed here. |
| 2026-11-13 | `make judge` and `make break` added; NEAR claims table in README | `make judge` (live fastnear RPC, `familiar-game.testnet`): 16 PASS, 0 FAIL, all 4 pets from `nft_tokens`. `make break`: 7 Rust refusal/acceptance tests (first_light_v1 and v2) + 5 signer tests pass. Codex hostile review found 5 gaps (undefined-hash false PASS, hard-coded pet sample, v1-only court tests, snapshot-vs-code and custody overclaims); all fixed. Full `make check`: 235 Bun tests, 130 Rust passes, typecheck; `make evidence` 15 signatures offline | Judge confirms every pet has no keys and run global code `CQQ63d8…` = `get_config.pet_code_hash`; `qa-maker-h1` has 2 accepted claims and 12 Shells granted once. Reported, not claimed: player keys are FullAccess (Privy-held), the method limit is the off-chain signer; root/items keep FullAccess admin keys; deployed root code `66HumWXu…` differs from the HEAD build `4xtG2991…` recorded in FAMILIAR-GAMEPLAY.json. `.env` NEAR_ROOT still names the older `familiar-1105-28522e` stack; judge does not read `.env`. Threat model now states replay proves legal steps only, winning inputs are public, and one pet passed between accounts earns each account a commission. `make break` uses the contract unit runtime, not the Wasm sandbox. No deploy, no signing, no push. |
12 changes: 12 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,21 @@ No account is needed for the device preview. Use neighboring-platform taps, WASD
| `make check` | Tests and build |
| `make browser` | Chromium/WebKit route and save checks |
| `make evidence` | Offline recorded signature/receipt checks |
| `make judge` | Live, read-only testnet checks of the claims below; public RPC, no keys |
| `make break` | Contract and signer refusals: doctored court, Shells twice, out-of-scope signing |

Make is a shortcut layer; the underlying `bun run` commands still work. Browser checks require `bunx playwright install chromium webkit`. Full outing checks use `bun scripts/test-expedition-browser.ts --only=390` and `bun scripts/test-passage-browser.ts`. Real-Wasm sandbox checks require `bun run build:contracts`, then `bun run test:tidebound-sandbox` or `bun run test:sandbox`; default Rust tests leave these integrations ignored.

## NEAR in Familiar

Live stack: root `familiar-game.testnet`, items `items.familiar-game.testnet`. `make judge` reads current chain state over public RPC with no keys; `make break` runs the source rules. The deployed root code differs from the HEAD build recorded in `docs/FAMILIAR-GAMEPLAY.json`, so source tests describe HEAD, not necessarily the deployed bytes.

| Claim | What is true on testnet | Check | Limit |
| --- | --- | --- | --- |
| Mochi is a real account | Every pet the root lists (`nft_tokens`) is a sub-account with no access keys, running global code pinned by hash (`get_config.pet_code_hash`); its NFT papers on the root name the owner | `make judge` | Root and Items still have admin keys, so the whole stack is not immutable |
| The court is refereed | In source, `tidebound_claim` replays the submitted steps and accepts only a court that brings Mochi home, and 12 Shells are granted once per account; on chain, the test player's accepted claims and Shells match that | `make break` (rule), `make judge` (state) | Replay proves the steps are legal, not that a person played them; one pet passed between accounts can earn each its own Shells |
| Your key | Your account key is held by your Privy wallet; Familiar's signer prepares only named harbor actions | `make judge` lists the key's permission; custody and the method limit come from source (`privy-adapter.ts`, `sign.ts`), checked by `make break` | The key is full-access; the method limit is enforced by the signer, not by the chain |

## Source

- `web/src/expedition/`: rules, Phaser presentation, Mochi, sound and harbor.
Expand Down
83 changes: 83 additions & 0 deletions contracts/root/src/tidebound.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1213,6 +1213,89 @@ mod tests {
);
}
#[test]
#[should_panic(expected = "ERR_RETURN_REQUIRED")]
fn break_a_court_that_never_brings_mochi_home_is_refused() {
let mut c = contract();
let mut doctored = dry();
doctored.pop();
claim(
&mut c,
"alice.testnet",
"mochi.root.testnet",
"first",
doctored,
);
}
#[test]
#[should_panic(expected = "ERR_REPLAY")]
fn break_an_illegal_step_is_refused_by_replay() {
let mut c = contract();
let mut doctored = dry();
doctored.insert(0, "move:teleport".into());
claim(
&mut c,
"alice.testnet",
"mochi.root.testnet",
"first",
doctored,
);
}
#[test]
#[should_panic(expected = "ERR_RETURN_REQUIRED")]
fn break_a_current_court_that_never_brings_mochi_home_is_refused() {
let mut c = contract();
let mut doctored = spatial_lens();
doctored.pop();
claim_court(
&mut c,
"alice.testnet",
"mochi.root.testnet",
"first",
doctored,
);
}
#[test]
#[should_panic(expected = "ERR_REPLAY")]
fn break_an_illegal_step_in_the_current_court_is_refused() {
let mut c = contract();
let mut doctored = spatial_lens();
doctored.insert(0, "step:teleport".into());
claim_court(
&mut c,
"alice.testnet",
"mochi.root.testnet",
"first",
doctored,
);
}
#[test]
fn break_the_current_court_accepts_the_honest_route() {
let mut c = contract();
let j = claim_court(
&mut c,
"alice.testnet",
"mochi.root.testnet",
"first",
spatial_lens(),
);
assert_eq!(j.claims.len(), 1);
}
#[test]
#[should_panic(expected = "ERR_COMMISSION_UNAVAILABLE")]
fn break_shells_without_an_accepted_court_are_refused() {
let mut c = contract();
ctx("alice.testnet");
c.tidebound_commission();
}
#[test]
fn break_shells_are_granted_once_however_often_asked() {
let mut c = ready();
ctx("alice.testnet");
assert_eq!(c.tidebound_commission().shells, 12);
let again = c.tidebound_commission();
assert_eq!((again.shells, again.commission_fulfilled), (12, true));
}
#[test]
#[should_panic(expected = "ERR_NOT_OWNER")]
fn relay_signer_cannot_claim_for_current_pet_holder() {
let mut c = contract();
Expand Down
2 changes: 1 addition & 1 deletion docs/THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Current source scope, November 13, 2026: browser game and supporting NEAR testne
| Account provider | App-scoped Privy identity and exact canonical user-owned NEAR wallet; separately configured NEAR Auth provider | Email/provider administration, session availability and SDK integrity remain dependencies |
| Account HTTP | Three exact H1 endpoints, origin/JWT/body/size/method checks, bounded setup | Process-local quotas are not durable anti-Sybil or cross-instance spending controls |
| Native transaction client | Exact canonical Borsh/signature/intent checks, durable original envelope, Web Locks, complete receipt graph | RPC outages or ambiguous consumed nonces may keep an action pending |
| Root registry/journey | Predecessor authorization, current companion ownership, checkpoint replay, accepted original input hashes | Administrative upgrade keys remain; source tests do not freeze deployed code |
| Root registry/journey | Predecessor authorization, current companion ownership, checkpoint replay, accepted original input hashes | Administrative upgrade keys remain; source tests do not freeze deployed code. Court replay proves legal steps, not human play, and winning inputs are public; the commission is per account, so one pet passed between accounts can earn each account its own 12 Shells |
| Items | Current-holder checks, authenticated immutable mint evidence, one finish per token | Transferred ownership is distinct from maker achievement; stale UI alone is never ownership proof |
| Keyless Pet | Registry-only execution, fixed buildings/pool, pinned global code and no access keys | General recovery for unforeseen historical callback failure is not available |

Expand Down
75 changes: 75 additions & 0 deletions scripts/judge.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
// `make judge`: read-only checks of Familiar's NEAR claims against live testnet.
// No keys, no signing, no .env. Every line it prints comes from a public RPC response.
const RPC = process.env.JUDGE_RPC ?? "https://test.rpc.fastnear.com";
const ROOT = process.env.JUDGE_ROOT ?? "familiar-game.testnet";
const ITEMS = `items.${ROOT}`;
const PLAYER = `qa-maker-h1.${ROOT}`;

type Key = { public_key: string; access_key: { permission: "FullAccess" | { FunctionCall: { receiver_id: string; method_names: string[] } } } };

async function rpc(params: Record<string, unknown>) {
const res = await fetch(RPC, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: "judge", method: "query", params: { finality: "final", ...params } }) });
const body = await res.json() as { result?: any; error?: { message?: string; data?: unknown } };
if (body.error || body.result?.error) throw new Error(`${params.request_type} ${params.account_id}: ${JSON.stringify(body.error ?? body.result.error)}`);
return body.result;
}
const account = (account_id: string) => rpc({ request_type: "view_account", account_id });
const keys = async (account_id: string) => (await rpc({ request_type: "view_access_key_list", account_id })).keys as Key[];
async function view(account_id: string, method_name: string, args: object = {}) {
const r = await rpc({ request_type: "call_function", account_id, method_name, args_base64: Buffer.from(JSON.stringify(args)).toString("base64") });
return JSON.parse(Buffer.from(r.result).toString());
}
const perm = (k: Key) => k.access_key.permission === "FullAccess" ? "FullAccess" : `FunctionCall ${k.access_key.permission.FunctionCall.receiver_id} [${k.access_key.permission.FunctionCall.method_names.join(", ") || "any method"}]`;

let failed = 0;
const check = (ok: boolean, line: string) => { if (!ok) failed++; console.log(`${ok ? "PASS" : "FAIL"} ${line}`); };
const note = (line: string) => console.log(`NOTE ${line}`);

console.log(`Familiar judge — ${ROOT} via ${RPC}\n`);

console.log("SELF Mochi has no access keys and runs code pinned by hash");
const config = await view(ROOT, "get_config");
const pinned = config.pet_code_hash;
check(typeof pinned === "string" && /^[1-9A-HJ-NP-Za-km-z]{43,44}$/.test(pinned), `${ROOT} get_config.pet_code_hash = ${pinned}`);
const supply = Number(await view(ROOT, "nft_total_supply"));
const pets: string[] = [];
for (let i = 0; i < supply; i += 50) pets.push(...(await view(ROOT, "nft_tokens", { from_index: String(i), limit: 50 })).map((t: { token_id: string }) => t.token_id));
check(supply > 0 && pets.length === supply, `${ROOT} has ${supply} pets; checking every one`);
for (const pet of pets) {
const [a, k, token] = await Promise.all([account(pet), keys(pet), view(ROOT, "nft_token", { token_id: pet })]);
check(k.length === 0, `${pet} has ${k.length} access keys`);
check(typeof pinned === "string" && a.global_contract_hash === pinned && a.code_hash === "11111111111111111111111111111111", `${pet} runs global code ${a.global_contract_hash} (no local code)`);
check(token?.owner_id !== undefined, `${pet} papers on ${ROOT}: owned by ${token?.owner_id}`);
}

console.log("\nREFEREE Ledger state left by replayed courts (the replay rule itself is source, checked by make break)");
const protocol = await view(ROOT, "tidebound_protocol");
note(`rules ${protocol.rules_version}, content ${protocol.content_version}, items ${protocol.items}`);
const journey = await view(ROOT, "tidebound_journey", { account_id: PLAYER });
check(journey.claims.length > 0, `${PLAYER} has ${journey.claims.length} accepted claims: ${journey.claims.map((c: { id: string }) => c.id).join(", ")}`);
check(journey.commission_fulfilled && journey.shells + journey.burned_shells === 12, `${PLAYER} was granted 12 Shells once (${journey.shells} held, ${journey.burned_shells} spent)`);
note("This is a snapshot of state, not proof of the deployed code: deployed root code is reported below and does not match the HEAD build recorded in docs/FAMILIAR-GAMEPLAY.json.");
note("Replay proves the steps are legal and bring Mochi home, not that a person played them; see docs/THREAT-MODEL.md.");

console.log("\nKEY What the player's key can do (reported, not claimed)");
for (const k of await keys(PLAYER)) note(`${PLAYER} ${k.public_key.slice(0, 16)}… ${perm(k)}`);
note("Who holds the key (Privy) is not visible on chain; it comes from the source (web/src/account/privy-adapter.ts). The method limit is in Familiar's signer (services/relayer/src/auth/sign.ts), not on chain.");

console.log("\nSEASON Season 2 shelf runs the reviewed code (state only; no trade claimed)");
const SEASON = `season.${ROOT}`;
const SEASON_CODE = process.env.JUDGE_SEASON_CODE ?? "3FbynwMm2uWs8bahXSCoqDdrKsEJ1on6rR1C277hXNzy";
const seasonAccount = await account(SEASON);
check(seasonAccount.code_hash === SEASON_CODE, `${SEASON} runs ${seasonAccount.code_hash} (built by scripts/build-contracts.sh on feat/season-two)`);
const shelf = await view(SEASON, "get_shelf");
note(`Bram's till ${shelf.till} Shells; ${shelf.goods.map((g: { good: string; stock: number; buy_price: number }) => `${g.good} ${g.stock} @ ${g.buy_price}`).join(", ")}`);

console.log("\nADMIN Keys that still control the stack (disclosed)");
for (const id of [ROOT, ITEMS, `season.${ROOT}`]) {
const [a, k] = await Promise.all([account(id), keys(id)]);
note(`${id} code ${a.code_hash}; keys: ${k.map(x => `${x.public_key.slice(0, 16)}… ${perm(x)}`).join("; ")}`);
}

console.log(`\n${failed ? `${failed} check(s) failed` : "All checks passed"}.`);
process.exit(failed ? 1 : 0);

export {};