2026-11-17 15:49:51 -03:00
2026-06-19 10:39:15 -03:00
2026-06-19 10:39:15 -03:00

Mesh

Upgrading an existing Daochi node preserves credentials, signed bytes and stored data.

Mesh is a mesh-native sync network for app-owned data. It stores public keys and mirrored app data, but never stores client private keys. New clients should use the X-Mesh-* wire headers. The server still accepts shipped X-Daochi-*, X-Ksync-* and X-Inbe-* compatibility headers.

Philosophy

Mesh is built for imperfect networks, older devices, and changing servers. Its design rules are:

  • local first: account authority begins on the user's device;
  • respect old hardware: keep the relay useful on modest machines, old phones, small home nodes, and low-power servers;
  • store less, reveal less: move and order private records without reading them whenever clients can carry that responsibility;
  • keep old paths open: compatibility windows and migrations are part of the product;
  • make trust inspectable: keys, signatures, app ownership, protocol versions, and node relationships should be understandable.

Guides

Privacy Model

Mesh uses the client account key for identity and authentication. A client proves control of the account by signing a short-lived challenge with ML-DSA-44, and the server then issues a bearer token for normal sync and social API calls.

The legacy typed sync surface is not end-to-end encrypted against the server. Mirrored app data is stored in SQLite as normal typed rows and JSON payloads so the service can sync, compact, export, derive friend leaderboard stats, and delete account data. This is intentional for compatibility. Operational access to the server database or a valid bearer token can read the typed data those credentials allow.

Protocol clients may also sync encrypted_records: opaque per-account private records identified by collection and id. Mesh stores and versions those blobs for relay, export, deletion, and diagnostics, but does not need to read their contents. Protocol v4 advertises this as the dual-write transition path: upgraded clients can keep sending legacy typed rows for compatibility while also seeding encrypted private records for future mesh-capable clients. Protocol v5 makes encrypted records the primary private-data surface for upgraded clients while legacy typed rows remain available through include_legacy_data for compatibility. Released legacy encrypted collections remain valid in v5 so clients do not need an immediate second backfill migration. Public/social projections such as aliases, friend requests, profile icons, and leaderboard stats remain readable server-side by design.

Clients that encrypt the whole sync payload may post an encrypted envelope to POST /api/v1/sync with JSON fields v, nonce, and ciphertext. Mesh authenticates the bearer token, stores the envelope bytes opaquely, assigns a normal server_version, and returns encrypted envelopes newer than X-Mesh-Since-Version. Existing typed clients keep using the same endpoint and JSON shape as before; the server only takes the envelope path when the request body has the explicit encrypted-envelope shape.

Mesh keeps an app registry so data ownership is app-neutral and no product behavior is hard-coded into the service. Inbe is a built-in registration because its released sync formats are a compatibility contract. The other built-in registration is entity, the account's own data (see Entity data). Every other app installs and maintains its own signed manifest, keys, collection scopes, and token policy. Registered apps can send app_id in v5 compatibility mode only when their manifest explicitly allows that protocol. Older shipped Inbe clients without app_id continue to sync during the compatibility window. A sync request may write only its own app's collections, and a request without app_id counts as Inbe, so a bearer token alone cannot reach another app's records. Protocol v6 requests must include a registered app_id, a signed transaction envelope, and encrypted record collections declared by that app.

Protocol compatibility policy: protocol v1 through v5 are valid through 2027-09-01 for legacy clients covered by app policy. When a future protocol version is deprecated, the immediately previous version must remain valid for at least one additional year, and the current protocol version must always stay valid. App manifests declare their own compatibility windows through compatibility_until and legacy_protocols.

API access is scoped by account, with explicit shared surfaces:

  • accepted friends can see the account alias and selected profile/leaderboard stats;
  • user-created app grants can share shared.*, friends.*, or public.* encrypted record prefixes with another registered app;
  • pending friend request participants can see the request metadata;

