diff --git a/README.md b/README.md index 146283a..2e3820e 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,107 @@ -# PonziLand Guilds Specifications (v0.1) +# +# ____ _ _ _ _ +# / ___|_ _(_) | __| |___| |__ +#| | _| | | | | |/ _` / __| '_ \ +#| |_| | |_| | | | (_| \__ \ | | | +# \____|\__,_|_|_|\__,_|___/_| |_| +# -Welcome to the **PonziLand Guilds** module—designed to introduce social, political, and economic dynamics through onchain guilds. +# Guilds ---- +Guilds is a contract-first Starknet system for on-chain guild governance, treasury operations, and dual revenue distribution (members + shareholders). -## 🔗 Quick Links +## Architecture -- **Website:** https://www.ponzi.land -- **Runelabs:** https://www.runelabs.xyz -- **Discord:** https://discord.gg/ponziland -- **Twitter (PonziDotLand):** https://x.com/ponzidotland -- **Twitter (RuneLabsxyz):** https://x.com/runelabsxyz +- `src/guild/guild_contract.cairo`: guild core state machine (membership, roles, treasury, revenue, shares) +- `src/token/guild_token.cairo`: ERC20Votes-style guild token with inactivity handling +- `src/governor/guild_governor.cairo`: governance control plane +- `src/models/*`: canonical structs, constants, and events +- `tests/*.cairo`: unit + integration-style coverage by domain +- `sdk/`: typed TypeScript SDK with compatibility gate and smoke tests ---- +## Quickstart -## 🎯 Objectives +### Contracts -1. **Facilitate social community formation** inside the game -2. **Introduce competitive and political narratives** via guild dynamics -3. **Enable economic access and mobility** for smaller or new players -4. **Support team-based esports** with in‑game guild competitions +```bash +# Option A: use your existing local Scarb/Snforge install +scarb fmt --check --workspace +snforge test -*Guilds function as a DAO, an investment fund, and an esports team.* +# Option B: project verify fallback +bash -lc 'sozo test || scarb test' +``` ---- +### SDK -## 🛠️ Basic Features +```bash +cd sdk +npm install +npm run verify +``` -### Creating a Guild +## Deployment / Stack Flow -- **Capital requirement:** Player must deposit a minimum capital (e.g. $10) at creation. - - 1000 shares are minted; initial share value = capital / 1000. -- **Metadata:** - - **Logo:** Generated via in‑game pattern designer and minted on-chain. - - **Guild name:** 4–50 chars; letters, numbers, spaces, dots; unique among active guilds. - - **Ticker:** 1–5 chars; letters, numbers, spaces, dots; globally unique. - - **Description:** Up to 4,000 characters (editable). -- **Governance settings:** Default profit distribution and role‑based rules set by CEO at creation. +Guilds uses Graphite stack workflows for incremental contract delivery. -### Closing a Guild +```bash +gt create -m "feat(guilds): " +gt restack --upstack --no-interactive +gt submit --stack --no-interactive +``` -- All members must leave or be removed. -- CEO must resign to trigger on-chain guild closure. -- A liquidation has been voted. +Operator scripts: -### Joining a Guild +- `scripts/operator/repair-graphite-stack.sh`: detects/tracks untracked branches, restacks with fallback +- `scripts/operator/qa-self-heal.sh`: verify-loop with deduplicated failure task generation -| Type | Behavior | -| -------------- | -------------------------------------------------------------------------------------------- | -| **Public** | Instant join; optional soft filters (level, experience). | -| **Private** | Players submit join request with optional message. | -| **Invitation** | Officers send direct invites; bypass request queue. | -| **Management** | Officers can approve, reject, or blacklist; Master toggles recruitment status. | +## Test & Verify Flow -### Player Management +- Contracts: `scarb fmt --check --workspace && snforge test` +- Fallback verify: `sozo test || scarb test` +- SDK type + compat + tests + build: `cd sdk && npm run verify` -- **Roles & Permissions:** Kick, ban, promote/demote -- **Request Handling:** Approve, reject, blacklist +## SDK (TS, Production-Oriented) -### Season Scoring & Standings +Package: `@runelabsxyz/guilds-sdk` -Track guild performance metrics each season: +- Typed client API (`core/client/types/utils/errors/config/bindings`) +- Contract compatibility gate via `sdk/generated/contracts.signature.json` +- Deterministic error model (`GuildsSdkError` with fixed error codes) +- Retry support for transport operations +- Example flows in `sdk/examples/` -- Sum of player scores -- Total land owned & assets -- Stakes and supply metrics -- Leaderboard positions +Common flows: ---- +1. Create guild +2. Register/wire addresses +3. Governance action + vote +4. Treasury and token/share operations -## 💰 Economic Structure +## Security Notes -Guilds manage shared capital via an on-chain share system: +- Governor-only and permission-gated boundaries enforced in guild logic +- Explicit numeric bound checks (BPS sums, plugin action ranges) +- Deterministic panic/error paths for negative scenarios +- Event coverage for indexers (`src/models/events.cairo`) -1. **Capital Building:** CEO deposits base capital; 1000 ERC‑20 shares minted. -2. **Shareholding:** Players buy shares via on-chain rounds. -3. **Voting:** Share count = voting power; used for share emissions and rate changes. -4. **Emitting Shares:** 51% shareholder approval; public purchase round with proportional allocation. +See `docs/CONTRACT-GUIDELINES-CHECKLIST.md` for itemized evidence. -### Capital Distribution & Yield +## Roadmap & Status -- Guild owns a portfolio of tokens as idle capital. -- Objective: maximize ROI by allocating to productive players. +- Completed: data model, permissions, lifecycle, token, governor, treasury, revenue +- Completed: SDK productization and operator automation +- Stack integration pending: Graphite stack submit + merge ---- +Vault coverage is tracked in `docs/VAULT-COVERAGE.md`. -## 🏛️ Guild Roles & Wallets +## Release Notes Surface -| Role | Description | -| -------------- | ------------------------------------------------------------------------------------------------- | -| **Guild Master** | Elected CEO; sole issuer of major proposals; controls master wallet. | -| **Co‑Leader** | Second‑in‑command; assists Master; accesses high‑tier wallet. | -| **Officer** | Manages membership, requests; accesses mid‑tier wallet. | -| **Member** | Standard participant; accesses member wallet. | -| **Recruit** | Trial role; limited permissions; no wallet access. | +- Release readiness: `docs/RELEASE-READINESS.md` +- SDK changelog: `sdk/CHANGELOG.md` +- Contract spec: `docs/SPEC.md` -- **Guild Wallets:** Five on-chain wallets, each gated by role for capital allocation and payouts. +## License --- diff --git a/docs/CONTRACT-GUIDELINES-CHECKLIST.md b/docs/CONTRACT-GUIDELINES-CHECKLIST.md new file mode 100644 index 0000000..b7201a1 --- /dev/null +++ b/docs/CONTRACT-GUIDELINES-CHECKLIST.md @@ -0,0 +1,20 @@ +# Contract Guidelines Checklist + +| Guideline Item | Pass/Fail | Evidence (File/Test/Commit) | Remediation PR | +| --- | --- | --- | --- | +| Access control boundaries on privileged paths | Pass | `src/guild/guild_contract.cairo` (`_only_governor`, `_check_permission`), `tests/test_permissions.cairo`, commit `dd5f53d` | - | +| Initialization safety (single init assumptions) | Pass | `src/guild/guild_contract.cairo` initialization wiring, `src/token/guild_token.cairo` constructor wiring, `tests/test_lifecycle.cairo` | - | +| Duplicate entrypoint prevention | Pass | Interface split in `src/interfaces/*.cairo`, contracts compile target in `Scarb.toml`, CI workflow `.github/workflows/_test-contracts.yaml` | - | +| Storage read/write trait correctness | Pass | `starknet::Store` derivations in `src/models/types.cairo`, storage read/write patterns in `src/guild/guild_contract.cairo`, `src/token/guild_token.cairo` | - | +| Assert/message conventions compatible with toolchain | Pass | Felt-based error constants in `src/guild/guild_contract.cairo` (`mod Errors`), negative-path tests in `tests/test_*` | - | +| Numeric bounds / felt range safety | Pass | Action bounds checks in `src/guild/guild_contract.cairo` (plugin offset overflow and BPS sum checks), tests in `tests/test_revenue.cairo` | - | +| Deterministic error paths | Pass | Centralized error constants in `src/guild/guild_contract.cairo`, `#[should_panic]` assertions across tests | - | +| Invariant preservation under edge cases | Pass | Lifecycle, treasury, token inactivity, and revenue edge cases in `tests/test_lifecycle.cairo`, `tests/test_treasury.cairo`, `tests/test_guild_token.cairo`, `tests/test_revenue.cairo` | - | +| Event emissions for indexability | Pass | Event models in `src/models/events.cairo`, emission points in `src/guild/guild_contract.cairo`, tests covering state transitions | - | +| Factory lifecycle implementation completeness | Pass | Implementation at `src/factory/guild_factory.cairo`, exports in `src/lib.cairo`, coverage in `tests/test_factory.cairo`, commit `5b6fd20` | - | + +## Notes + +- This checklist is release-gating documentation. +- A `Fail` item blocks final production-go unless explicitly accepted as a limitation. +- If a new contract/security guideline is introduced, add a new row with evidence before merge. diff --git a/docs/RELEASE-READINESS.md b/docs/RELEASE-READINESS.md new file mode 100644 index 0000000..3655c74 --- /dev/null +++ b/docs/RELEASE-READINESS.md @@ -0,0 +1,48 @@ +# Release Readiness Report + +## Checklist + +- [x] Graphite stack repair and operator scripts added (`scripts/operator/repair-graphite-stack.sh`, `46ef136`) +- [x] QA self-heal loop added (`scripts/operator/qa-self-heal.sh`, `46ef136`) +- [x] Contract test workflow exists (`.github/workflows/_test-contracts.yaml`, `46ef136`) +- [x] SDK scaffold implemented (`sdk/`, `7b6cb98`, `f2f56c9`) +- [x] Vault coverage matrix added (`docs/VAULT-COVERAGE.md`) +- [x] Contract guidelines checklist added (`docs/CONTRACT-GUIDELINES-CHECKLIST.md`) +- [x] Factory lifecycle implementation completed (`src/factory/guild_factory.cairo`, `tests/test_factory.cairo`, `5b6fd20`) + +## Known Limitations + +1. Local environment must provide Scarb/Snforge/USC toolchain (or Nix shells + binaries) for deterministic contract verification. + +## Migration Notes + +- Existing contracts follow v0.2 data model and permission boundaries (`5060c00`, `dd5f53d`, `f862363`, `91607db`, `b58d212`, `486b922`, `2370af8`). +- SDK introduces compatibility checks against Cairo interface signatures (`sdk/generated/contracts.signature.json`). +- Any interface changes now require `npm run sync:contracts` in `sdk/`. + +## Test Matrix (Current) + +| Scope | Command | Expected Result | +| --- | --- | --- | +| Cairo fmt + test | `scarb fmt --check --workspace && snforge test` | pass | +| Fallback verify | `sozo test || scarb test` | pass | +| SDK type checks | `npm run typecheck && npm run typecheck:examples` (in `sdk/`) | pass | +| SDK compatibility gate | `npm run check:compat` (in `sdk/`) | pass | +| SDK tests | `npm run test` (in `sdk/`) | pass | + +## Operator Mode + +Run from repo root: + +```bash +./scripts/operator/repair-graphite-stack.sh +./scripts/operator/qa-self-heal.sh +``` + +- `repair-graphite-stack.sh` tracks untracked branches, restacks iteratively, and clears metadata cache as fallback. +- `qa-self-heal.sh` loops verify, creates deduplicated fix tasks in `.operator/tasks/`, and exits green only when verify passes. + +## Go/No-Go + +- **Current recommendation:** **GO** after stack submit/merge and one final CI green pass. +- **Hardening window (next 7 days):** reduce deprecated `contract_address_const` usage warnings and remove stale unused imports in legacy modules. diff --git a/docs/VAULT-COVERAGE.md b/docs/VAULT-COVERAGE.md new file mode 100644 index 0000000..67946d0 --- /dev/null +++ b/docs/VAULT-COVERAGE.md @@ -0,0 +1,18 @@ +# Vault Coverage Matrix + +Canonical requirement source: `/home/mugen/Documents/Obsidian Vault/life/areas/projects/guilds.md`. + +| Vault Requirement | Task/PR | Status | Test Coverage | Merged Commit | +| --- | --- | --- | --- | --- | +| Governance-first delegation model | `feat/guild-lifecycle`, `feat/governor`, `feat/permission-system` | Implemented | `tests/test_lifecycle.cairo`, `tests/test_guild_governor.cairo`, `tests/test_permissions.cairo` | `f862363`, `b58d212`, `dd5f53d` | +| Role framework and bypass boundaries | `feat/permission-system` | Implemented | `tests/test_permissions.cairo`, `tests/test_lifecycle.cairo` | `dd5f53d`, `f862363` | +| Share lifecycle and inactivity handling | `feat/guild-token`, `feat/revenue` | Implemented | `tests/test_guild_token.cairo`, `tests/test_revenue.cairo` | `91607db`, `2370af8` | +| Dual revenue model (shareholder + member) | `feat/revenue` | Implemented | `tests/test_revenue.cairo` | `2370af8` | +| End-to-end governance to execution paths | `feat/governor`, `feat/treasury`, `feat(factory)` | Implemented | `tests/test_guild_governor.cairo`, `tests/test_treasury.cairo`, `tests/test_factory.cairo` | `b58d212`, `486b922`, `5b6fd20` | +| SDK v0 scaffold after contract hardening | `feat(sdk): production scaffold` | Implemented | `sdk/tests/address.test.ts`, `sdk/tests/retry.test.ts`, `sdk/tests/client.smoke.test.ts` | `7b6cb98`, `f2f56c9` | + +## Coverage Notes + +- Local stack commits listed above become merge commits after stack submission. +- This matrix must be updated in every cycle that changes contracts, SDK interfaces, or vault requirements. +- SDK compatibility gate is enforced by `sdk/scripts/check-contract-compat.mjs` and snapshot file `sdk/generated/contracts.signature.json`.