1  # How-To Guide — Frame17711
  2  
  3  Task-oriented guides. Find what you want to do, follow the steps.
  4  
  5  ---
  6  
  7  ## Deploy a Service
  8  
  9  ### What happens
 10  
 11  1. You build a release binary → BLAKE3 hash
 12  2. Ansible deploys to node → Quadlet container starts
 13  3. Service auto-registers in directory (`ServiceEntry`)
 14  4. Fabric ledger records deployment (private, operational)
 15  5. Polygon records CI proof (public, minimal — hash only)
 16  6. Caddy auto-configures HTTPS vhost from directory
 17  7. Service appears in catalog (`catalog.mesh.17711.org`)
 18  
 19  ### Steps
 20  
 21  ```bash
 22  cargo build --release
 23  b3sum target/release/org-17711-mesh-{name}
 24  ansible-playbook playbooks/deploy-{name}.yml --ask-vault-pass
 25  mesh service verify org.17711.mesh/{name}
 26  ```
 27  
 28  ### Blockchain contracts involved
 29  
 30  | Contract | What it stores | Chain |
 31  |---|---|---|
 32  | `CiReport17711Contract` | Build hash + commit + status | Polygon |
 33  | `Deployment17711Registry` | Domain hash + service_id + status | Polygon |
 34  | Fabric `register_deployment` | Full deployment record (version, hash, node, wallet) | Fabric (local) |
 35  
 36  ---
 37  
 38  ## Bump a Version
 39  
 40  ### What happens
 41  
 42  1. You edit `Cargo.toml` version
 43  2. Founder signs with wallet (SIWE)
 44  3. CI builds + hashes the new version
 45  4. `VersionedRelease17711Registry` records the new version on-chain
 46  5. All services update to new version on next deploy
 47  
 48  ### Steps
 49  
 50  ```bash
 51  # 1. Edit version
 52  vim Cargo.toml  # workspace.package.version = "X.Y.Z"
 53  cargo check --workspace && cargo test
 54  
 55  # 2. Commit + sign
 56  git commit --author="Paul Milton <paul.milton@17711.org>"
 57  mesh release sign vX.Y.Z
 58  
 59  # 3. Tag + push
 60  git tag vX.Y.Z
 61  rad push
 62  # → CI: build → hash → register on-chain
 63  ```
 64  
 65  ### Blockchain contracts involved
 66  
 67  | Contract | What it stores | Chain |
 68  |---|---|---|
 69  | `VersionedRelease17711Registry` | Version + BLAKE3 hash + commit | Polygon |
 70  | `CiReport17711Contract` | Build pipeline result | Polygon |
 71  
 72  ### Rules
 73  
 74  - Pre-1.0.0: single founder signature
 75  - Post-1.0.0: F(5)-of-F(6) = 5-of-8 quorum
 76  
 77  ---
 78  
 79  ## Register a JSON Schema
 80  
 81  ### What happens
 82  
 83  1. You modify a Rust struct with `#[derive(Serialize, Deserialize)]`
 84  2. CI detects schema change (BLAKE3 hash differs from on-chain)
 85  3. Additive change → minor bump eligible
 86  4. Breaking change → pipeline FAIL, major bump required
 87  5. Founder signs → schema registered on-chain
 88  6. Schema content stored in OrbitDB (BLAKE3-addressed)
 89  
 90  ### Steps
 91  
 92  ```bash
 93  # Check schema status
 94  mesh schema verify
 95  
 96  # Register (founder signature required)
 97  mesh schema register urn:17711:schema:scim:user:0.2.3+43.KfR7bNm
 98  ```
 99  