Endpoints

  • GET /api/v1/sync/challenge?user_id=<sha256-public-key-hex>
  • GET /api/v1/sync/diagnostics
  • GET /api/v1/sync/ws
  • POST /api/v1/sync/login
  • POST /api/v1/sync
  • POST /api/v1/account/delete
  • GET /api/v1/apps
  • POST /api/v1/apps with X-Mesh-Admin when MESH_ADMIN_TOKEN is set
  • POST /api/v1/apps/register-signed
  • GET /api/v1/apps/{app_id}
  • GET /api/v1/apps/{app_id}/collections
  • GET /api/v1/node
  • POST /api/v1/node/pairing/invites
  • POST /api/v1/node/pairing/accept
  • POST /api/v1/node/pairing/complete
  • GET /api/v1/node/peers
  • POST /api/v1/link/put, POST /api/v1/link/get and POST /api/v1/link/close relay one sealed request and response between two devices connecting by QR code; links expire after ten minutes, and a closed link stays closed until then
  • POST /api/v1/namespaces
  • POST /api/v1/namespaces/claims
  • GET /api/v1/namespaces/resolve?space_id=<id>&name=<name>
  • POST /api/v1/node/mesh/export
  • POST /api/v1/node/mesh/import
  • GET /api/v1/tokens/assets
  • GET /api/v1/tokens/products
  • GET /api/v1/rates (public XMR/USD display rate and the Dew funding ratio)
  • GET /api/v1/tokens/issuer
  • GET /api/v1/tokens/balance?app_id=<optional-app-id>
  • GET /api/v1/tokens/ledger?since=<optional-seq>&app_id=<optional-app-id>
  • GET /api/v1/tokens/activity?before_seq=<optional-seq>&limit=<optional-count>
  • POST /api/v1/tokens/spend
  • POST /api/v1/tokens/gifts (Dew to a friend)
  • POST /api/v1/tokens/purchases/google/verify
  • POST /api/v1/tokens/purchases/monero/invoices
  • GET /api/v1/tokens/purchases/monero/invoices/{id}
  • GET /api/v1/tokens/purchases/monero/address (authenticated account)
  • GET /api/v1/tokens/purchases/monero/address/{alias-or-public-id} (gift recipient)
  • GET /api/v1/tokens/purchases/monero/deposits
  • GET /api/v1/tokens/checkpoints/latest
  • GET /api/v1/tokens/receipts/{receipt_id}
  • POST /api/v1/admin/tokens/manual-credit
  • POST /api/v1/admin/tokens/checkpoint
  • POST /api/v1/account/alias
  • GET /api/v1/account/alias?alias=<name> (authenticated availability and DEW quote)
  • POST /api/v1/account/alias/purchase (explicit premium username purchase)
  • GET /api/v1/account/export
  • GET /api/v1/account/app-grants
  • POST /api/v1/account/app-grants
  • POST /api/v1/account/app-grants/signed
  • DELETE /api/v1/account/app-grants/{id}
  • GET /api/v1/account/app-records?source_app_id=&target_app_id=&collection_prefix=
  • GET /api/v1/friends
  • GET /api/v1/friends/requests
  • POST /api/v1/friends/requests
  • POST /api/v1/friends/requests/{id}/accept
  • POST /api/v1/friends/requests/{id}/decline
  • DELETE /api/v1/friends/{user_id_hash}
  • PUT /api/v1/profile/stats
  • GET /api/v1/friends/stats?app=&practice=&metric=
  • GET /api/v1/publications?format=&author= (published level collections)
  • POST /api/v1/publications
  • GET /api/v1/publications/{id}
  • DELETE /api/v1/publications/{id}
  • DELETE /api/v1/account
  • POST /api/v1/account/delete-with-key
  • GET /openapi.json
  • GET /healthz
  • GET /readyz
  • GET /metrics
  • GET /

GET /api/v1/node includes aggregate usage counts for public node dashboards: registered users, users active in the last 30 days, registered clients, clients active in the last 30 days, distinct connected WebSocket users, and current WebSocket client connections. /metrics publishes the same aggregate user and client gauges with mesh_* names; legacy ksync_* metric aliases remain for existing dashboards.

The public API hostname should terminate TLS at a reverse proxy and forward to MESH_ADDR, for example 127.0.0.1:8080. Set MESH_TOKEN_SECRET_HEX to at least 32 random bytes encoded as hex in production. MESH_ALLOW_EPHEMERAL_TOKEN_SECRET=1 is only for local development because it invalidates tokens on restart and is not a stable server secret.

POST /api/v1/sync accepts up to 300 requests a minute per account across its devices; more return 429. Blobs count toward MESH_ACCOUNT_STORAGE_LIMIT_BYTES like records, and deleting an account removes its blob files.

Bearer tokens are intentionally cacheable client-side credentials, not the user's durable login state. Clients should silently run the challenge/sign/login flow again when a token expires or receives a 401, as long as the local account key still exists. Login responses include server_time as Unix seconds so clients can compensate for local clock skew when caching token expiry. Older clients may ignore it. Only an explicit user logout, account deletion, or local account reset should remove the account key.

The WebSocket endpoint accepts bearer auth through Authorization: Bearer <token>. Browser clients that cannot set custom WebSocket headers may send Sec-WebSocket-Protocol: mesh-sync-v1, bearer.<token>. Legacy daochi-sync-v1, ksync-sync-v1 and inbe-sync-v1 subprotocols remain accepted. Mesh rejects ?token= WebSocket URLs so bearer tokens do not leak through request URLs, browser history, or proxy URL logs.

Encrypted envelope clients should send:

  • Authorization: Bearer <token>
  • X-Mesh-User: <sha256-public-key-hex>
  • X-Mesh-Client: <client-id> when available
  • X-Mesh-Since-Version: <last-seen-server-version> when requesting only newer envelopes
  • X-Mesh-Limit: <count> when deliberately paging envelope deltas

X-Ksync-* header names remain accepted as compatibility aliases. Envelope bodies are relayed as JSON encrypted_payloads in the sync response. Mesh does not parse the envelope contents beyond checking that v is 1 or 2 and nonce and ciphertext are non-empty. If a response is paged, encrypted_payloads_truncated is true and encrypted_payloads_next_since_version is the next value to send as X-Mesh-Since-Version.

