How cartridge-gg/controller works
Project type and purpose
• This is a full-stack, mono-repo dApp SDK and sandboxed front-end suite for gaming-specific smart-contract wallets on StarkNet.
• Key purposes:
• Provide Rust and WASM SDKs for account interactions (account_sdk, account-wasm).
• Contain and compile Cairo contracts (contracts).
• Expose a TypeScript “Controller” SDK that embeds a sandboxed keychain iframe for signing (controller).
• Ship two user-facing front-ends: Keychain (at x.cartridge.gg) and Profile (at profile.cartridge.gg).
• Offer shared UI components (ui) and example apps (examples) that consume the Controller SDK.
File structure
• Top-level build tools: pnpm-workspace.yaml, turbo.json, Makefile, GitHub workflows.
• /packages directory hosts functional modules:
• account_sdk (Rust SDK), account-wasm (WASM build), contracts (Cairo), controller (TS SDK), connector (simple TS glue), keychain, profile (front-ends), ui (component library), plus lint and config packages.
• examples demonstrate Next.js, Svelte, Node.js integrations.
• Shared configs: ESLint, Prettier, Rust toolchain, Docker, GraphQL codegen.
README for insights
• README clearly spells out subprojects and their roles.
• Development workflow spins up four local servers: Controller example (Next.js, Svelte), Keychain, Profile.
Main components and relationships
a. On-chain Smart Contracts (StarkNet network)
• Deployed Cairo contracts under /packages/contracts/controller and /packages/contracts/resolver.
b. Rust & WASM SDK
• account_sdk (Rust crate) used in CLI or Node contexts.
• account-wasm compiled to WASM for browser usage by Keychain and examples.
c. Controller SDK (packages/controller)
• A TS library implementing StarkNet.js account interface.
• Internally loads a sandboxed Keychain iframe for signing.
d. Keychain Front-End (packages/keychain)
• React/Vite app served at localhost:3001 or x.cartridge.gg.
• Uses account-wasm to perform crypto, manages Passkey/WebAuthn and session tokens.
• Exposes an iframe messaging API consumed by Controller SDK.
e. Profile Front-End (packages/profile)
• React/Vite app served at localhost:3003 or profile.cartridge.gg.
• Uses Controller SDK for on-chain reads and uses ui and GraphQL APIs for off-chain data.
f. UI Library (packages/ui)
• Shared component and styling library used by Keychain, Profile, and Examples.
• Connects to GraphQL backends via auto-generated code in utils/api.
g. Backend APIs (GraphQL)
• Cartridge API endpoint (/utils/api/cartridge/...) provides user, balances, transfers, etc.
• Indexer API endpoint (/utils/api/indexer/...) provides event and token indexing.
h. Example Apps (examples/next, examples/svelte, examples/node)
• Import Controller SDK and UI, demonstrate integration and e2e tests.
i. CI/CD & Tooling
• GitHub Actions for build, test, deploy.
• Dockerfiles, codegen scripts, schema pulls.
[Developer Environment] | [Frontend Apps] | [SDKs & Libraries] | [Blockchain & Backends]
• Frontends: Keychain, Profile, Examples
• SDKs: Controller SDK (TS), account-wasm (WASM), account_sdk (Rust)
• UI Library
• Backends: GraphQL Cartridge API, GraphQL Indexer API, StarkNet Blockchain
• Examples → Controller SDK → Keychain iframe → account-wasm → Blockchain
• Controller SDK ↔ Keychain iframe (postMessage channel)
• Frontends & UI Library → GraphQL APIs (Cartridge & Indexer)
• Rust SDK → CLI / Node.js contexts → Blockchain
Architectural patterns and principles
• Monorepo managed by pnpm/Turbo: emphasize shared build and versioning.
• Micro-frontend sandbox: Keychain and Profile as isolated apps with iframe boundary.
• SDK composition: layering from low-level Rust → WASM → TS Controller → Frontend apps.
• Separation of concerns: On-chain logic (contracts) vs off-chain UI & data (GraphQL APIs).
Detail level
• Local development servers and ports for examples and frontends.
• Build scripts (Makefile, Dockerfile, GitHub workflows) near relevant components.