100  ### Blockchain contracts involved
101  
102  | Contract | What it stores | Chain |
103  |---|---|---|
104  | `Schema17711Registry` | Schema URN + BLAKE3 hash + version + deprecated flag | Polygon |
105  | OrbitDB | Full JSON Schema content (encrypted) | Mesh (IPFS) |
106  
107  ### URN format
108  
109  `urn:17711:schema:{category}:{entity}:{semver}+{pipeline}.{commit_b55}`
110  
111  ---
112  
113  ## Create a Smart Contract
114  
115  ### What happens
116  
117  1. You write Solidity extending `Mesh17711ContractBase`
118  2. Contract inherits: version, family, pause/unpause, registry link
119  3. Deploy to Polygon mainnet
120  4. Contract address registered in `VersionedRelease17711Registry`
121  5. ABI hash registered on-chain for client verification
122  
123  ### Steps
124  
125  ```bash
126  cd org-17711-mesh/contracts
127  npx hardhat compile
128  npx hardhat test
129  npx hardhat run scripts/deploy-{name}.ts --network polygon
130  ```
131  
132  ### Base contract
133  
134  All contracts extend `Mesh17711ContractBase`:
135  - `VERSION_MAJOR`, `VERSION_MINOR`, `VERSION_PATCH` (immutable at deploy)
136  - `CONTRACT_FAMILY` (keccak256 of family name)
137  - `registry` (link to VersionedRelease17711Registry)
138  - `pause()` / `unpause()` (owner only)
139  
140  ### Existing contracts (26)
141  
142  | Family | Contracts |
143  |---|---|
144  | Token | `Frame17711Token`, `O17711Token`, `TokenLevels17711Contract` |
145  | Governance | `Frame17711DAO`, `Frame17711Governor`, `Governance17711Contract`, `Governance17711Suspension`, `Emergency17711Guard` |
146  | Partners | `Partners17711DAO`, `Partners17711Gov`, `Partners17711Governor` |
147  | Treasury | `Mesh17711Treasury`, `Treasury17711Split`, `Commission17711Contract`, `Referral17711Contract` |
148  | Operations | `Quota17711Contract`, `Metering17711Contract`, `Sla17711Contract`, `TierConfig17711Contract` |
149  | Hosting | `Hosting17711Contract` |
150  | Registry | `Deployment17711Registry`, `VersionedRelease17711Registry`, `Schema17711Registry` |
151  | Compliance | `Charter17711Contract`, `CiReport17711Contract` |
152  
153  ---
154  
155  ## Add a UI Component
156  
157  ### What happens
158  
159  1. You create a Vue 3 component following `{Name}17711` naming
160  2. Component is added to `@org-17711-mesh/ui-components` package
161  3. Package published to `js.factory.mesh.17711.org`
162  4. BLAKE3 hash of package tarball registered on-chain
163  5. Component appears in catalog with `data-component` DOM attribute
164  
165  ### Steps
166  
167  ```bash
168  # Create component
169  cat > libs/ui-components/src/components/MyNew17711Widget.vue
170  
171  # Export it
172  # → add to libs/ui-components/src/index.ts
173  
174  # Test
175  cd libs/ui-components && npm test
176  
177  # Publish (founder signature for version bump)
178  npm publish --registry https://js.factory.mesh.17711.org
179  ```
180  
181  ### Blockchain contracts involved
182  
183  | Contract | What it stores | Chain |
184  |---|---|---|
185  | `VersionedRelease17711Registry` | Package version + BLAKE3 hash | Polygon |
186  
187  ### Naming
188  
189  - Component: `MyNew17711Widget`
190  - DOM: `data-component="MyNew17711Widget"`, `data-contract="{hash}"`
191  
192  ---
193  
194  ## Grant Permissions (Zanzibar ACL)
195  
196  ### What happens
197  
198  1. Wallet A (owner) creates a delegation
199  2. Zanzibar tuple stored: `(namespace:resource#relation@subject)`
200  3. Subject can now access the resource within TTL
201  4. Delegation expires after F(12)=144 hours (auto-revoke)
202  
203  ### Steps
204  
205  ```bash
206  # Grant editor access on a site
207  mesh delegate grant \
208    --namespace site \
209    --resource my-site.mesh.17711.org \
210    --relation editor \
211    --to 0x742d...2bd18
212  
213  # Check permissions
214  mesh delegate check \
215    --namespace site \
216    --resource my-site.mesh.17711.org \
217    --relation reader \
218    --who 0x742d...2bd18
219  
220  # Revoke
221  mesh delegate revoke --id <delegation-id>
222  ```
223  
224  ### ACL hierarchy
225  
226  `owner` ⊃ `admin` ⊃ `editor` ⊃ `writer` ⊃ `reader` ⊃ `authenticated` ⊃ `anonymous`
227  
228  ---
229  
230  ## Monitor the Mesh
231  
232  ### What happens
233  
234  - All services export Prometheus metrics on port 17944+
235  - Logs shipped to Loki in JSON format with correlation IDs
236  - Dashboards aggregate everything in Grafana
237  - All o11y data is public (wallet-auth, any wallet)
238  
239  ### URLs
240  
241  | Tool | URL | What |
242  |---|---|---|
243  | Dashboards | `dashboards.o11y.mesh.17711.org` | Grafana panels |
244  | Metrics | `metrics.o11y.mesh.17711.org` | Prometheus queries |
245  | Logs | `logs.o11y.mesh.17711.org` | Loki LogQL |
246  
247  ### Key metrics
248  
249  - `mesh_requests_total` — HTTP requests per service
250  - `mesh_latency_seconds` — p50/p95/p99 latency
251  - `mesh_node_status` — node up/down/degraded
252  - `mesh_build_hash` — current deployed build hash
253  
254  ---
255  
256  ## Access Commercial Code
257  
258  ### What happens
259  
260  1. You acquire `eu.17711.smart` token
261  2. Connect wallet at `sources.smart.17711.eu`
262  3. SIWE challenge → token ownership verified
263  4. Clone access granted
264  
265  ### Steps
266  
267  ```bash
268  # Clone (token required)
269  rad clone rad:eu-17711-smart --seed sources.smart.17711.eu
270  
271  # Install commercial plugin
272  mesh plugin install eu.17711.smart/code-analysis
273  
274  # Use
275  mesh analyze java ./src --profile owasp
276  mesh analyze sql pgsql ./queries
277  ```
278  
279  ### Blockchain contracts involved
280  
281  | Contract | What it stores | Chain |
282  |---|---|---|
283  | `O17711Token` | Token ownership (ERC-20/721) | Polygon |
284  | `TierConfig17711Contract` | Access tiers + quotas | Polygon |
285  
286  ---
287  
288  ## Check Any Service Version
289  
290  ### What happens
291  
292  Every service exposes its exact version. DNS root = `current` (DAO-blessed). Every brick is versioned identically.
293  
294  ### Steps
295  
296  ```bash
297  # Check current version (DNS root = current)
298  curl https://dashboards.o11y.mesh.17711.org/health
299  # → {"version": "v0.2.2+42.KfR7bNm", "selector": "current"}
300  
301  # Check latest version
302  curl https://dashboards.o11y.mesh.17711.org/api/latest/health
303  # → {"version": "v0.2.3+43.MpT9cQw", "selector": "latest"}
304  
305  # Check specific version
306  curl https://dashboards.o11y.mesh.17711.org/api/v0.2.2/health
307  # → {"version": "v0.2.2+42.KfR7bNm", "selector": "v0.2.2"}
308  
309  # Works for ALL services:
310  curl https://ci.factory.mesh.17711.org/health
311  curl https://metrics.o11y.mesh.17711.org/health
312  curl https://api.mesh.17711.org/health
313  curl https://org.sources.oss.mesh.17711.org/health
314  ```
315  
316  ### Blockchain contracts involved
317  
318  | Contract | What it stores | Chain |
319  |---|---|---|
320  | `VersionedRelease17711Registry` | `current` → version hash mapping | Polygon |
321  | `Deployment17711Registry` | Service domain → version + status | Polygon |
322  | Fabric ledger | Full deployment history per service | Fabric (free) |
323  
324  ### Version selectors
325  
326  | Selector | What | When to use |
327  |---|---|---|
328  | `current` | DAO-blessed stable | Production clients (DNS root default) |
329  | `latest` | Most recent deploy | Dev/testing |
330  | `v0.2.2` | Exact pinned version | Reproducibility, rollback |
331  
332  ### Verify version on-chain
333  
334  ```bash
335  # Verify what's deployed matches what's on-chain
336  mesh service verify org.17711.mesh/dashboards
337  # → version: v0.2.2+42.KfR7bNm
338  # → BLAKE3: abc123...
339  # → Polygon tx: 0xdef456...
340  # → Status: ✓ Verified
341  ```
342  
343  ---
344  
345  ## Revenue Distribution — Fibonacci Split
346  
347  ### What happens
348  
349  Every foundation sale is automatically split across 9 pools via `Treasury17711Split` on Polygon. The percentages follow Fibonacci numbers. The Social Impact pool (34%) has an **immutable minimum** — it can never go below F(9).
350  
351  ### Distribution
352  
353  | Pool | % | F(n) | Purpose |
354  |---|---|---|---|
355  | Social Impact | 34% | F(9) | Good causes, associations, environment |
356  | Open Source | 21% | F(8) | Mesh development, infrastructure |
357  | DAO Treasury | 13% | F(7) | Governance-allocated budget |
358  | Founders & Devs | 13% | F(7) | Core team compensation |
359  | Architects | 8% | F(6) | System design, ADRs |
360  | Node Operators | 5% | F(5) | Infrastructure providers |
361  | Community | 3% | F(4) | Bug bounty, grants, contributions |
362  | Documentation | 2% | F(3) | Docs, i18n, translation |
363  | Emergency | 1% | F(2) | Reserve fund |
364  
365  ### Blockchain contracts involved
366  
367  | Contract | What | Chain |
368  |---|---|---|
369  | `Treasury17711Split` | Splits ERC-20 payments to 9 wallets | Polygon |
370  
371  ### Rules
372  
373  - Social Impact ≥ 34% — immutable floor (enforced in contract)
374  - BPS must always sum to 10000 (100%)
375  - Pool wallets updatable by DAO governance
376  - Ratios updatable by DAO governance (within constraints)
377  - Rounding dust goes to Emergency pool
378  
379  ### Verify
380  
381  ```bash
382  # Check pool details
383  mesh treasury pool 0  # → Social Impact: 34%, wallet: 0x..., total: X tokens
384  
385  # Check all pools
386  mesh treasury pools  # → table of all 9 pools with totals
387  ```