Signature Message

Clients must sign this exact byte string with ML-DSA-44:

daochi-sync-v1
<HTTP_METHOD>
<HTTP_PATH>
<sha256 hex of exact raw request body bytes>
<challenge nonce hex>

Legacy ksync-sync-v1 and inbe-sync-v1 signed-message contexts remain accepted with their matching legacy signature headers.

The challenge response returns nonce as lowercase hex. The challenge is single-use and expires after 60 seconds by default.

Bearer-authenticated POST /api/v1/sync requests must include Authorization: Bearer <token>, X-Mesh-User: <sha256-public-key-hex>, and Content-Type: application/json. Legacy account headers remain accepted.

Protocol v6 POST /api/v1/sync requests must also include X-Mesh-Tx. The header is either raw JSON or base64url JSON with:

  • protocol_version: 6
  • tx_id and nonce, both replay-protected per account
  • account_id, matching the bearer account
  • app_id, matching the request body app ID
  • app_key_id, matching an active key in the app manifest
  • method, path, and body_sha256 for the exact HTTP request
  • expires_at, no more than 15 minutes in the future
  • signature, an ML-DSA-44 account signature over the canonical transaction message
  • app_signature, an Ed25519 app-key signature over the same canonical transaction message

The canonical transaction message is:

daochi-tx-v1
<protocol_version>
<tx_id>
<account_id>
<app_id>
<app_key_id>
<HTTP_METHOD>
<HTTP_PATH>
<sha256 hex of exact raw request body bytes>
<nonce>
<expires_at unix seconds>

Signed POST /api/v1/account/delete and legacy DELETE /api/v1/account requests must include:

  • X-Mesh-User: <sha256-public-key-hex>
  • X-Mesh-Signature: <ML-DSA-44 signature>
  • Content-Type: application/json

Signed JSON bodies still include user_id_hash for compatibility. The server accepts public_key and signatures as either base64 or lowercase/uppercase hex. This matches the current C client account storage, which keeps ML-DSA-44 keys as hex strings.

The preferred account deletion endpoint is POST /api/v1/account/delete, using the same challenge/signature scheme as login and sync so the private key never leaves the device. DELETE /api/v1/account remains supported for older clients that already shipped with that wire shape.

The website deletion endpoint POST /api/v1/account/delete-with-key accepts user_id_hash plus the full exported account key text. Current exports start with ksync-account-key-v1, and legacy account key exports are still accepted. Current key exports include public_id, and Mesh rejects a request if that public ID does not match user_id_hash. Mesh signs a fixed deletion proof with that private key, verifies it against the registered public key, deletes the account, and does not store the uploaded key.

Build

From this project directory, build with:

make build

The Makefile builds a minimal static liboqs from vendor/liboqs with SIG_ml_dsa_44 enabled, then passes the right cgo include/library flags to Go. Use make test for the same setup in tests.

For large v6 encrypted libraries, POST /api/v1/sync accepts encrypted_records_only: true and record_limit (1–200, default 200). This signed app-scoped exchange excludes legacy data and account snapshots. Continue incomplete pages with the returned record_cursor (version, collection, id), retaining since_server_version until changes_complete is true. Then checkpoint server_version and clear the cursor. Persist records and their checkpoint atomically. Each response contains at most 200 records and 4 MiB of ciphertext. Clients must verify encrypted_records_only in the response; older nodes do not implement this mode. Full replacements, legacy writes, operations and state-hash reconciliation must use the existing sync mode.

Mesh's server implementation is authored in Ziran. Go is generated from the canonical .zi modules under src/ and tests/ziran/ and is not committed. Use Go 1.26. Run make generate after changing Ziran source and make test-ziran to check generated files and run the server suite against both source and saved Ziran IR. The default launcher is ziran, which resolves the pinned project toolchain; ZIRAN overrides the launcher. Local compiler checkouts belong in the ignored ziran.local.toml package overrides. See the development guide for source ownership and the build and verification workflow.

Inspect a production database offline with:

./mesh inspect --db /var/lib/mesh/mesh.db summary
./mesh inspect --db /var/lib/mesh/mesh.db doctor <user_id_hash>

inspect doctor prints redacted account status, sync versions, table counts, recent client protocol hints, and recent sync audit metadata. Use --full only when you intentionally need unredacted IDs.

Without Nix, install liboqs headers and library on the host, then:

make generate
CGO_ENABLED=1 go build -mod=mod -o mesh .

Runtime configuration:

