feat(chain): settlement program, node identity, vanity wallets, devnet scripts

.env.example

@@ -38,9 +38,39 @@ STRIPE_SECRET_KEY=sk_test_...
 STRIPE_WEBHOOK_SECRET=whsec_...
 STRIPE_PUBLISHABLE_KEY=pk_test_...
 
-# ─── Solana ──────────────────────────────────────────────────────────────────
-SOLANA_RPC_URL=https://api.devnet.solana.com
-SOLANA_WALLET_PATH=~/.config/solana/id.json
+# ─── Solana / Chain ──────────────────────────────────────────────────────────
+SOLANA_CLUSTER=devnet                              # devnet | mainnet-beta
+SOLANA_WALLET_PATH=~/.config/solana/id.json        # Path to authority keypair
+
+# Helius — Solana RPC + webhooks (https://helius.dev)
+HELIUS_API_KEY=                                    # Required for prod; falls back to public RPC
+HELIUS_WEBHOOK_ID=                                 # Set after running scripts/setup-devnet.ts
+HELIUS_WEBHOOK_SECRET=                             # Random secret for webhook auth header
+
+# Settlement program (update after anchor deploy --provider.cluster devnet)
+SETTLEMENT_PROGRAM_ID=DysEiPCWKkcMUemm1YHftCQv2UVH3JvDJsdAGbyBW4Md
+
+# Settlement wallets — generate with: solana-keygen new -o wallets/<name>.json --no-bip39-passphrase
+# Keypair files live in wallets/ (gitignored). Only pubkeys go here.
+SETTLEMENT_AUTHORITY_KEYPAIR=wallets/authority.json  # Signs settle_earnings, initialize_config
+SETTLEMENT_TREASURY_PUBKEY=                          # Receives 15% of all earnings
+SETTLEMENT_DEVELOPER_PUBKEY=                         # Receives 10% marketplace fee
+SETTLEMENT_VALIDATORS_PUBKEY=                        # Receives 5% validators pool
+
+# MACH token (set after running scripts/setup-mach-token.ts)
+MACH_MINT_ADDRESS=
+
+# Realms DAO (set after running scripts/setup-realms.ts)
+REALM_ADDRESS=                                       # Maschina DAO realm address
+
+# USDC mint addresses
+USDC_MINT_DEVNET=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
+USDC_MINT_MAINNET=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
+
+# Maschina treasury USDC token account (set after creating treasury wallet)
+TREASURY_USDC_ADDRESS=
+# Validators pool USDC token account
+VALIDATORS_USDC_ADDRESS=
 
 # ─── Services ────────────────────────────────────────────────────────────────
 GATEWAY_PORT=3001
@@ -141,3 +171,10 @@ DISCORD_CI_WEBHOOK=                # GitHub CI pass/fail notifications (set in G
 
 # ─── Feature Flags ───────────────────────────────────────────────────────────
 NODE_ENV=development
+
+# ─── App ─────────────────────────────────────────────────────────────────────
+APP_URL=http://localhost:3000        # public-facing URL for magic link emails etc.
+CORS_ORIGINS=http://localhost:5173   # comma-separated allowed origins
+PORT=3000                            # API listen port (alias for API_PORT in some services)
+DAEMON_HEALTH_PORT=3002              # daemon health-check HTTP port
+RUST_LOG=info                        # Rust log level: error | warn | info | debug | trace

.gitignore

@@ -57,6 +57,10 @@ dev.db
 *.jks
 *.keystore
 