MESH_ADDR=127.0.0.1:8080
MESH_BASE_URL=https://api.example.com
MESH_DB=/var/lib/mesh/mesh.db
MESH_ADMIN_TOKEN=<optional admin token; also gates GET /metrics and app registry writes when set>
MESH_TOKEN_SECRET_HEX=<stable 64+ hex chars shared by every server instance>
MESH_NODE_REGISTRY_PUBLIC_KEY_HEX=<ed25519 public key hex for signed app approvals>
MESH_NODE_REGISTRY_PUBLIC_KEY_HEX_FILE=/run/secrets/node_registry_public.hex
MESH_NODE_NAME=Home
MESH_NODE_IDENTITY_KEY_FILE=/var/lib/mesh/node.key
MESH_LAN_DISCOVERY=1
MESH_KNOWN_NODES=Public=https://api.example.com;sync=pull;apps=inbe;collections=private.inbe.v1.*;data=app_registry+encrypted_records
MESH_NODE_SYNC_TOKEN=<shared secret for trusted node-to-node mesh sync>
MESH_NODE_SYNC_INTERVAL_SECONDS=60
MESH_NODE_SYNC_BATCH_LIMIT=500
MESH_TOKEN_ISSUER_PUBLIC_KEY_HEX=<ed25519 public key hex>
MESH_TOKEN_ISSUER_PUBLIC_KEY_HEX_FILE=/run/secrets/token_issuer_public.hex
MESH_TOKEN_ISSUER_PRIVATE_KEY_HEX=<ed25519 private key hex, issuer nodes only>
MESH_TOKEN_ISSUER_PRIVATE_KEY_HEX_FILE=/run/secrets/token_issuer_private.hex
MESH_TOKEN_PRODUCTS=tokens_small:5000000:1000000000000
MESH_GOOGLE_PACKAGE_NAMES=com.example.app
MESH_GOOGLE_SERVICE_ACCOUNT_JSON=<google service account json>
MESH_GOOGLE_SERVICE_ACCOUNT_JSON_FILE=/run/secrets/google_play_service_account.json
MESH_GOOGLE_OAUTH_CLIENT_JSON_FILE=/run/secrets/google_play_oauth_client.json
MESH_GOOGLE_OAUTH_REFRESH_TOKEN_FILE=/run/secrets/google_play_refresh_token.txt
MESH_TOKEN_DIRECT_PURCHASES_ENABLED=1
MONERO_WALLET_RPC_URL=http://127.0.0.1:18083
MONERO_WALLET_RPC_USER=<wallet rpc user>
MONERO_WALLET_RPC_PASSWORD_FILE=/run/credentials/mesh.service/monero_rpc_password
MONERO_NETWORK=stagenet
MONERO_RATE_ATOMIC_AMOUNT=1000000000000
MONERO_RATE_TOKEN_UNITS=5000000
MONERO_MINIMUM_ATOMIC_AMOUNT=1000
MONERO_CONFIRMATIONS_REQUIRED=10
MESH_CHALLENGE_TTL_SECONDS=60
MESH_TOKEN_TTL_SECONDS=3600
MESH_MAX_BODY_BYTES=1048576
MESH_ENCRYPTED_PAYLOAD_MAX_RETURN=0
MESH_ENCRYPTED_PAYLOAD_MAX_ACCOUNT_BYTES=0
MESH_ENCRYPTED_PAYLOAD_RETENTION_DAYS=0

Wallet RPC Digest authentication requires a SHA-256 challenge. Mesh rejects MD5-only challenges; use a wallet RPC version supporting SHA-256. RPC credentials are sent only to the configured HTTPS or literal loopback destination, and redirects are refused.

The CodeQL review in scripts/security_reviews.json classifies this SHA-256 Digest exchange as protocol authentication rather than password storage. It matches only the reviewed source fingerprint, digest function and authentication call site; other high-severity findings and source changes still block release.

When MONERO_RATE_ATOMIC_AMOUNT and MONERO_RATE_TOKEN_UNITS are set, every Mesh account receives one permanent Monero subaddress on first use. Sending XMR to that address credits the account at the configured integer ratio after the transfer reaches MONERO_CONFIRMATIONS_REQUIRED, is unlocked, has zero unlock_time, and has not been marked as a double spend. Looking up an alias or public ID returns the same address, so purchasing for yourself and gifting use the same payment flow. Rate values are snapshotted when a transfer is first observed. Each deposit also snapshots the node's public XMR/USD display rate at first observation (usd_cents, usd_rate_time, usd_sources), so every credited deposit keeps the fiat value at receipt as an audit record; the snapshot stays zero while no fresh rate exists and never affects the Dew amount. Existing product invoices remain available during migration.

Inbe calls this account credit Dew. Its existing asset ID stays waozi:token, with 1,000,000 integer ledger units per Dew. Storage prices are fixed in XMR, with no dollar peg, exchange-rate feed, or fiat conversion. Choose how much Dew one XMR buys and express that ratio in integer units (1 XMR = 1,000,000,000,000 atomic units). For 10,000 Dew per XMR, set MONERO_RATE_ATOMIC_AMOUNT=1000000000000 and MONERO_RATE_TOKEN_UNITS=10000000000. One month of 1 GB storage costs 20 Dew (0.002 XMR at that ratio) and one year costs 200 Dew. The app shows the node's Dew prices before purchase. Confirmed deposits retain their snapshotted fixed ratio, and existing Dew balances remain intact.

Set MESH_STORAGE_PLANS_ENABLED=true on a node offering prepaid storage. A valid fixed Monero ratio is required before upgrades can be purchased. The free allowance is the node's MESH_ACCOUNT_STORAGE_LIMIT_BYTES. Two sizes are sold: 1 GiB costs 20 Dew a month or 200 Dew a year, and 5 GiB costs 60 Dew a month or 600 Dew a year. Buying the current size extends an existing paid period or starts immediately, with calendar month/year expiry. Buying the other size starts now, and the unexpired time carries over converted by the monthly prices (three days of 1 GiB become one day of 5 GiB). Plans do not renew automatically. GET /api/v1/storage/plan returns the authenticated account's balance, allowance and the plans with their Dew and XMR prices. POST to the same endpoint accepts period (monthly or yearly), size (1gb or 5gb; 1gb when missing) and a persistent request_id. The signed ledger debit and paid allowance commit together; retry the same request ID after an uncertain result to avoid a second charge.

After expiry, the account returns to the free allowance. Existing data remains available; uploads that grow an account above its allowance are refused, while reads and space-reducing changes remain available. Storage upgrades are opt-in on each node; nodes without them retain their configured storage-limit behavior. The Inbe Play build has no Dew purchase or storage-upgrade UI.

The Waozi node prices new premium username claims in DEW. Existing usernames remain untouched. See premium usernames for the catalog, prices, availability quotes and explicit purchase API.

Unlocks are priced by the node, never by the client. GET /api/v1/unlocks lists the account's unlocks and each product's current and regular price; POST with {"product":"inbe.practice.taichi"} debits the price once (100 Dew) and records the unlock in the same transaction. Setting MESH_UNLOCK_TRIAL_UNTIL to a Unix time sells every unlock at 90% off until then. POST /api/v1/unlocks/grant returns a one-hour download grant, signed by the Dew issuer, for a product the account has unlocked. A package artifact with a <sha256>.zx.product file beside it naming a product is gated: it is served, uncached, only at /api/v2/packages/<app>/<sha256>.zx/<grant> with an unexpired grant for that product. Legacy .zib artifacts are gated the same way.

Shovey Island (shovey.island, app entity) uses the same atomic unlock transaction at 85 Dew regular and 51 Dew at launch (40% off). Set MESH_SHOVEY_ISLAND_LAUNCH_AT once to the actual launch's Unix seconds; the server applies the offer from that instant until six calendar months later in UTC, exclusively. Zero disables the offer. Island ignores the unrelated MESH_UNLOCK_TRIAL_UNTIL setting. The public products endpoint returns its current price_units and regular_price_units; Island's trial_until remains zero, so clients market only the percentage, without a duration or countdown. Clients must POST {"product":"shovey.island","expected_units":51000000} (or the current 85000000 quote). A missing or mismatched confirmation returns 409 without a debit. Already paid accounts restore their original receipt and price even after the sale, without a second debit. Only an unlock receipt can restore Island; a generic token spend cannot grant it.

The fixed Dew price was selected using the public /api/v1/rates snapshot at Unix 1793564642: 59,226 US cents/XMR and 10,000 Dew/XMR (three agreeing sources). Thus 85 Dew was about $5.03 and 51 Dew about $3.02. These are selection-time approximations, not a USD peg or a guaranteed purchase rate. The server charges integer millionths of Dew and never uses a client price or the live USD display rate to set the debit.

An account can send Dew to a friend: POST /api/v1/tokens/gifts with the friend's recipient account ID, units (millionths of Dew) and a persistent request_id. The sender's signed debit and the friend's signed credit commit together, both with source_type gift. Only accepted friends receive gifts; a gift to oneself, above the balance or to anyone else is refused and moves nothing. Retry the same request ID after an uncertain result: it never sends twice and answers with the first result even after the friendship ends, while the same ID with another recipient or amount is refused.

People can publish collections of custom game levels for others to find and play. POST /api/v1/publications publishes one from a format (1-64 characters of a-z0-9.-), a title (1-80 bytes of text), a visibility and the document, a JSON object of at most 256 KiB that the node keeps as it is. A public publication is for everyone, friends for the author's friends, and private for the author alone. Send its id to replace one of your own; to anyone else it answers 404. An account keeps at most 100 publications, and their documents count toward its storage. GET /api/v1/publications lists the newest public ones, or with author (an alias or account ID) the ones that author lets you see; format keeps one kind. Reads need no account: without an Authorization header they see public publications only, limited per address and cacheable for 15 seconds, so a game can load its published levels for every player. GET /api/v1/publications/{id} returns a visible publication with its document, and its author removes it with DELETE. Each publication reports its levels, the length of the document's top-level levels array. An account may publish or unpublish 60 times an hour and read 120 times a minute.

GET /api/v1/rates is public and lets an app show what Dew and XMR amounts are worth in US dollars. It returns xmr_usd_cents (US cents per XMR), updated_at, the agreeing sources, and the node's fixed funding ratio xmr_atomic_units per token_units (0 when MONERO_RATE_* is unset). Every ten minutes the node reads CoinGecko, Kraken and CoinPaprika, drops a source more than 10% from the median, and keeps the median of at least two that agree; the last rate is stored, so a restart serves it at once. Without a rate newer than two hours, xmr_usd_cents and updated_at are 0 and sources is empty. The USD rate is display only: it never sets a price, a charge or a Dew credit, which all follow the fixed funding ratio.