+# ─── Solana Keypairs ─────────────────────────────────────────────────────────
+wallets/
+programs/target/deploy/*-keypair.json
+
 # ─── AI / Claude ─────────────────────────────────────────────────────────────
 CLAUDE.md
 .claude/

apps/docs/src/content/introduction.mdx

@@ -17,7 +17,7 @@ Maschina is infrastructure for autonomous digital labor. It lets you deploy AI a
 
 ## What it is
 
-Think Uber for compute. Anyone can run a Maschina node on their machine and earn credits when their hardware executes agent tasks. Developers publish agents. Users run them. Node operators get paid.
+Think Uber for compute. Anyone can run a Maschina node on their machine and earn credits when their hardware executes agent tasks. Developers publish agents. Users run them. Node runners get paid.
 
 The network is distributed, not centralized. No single server. No cloud lock-in. Jobs route to nodes based on load, model availability, and reputation.
 

apps/docs/src/routes/introduction.tsx

@@ -80,7 +80,7 @@ export const Route = createFileRoute("/introduction")({
           ]}
         />
         <p className="text-white/60 leading-7 mb-4 text-sm max-w-xl">
-          Settlement happens on Solana — node operators receive payment automatically when a run completes and is verified.
+          Settlement happens on Solana — node runners receive payment automatically when a run completes and is verified.
         </p>
 
         <h2 style={{ fontFamily: "Sohne, sans-serif" }} className="text-xl text-white mt-10 mb-4 tracking-tight">

apps/web/src/routes/about.tsx

@@ -48,7 +48,7 @@ function AboutPage() {
         <div>
           <ScrambleText text="MISSION" className="text-xs text-white/30 tracking-widest uppercase mb-6 block" />
           <p className="text-2xl font-medium text-white leading-snug pl-5" style={{ borderLeft: "2px solid #F84242" }}>
-            Make autonomous agents accessible to every developer and profitable for every node operator.
+            Make autonomous agents accessible to every developer and profitable for every node runner.
           </p>
         </div>
         <div>

apps/web/src/routes/careers.tsx

@@ -10,7 +10,7 @@ const VALUES = [
   { title: "Default to distributed", body: "We build decentralized infrastructure and operate the same way — async-first, globally distributed, no single point of failure." },
   { title: "Own the outcome", body: "Small team, real ownership. Everyone is close to the product and close to the user. No layers, no waiting for approval." },
   { title: "Build to last", body: "We move fast but we don't cut corners on correctness. Infrastructure that people depend on needs to be right." },
-  { title: "Earn trust, don't demand it", body: "From users, from node operators, from each other. Trust is the foundation of a network." },
+  { title: "Earn trust, don't demand it", body: "From users, from node runners, from each other. Trust is the foundation of a network." },
 ];
 
 function CareersPage() {

apps/web/src/routes/index.tsx

@@ -354,13 +354,13 @@ function HomePage() {
               Everyone who builds with AI.<br />Everyone who has a machine.
             </h2>
             <p className="text-base text-white/40 leading-relaxed">
-              Developers get a global execution layer for their agents. Node operators get paid to run them. The network belongs to both.
+              Developers get a global execution layer for their agents. Node runners get paid to run them. The network belongs to both.
             </p>
           </div>
           <div className="flex flex-col gap-3">
             {[
               { title: "Developers",     body: "Deploy agents in minutes. Access every major model. Pay per run, not per seat." },
-              { title: "Node operators", body: "Contribute your idle compute. Earn on every job routed your way. No staking required." },
+              { title: "Node runners", body: "Contribute your idle compute. Earn on every job routed your way. No staking required." },
               { title: "Teams",          body: "Share agents across your org. Role-based access, audit logs, and shared billing." },
               { title: "Enterprises",    body: "On-premise deployment, custom SLA, dedicated infrastructure, and volume pricing." },
             ].map((item) => (

apps/web/src/routes/marketplace.tsx

@@ -137,13 +137,13 @@ function MarketplacePage() {
             65% to the developer.<br />Not the platform.
           </h2>
           <p className="text-base text-white/40 leading-relaxed">
-            Most platforms take 30–50% of every transaction. Maschina takes 20% — split between the treasury and network validators. The developer keeps 65%. Node operators who run your agent earn the rest.
+            Most platforms take 30–50% of every transaction. Maschina takes 20% — split between the treasury and network validators. The developer keeps 65%. Node runners who run your agent earn the rest.
           </p>
         </div>
         <div className="flex flex-col gap-3">
           {[
             { label: "Developer", pct: "65%", color: "" },
-            { label: "Node operators", pct: "10%", color: "bg-white/30" },
+            { label: "Node runners", pct: "10%", color: "bg-white/30" },
             { label: "Treasury", pct: "20%", color: "bg-white/15" },
             { label: "Validators", pct: "5%", color: "bg-white/8" },
           ].map((row) => (

apps/web/src/routes/press-kit.tsx

@@ -7,7 +7,7 @@ export const Route = createFileRoute("/press-kit")({
   component: PressKitPage,
 });
 
-const BOILERPLATE = `Maschina is a distributed execution network for AI agents. Developers deploy agents through a single API and CLI — Maschina handles routing, execution, billing, and settlement across a global network of nodes. Node operators contribute compute and earn on every job routed their way. Maschina is built on the principle that the infrastructure for autonomous AI should be open, distributed, and economically fair.`;
+const BOILERPLATE = `Maschina is a distributed execution network for AI agents. Developers deploy agents through a single API and CLI — Maschina handles routing, execution, billing, and settlement across a global network of nodes. Node runners contribute compute and earn on every job routed their way. Maschina is built on the principle that the infrastructure for autonomous AI should be open, distributed, and economically fair.`;
 
 function PressKitPage() {
   return (

apps/web/src/routes/security.tsx

@@ -11,7 +11,7 @@ const PRACTICES = [
   { title: "Encryption at rest",      body: "Agent configs, run payloads, and sensitive user data are encrypted at rest using AES-256-GCM. Encryption keys are compartmentalized by data type." },
   { title: "Encryption in transit",   body: "All API endpoints are served over HTTPS/TLS 1.3. Internal service communication uses mTLS. NATS traffic is encrypted in transit." },
   { title: "Authentication",          body: "Passwords are hashed with argon2id. API keys use a prefix + hash model — we never store plaintext keys. Sessions are short-lived JWT tokens." },
-  { title: "Access control",          body: "Role-based access control at the API level. Node operators can only receive jobs, not read user data. Internal services have minimal required permissions." },
+  { title: "Access control",          body: "Role-based access control at the API level. Node runners can only receive jobs, not read user data. Internal services have minimal required permissions." },
   { title: "Infrastructure",          body: "Services run behind a reverse proxy. Internal services are not publicly exposed. Firewall rules restrict access by IP and port. fail2ban is active on all SSH-accessible hosts." },
   { title: "Dependency management",   body: "Dependencies are pinned and audited. We run automated vulnerability scans on CI. Critical patches are applied within 24 hours of disclosure." },
 ];

apps/web/src/routes/terms.tsx

@@ -9,7 +9,7 @@ export const Route = createFileRoute("/terms")({
 const SECTIONS = [
   {
     title: "Acceptance",
-    body: "By accessing or using Maschina, you agree to these Terms of Service. If you don't agree, don't use the service. These terms apply to all users — developers, node operators, and guests.",
+    body: "By accessing or using Maschina, you agree to these Terms of Service. If you don't agree, don't use the service. These terms apply to all users — developers, node runners, and guests.",
   },
   {
     title: "What Maschina provides",
@@ -28,8 +28,8 @@ const SECTIONS = [
     body: "Subscription fees are charged monthly or annually. Credits are consumed per agent run. Unused credits do not roll over unless stated. Refunds are evaluated case-by-case — contact us within 7 days of a charge.",
   },
   {
-    title: "Node operators",
-    body: "Node operators agree to execute jobs faithfully, maintain uptime commitments, and abide by network policies. Maschina may remove nodes from the network at any time for policy violations or reliability failures.",
+    title: "Node runners",
+    body: "Node runners agree to execute jobs faithfully, maintain uptime commitments, and abide by network policies. Maschina may remove nodes from the network at any time for policy violations or reliability failures.",
   },
   {
     title: "Availability",

ascii-logo.txt

@@ -0,0 +1,9 @@
+
+  ███╗   ███╗ █████╗ ███████╗ ██████╗██╗  ██╗██╗███╗   ██╗ █████╗
+  ████╗ ████║██╔══██╗██╔════╝██╔════╝██║  ██║██║████╗  ██║██╔══██╗
+  ██╔████╔██║███████║███████╗██║     ███████║██║██╔██╗ ██║███████║
+  ██║╚██╔╝██║██╔══██║╚════██║██║     ██╔══██║██║██║╚██╗██║██╔══██║
+  ██║ ╚═╝ ██║██║  ██║███████║╚██████╗██║  ██║██║██║ ╚████║██║  ██║
+  ╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝ ╚═════╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝
+
+  infrastructure for autonomous digital labor

assets/mach-token-metadata.json

@@ -0,0 +1,17 @@
+{
+  "name": "Maschina",
+  "symbol": "MACH",
+  "description": "Maschina governance and utility token. Stake to participate in network governance, earn rewards, and access premium compute capacity on the agentic network.",
+  "image": "https://arweave.net/At45mjn2d5h2VqcYVGrc9xNf4YAtSuMcaN5qChaH2VsU",
+  "external_url": "https://maschina.dev",
+  "attributes": [],
+  "properties": {
+    "files": [
+      {
+        "uri": "https://arweave.net/At45mjn2d5h2VqcYVGrc9xNf4YAtSuMcaN5qChaH2VsU",
+        "type": "image/png"
+      }
+    ],
+    "category": "image"
+  }
+}

package.json

@@ -185,6 +185,7 @@
     "@commitlint/cli": "^19.6.0",
     "@commitlint/config-conventional": "^19.6.0",
     "@discordjs/rest": "^2.6.1",
+    "@irys/sdk": "^0.2.11",
     "@semantic-release/changelog": "^6",
     "@semantic-release/github": "^10",
     "@types/node": "^22",

packages/chain/package.json

@@ -19,7 +19,10 @@
   },
   "dependencies": {
     "@coral-xyz/anchor": "^0.30.1",
+    "@solana/spl-governance": "^0.3.28",
+    "@solana/spl-token": "^0.4.9",
     "@solana/web3.js": "^1.98.0",
+    "bn.js": "^5.2.1",
     "helius-sdk": "^1.4.3",
     "tweetnacl": "^1.0.3"
   },

packages/marketplace/src/marketplace.test.ts

@@ -69,6 +69,7 @@ describe("calcExecutionRevenue", () => {
     expect(r.nodeCents).toBe(69);
     expect(r.developerCents).toBe(9);
     expect(r.validatorCents).toBe(4);
+    expect(r.treasuryCents).toBe(17);
     expect(r.nodeCents + r.developerCents + r.treasuryCents + r.validatorCents).toBe(99);
   });