When the node's Dew per XMR ratio changes, stop the service and run mesh rescale-dew NAME FACTOR once with the node's environment. NAME is rescale- and lowercase letters, digits or hyphens, new for each ratio change (rescale-v1 was 5 to 100 Dew per XMR, rescale-v2 1000 to 10,000). Every positive balance gains (FACTOR-1)×balance as a signed credit, so no ledger row is rewritten; uncredited Monero invoices and deposits are scaled in the same transaction, and a new checkpoint is signed. Running it again changes nothing.

The production node's ratio lives in deploy/dew-ratio.env. When a deploy finds it raised by a whole factor, deploy/apply-dew-ratio.sh stops the service, runs rescale-dew under the file's DEW_RESCALE name and writes the new ratio and the scaled MESH_TOKEN_PRODUCTS into the node environment before starting again. The file's DEW_PRODUCTS (id:Dew items) are added to MESH_TOKEN_PRODUCTS at the ratio when the node lacks them; products the node sells keep their amounts until a raise scales them. A failed deploy restores the previous binary, database and environment together.

POST /api/v1/tokens/purchases/google/verify credits a Google Play purchase of a MESH_TOKEN_PRODUCTS product once per order and then consumes it, so Play and Monero buy the same Dew. MESH_GOOGLE_PACKAGE_NAMES limits the Android apps it accepts. GET /api/v1/node lists the google-play-purchases capability while a Google Play verifier is configured. Production's package names live in deploy/node.env, and a deploy installs the service account from the optional MESH_GOOGLE_SERVICE_ACCOUNT_JSON secret.

To reward one person with Dew, for example as thanks for a past donation, stop the service and run mesh reward-dew REWARD ACCOUNT DEW with the node's environment. ACCOUNT is the person's alias (@name) or account ID. The Dew is a signed credit with REWARD:account as its payment ID, and a new checkpoint is signed. The same REWARD never credits that account twice, and reusing it with a different amount is refused. There is no command that credits every account.

The background reconciler runs whenever MONERO_WALLET_RPC_URL is configured, even with MESH_TOKEN_DIRECT_PURCHASES_ENABLED unset, so confirmed deposits keep settling while purchase creation is disabled. The deposit scan keeps a persisted height bookmark and only fetches transfers from that height onward, plus the mempool pool. Fixed-price invoices accept partial payments that accumulate across transfers until they cover the price. A payment that lands after an invoice expired is still credited by the expired-invoice sweep; partial funds on an expired invoice cannot be credited or refunded automatically from a view-only wallet, so they are reported once through the mesh_monero_stuck_invoices_total metric and a warning log for manual disposition.

The wallet RPC should open a view-only wallet, bind only to loopback, and require RPC authentication. Mesh needs the wallet-state-changing create_address method, so do not enable --restricted-rpc; the view-only wallet itself prevents spending. The full wallet, mnemonic seed, private spend key, and their backups must never be copied to the Mesh node.

Create the cold wallet and encrypted view-only deployment bundle on the trusted computer with:

MONERO_NETWORK=stagenet MONERO_RESTORE_HEIGHT=0 \
  ./scripts/create_monero_merchant_wallet.sh

The script generates independent random wallet and RPC passwords, displays the mnemonic only through the Monero CLI for offline transcription, and creates two GPG-encrypted files under secrets/monero/. The cold archive contains the spend-capable wallet. The node archive contains only the view-only wallet and its runtime credentials. For mainnet, restore the mnemonic offline and verify the primary address before deploying the view-only archive.

Each node has a persistent Ed25519 identity. By default it is stored beside the database as a mode-0600 key; production deployments should set MESH_NODE_IDENTITY_KEY_FILE explicitly or supply MESH_NODE_IDENTITY_PRIVATE_KEY_HEX_FILE. MESH_LAN_DISCOVERY=1 advertises _daochi._tcp.local with mDNS. Discovery only finds candidates: it never grants trust or starts replication.

The manual Verify origin SSH identity workflow can recover a missing deployment host pin using that identity. It verifies a fresh, domain-separated signature binding the SSH host key to the node public key obtained from the authenticated HTTPS API. A key scan alone is never trusted. The origin command only reads and signs; it does not change the service or export private keys. The resulting host pin is encrypted to the RSA public key in MESH_SSH_BOOTSTRAP_RECIPIENT, with only public proof fields saved alongside it. Verify the proof and workflow revision before installing the decrypted pin as the production environment's MESH_SSH_HOST_KEY secret. Normal deployments still require strict host-key verification and all CI/security gates.

Pairing is operator-controlled. Create a short-lived, signed invite with POST /api/v1/node/pairing/invites, transfer its JSON as text or a QR payload, and accept it on the other node with POST /api/v1/node/pairing/accept. Acceptance automatically posts a signed completion to the inviter, so one invite establishes reciprocal trust while storing directional policy from each node's perspective. The invite is single-use and fixes the peer identity, addresses, direction, apps, collections, trust spaces, and data classes. Paired requests are signed, time-bounded, and replay-protected. If MESH_ADMIN_TOKEN is configured, pairing and namespace writes require X-Mesh-Admin; without it they are limited to direct loopback callers. A request that carries a forwarding header (X-Forwarded-For, Forwarded, CF-Connecting-IP and similar), names a non-local Host, or comes from a cross-site browser Origin is refused, so a node behind a reverse proxy must set MESH_ADMIN_TOKEN to pair. Both nodes need reachable MESH_BASE_URL values during pairing.

MESH_KNOWN_NODES remains the convenient public-node/bootstrap path. It is a comma-separated peer list whose entries can be https://node.example, Name=https://node.example, or Name|https://node.example. A peer can add sync=<pull|push|bidirectional|none>, apps=inbe, collections=private.inbe.v1.*, spaces=<space-id>, and data=app_registry+encrypted_records+names. The node worker tries configured and paired peers with pull permission. MESH_NODE_SYNC_INTERVAL_SECONDS controls polling and MESH_NODE_SYNC_BATCH_LIMIT caps record pages.

The mesh replicates signed app manifests, opaque encrypted app records, deletion tombstones, and signed trust-space names. App manifests are verified against the receiving node's configured registry authority and are installed before records, so a new home or neighbor node can validate collection ownership offline. Social/account projections, payments, and opaque whole-request envelopes remain API or online-authority owned. The old shared MESH_NODE_SYNC_TOKEN is still accepted for configured-node migration, but signed pairing is the preferred trust path.

Trust-space naming is an application-level ICANN alternative, not public DNS. An operator creates a local authority with POST /api/v1/namespaces, signs names such as mesh://<space-id>/home through POST /api/v1/namespaces/claims, and resolves them with GET /api/v1/namespaces/resolve. Claims replicate to approved peers, but the authority private key does not. Different neighborhoods may intentionally resolve the same label differently; there is no global blockchain or automatic claim that browsers and the public DNS root will recognize these names.

Deletions replicate too: exports carry record tombstones in a separate deletions field, and imports apply them when the tombstone timestamp is at least as new as the stored record. Older peers that do not know the field ignore it, so mixed-version meshes keep working. Account deletion and full client re-syncs (full_sync_requested) propagate as per-record tombstones, and applying an imported delete re-logs it locally, letting a deletion travel multiple hops. A full re-sync replaces only the calling app's data: Inbe (including requests without app_id) clears the typed tables, envelopes, account-wide records and its own collections, and any other app clears only its own collections.

Records resolve by their updated_at, last writer wins. A client or peer may date a record or deletion at most five minutes ahead of the receiving node's clock; a later time is stored as that limit, so it cannot block later edits. A stored record dated beyond the limit, written before it existed, yields to the next edit.

Generate a token secret once and keep it stable across restarts and every deployed instance:

openssl rand -hex 32

If MESH_TOKEN_SECRET_HEX is missing, Mesh generates a random in-memory secret at startup. That is only suitable for single-process local development: existing bearer tokens become invalid after restart, and multi-instance deployments will reject tokens issued by another instance.

Malformed environment values abort startup with the offending key name instead of silently falling back. GET /metrics is public only while no admin token is configured; once MESH_ADMIN_TOKEN is set, scrape it with X-Mesh-Admin: <token>. The exposition includes a mesh_build_info{version=...} gauge identifying the running build when the binary was stamped via make build VERSION=<...> or the Docker/CI build args.

Encrypted envelope limits are disabled by default to avoid surprising existing clients. Set MESH_ENCRYPTED_PAYLOAD_MAX_RETURN to cap each envelope response, MESH_ENCRYPTED_PAYLOAD_MAX_ACCOUNT_BYTES to reject writes that would exceed an account quota, and MESH_ENCRYPTED_PAYLOAD_RETENTION_DAYS only after clients can tolerate older envelope pruning.

Tokens

Mesh can issue signed token receipts for registered assets. The server verifies a payment provider or admin credit, writes an append-only ledger event, and signs the receipt with the configured Ed25519 issuer key. Clients must verify the issuer key and accept only issuer and asset IDs they trust.

Self-hosted Mesh servers may use the same ledger shape for local assets later, but they cannot create receipts for an issuer without that issuer's private key. If only the issuer public key is configured, the server can expose and verify receipts but cannot credit or spend tokens.

Token ledger and payment-intent rows are financial audit records. They are scoped by account for balance and receipt lookup, but they are not included in normal account data export and are not deleted by account-data cascade.

GET /api/v1/tokens/activity serves the profile's Dew screen in every app. It returns the account's current balance plus its full activity history, newest first, across every app: deposits, purchases, spends, gifts, storage, unlocks and rewards. Each event carries its ledger seq, receipt id, event type, source and signed amount; Monero-backed credits additionally carry the paid atomic amount and the deposit's USD rate snapshot through a joined monero object. before_seq from the last returned seq pages older events, and limit caps a page (default 100, at most 500).

Token purchases, spends, invoices, receipts, and spend nonces carry app_id, and spend or purchase flows validate that the app is registered. GET /api/v1/tokens/balance and GET /api/v1/tokens/ledger stay account-wide by default for compatibility; adding ?app_id=<app> returns the app-scoped balance or ledger view for that account and asset.

Signed app manifests can publish token policies with asset_id, permission, status, and optional legacy_unsigned_until. If an app has no token policies, token endpoints keep the legacy registered-app behavior. If policies exist, spends and purchases require the matching policy, and unsigned legacy requests are accepted only until that policy's legacy_unsigned_until timestamp. The registration validator caps that unsigned grace window at 365 days.

Mesh records app-scoped token events, but it does not yet move value between separate account and app allocation pools. Treat app-filtered balances as audit views over the ledger. Explicit account-to-app allocation events are still required before calling per-app token distribution fully complete.

Signed App Registration

Nodes can accept self-contained, app-owned manifests through POST /api/v1/apps/register-signed. The request body contains:

  • manifest, including manifest_version, an optional manifest_sequence, app_id, display metadata, Ed25519 app keys, collection prefixes, capabilities, and optional token policies;
  • manifest_signature, an Ed25519 signature from one active app key over daochi-app-manifest-v1\n<canonical manifest json>;
  • approval_signature, an Ed25519 signature from the node registry key over daochi-app-approval-v1\n<app_id>\n<manifest_hash>\n.

An approved manifest stays signed after a newer one replaces it, and anyone may submit it. Give each approval a higher manifest_sequence (it sits right after manifest_version in the canonical JSON): a node then refuses, with 409, any manifest whose sequence is lower than the installed one, so an old approval cannot undo a later suspension or key revocation. Mesh peers skip such stale copies. Manifests without the field keep their previous behaviour and hash. A revoked device key ID also stays revoked; registering it again returns 409.

Each node decides which registry approval key it trusts through MESH_NODE_REGISTRY_PUBLIC_KEY_HEX or MESH_NODE_REGISTRY_PUBLIC_KEY_HEX_FILE. That keeps registration cross-platform: CLI, TUI, web, mobile, and desktop apps all submit the same signed JSON manifest, and no platform-specific package name is the root of authority.

Encrypted Hierarchy

Protocol v5 clients should put all new private app data in encrypted_records and use typed sync only as a backward-compatibility mirror. Existing released legacy encrypted collections are grandfathered.

New v5 collection names use a dotted hierarchy:

  • account.v1.manifest for the per-account hierarchy manifest;
  • private.<app>.v<version>.<collection> for encrypted private app records;
  • private.entity.v<version>.<kind> for the account's own data, such as photos or game levels, that every app of the account shares instead of keeping a copy;
  • shared.<app>.v<version>.<collection> for user-grantable cross-app records;
  • friends.<app>.v<version>.<collection> for friend-visible app records;
  • public.<app>.v<version>.<collection> for intentionally public encrypted/public-record namespaces.

The app ID in every declared collection scope must match the manifest's app_id, and the first segment must match the declared visibility. Features may reference only scopes declared in that same manifest. This prevents one app from claiming or describing another app's data.

Future private features should add or extend encrypted collections first. Existing v4 encrypted collections may continue to sync without another migration; new private namespaces should use the v5 hierarchy. Legacy typed schema additions are reserved for compatibility with older clients or for public/server-readable projections.

Reverse Proxy

Example nginx server block:

server {
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Use your normal ACME flow for TLS certificates.

Per-address rate limits trust forwarding headers only from a loopback peer. Behind Cloudflare, CF-Connecting-IP names the client; otherwise Mesh uses the last X-Forwarded-For entry, the one your proxy appended. The first entry is whatever the client sent and is never used. A proxy that does not append $remote_addr (or set CF-Connecting-IP) puts every client in one bucket.

Data Model

SQLite tables mirror the app data:

  • server_users
  • server_meditation_logs
  • server_habits
  • server_habit_days
  • server_sessions including session check-in fields such as mood, energy, stress, notes, and tags
  • server_session_rounds
  • server_friend_requests
  • server_friendships
  • server_apps
  • server_app_collections
  • server_app_capabilities
  • server_app_grants
  • server_app_grant_audit
  • server_encrypted_payloads
  • server_sync_audit
  • server_profile_stats
  • token_assets
  • token_ledger
  • token_processed_payments
  • token_spend_nonces
  • token_payment_intents
  • token_checkpoints

Deleting an account removes app sync, social, profile, and governance rows through foreign-key cascade, and its daily chat counts. Token financial audit rows are retained as described above.

S
Description
Local-first synchronization and networking between trusted nodes.
https://mesh.ziran-lang.org Readme
9.3 MiB
0 Stars 1 Watchers 0 Forks
No results found.
Languages
Go 48.2%
Ziran 44.7%
Python 4.1%
HTML 1.8%
CSS 0.5%
Other 0.6%