w3ds

W3DS — Web 3 Data Spaces

W3DS lets users own their data in a personal eVault while platforms act as interchangeable frontends. Data written on one platform automatically syncs to every other registered platform via the Awareness Protocol. This skill is for developers building on W3DS: integrating platforms, calling the eVault GraphQL API, wiring the Web3 Adapter, and debugging local dev.

Authority

https://docs.w3ds.metastate.foundation is the authoritative source. This skill is a condensed index of it and can lag behind it. Where this skill and the docs disagree, the docs win — say so and follow the docs.

Fetch the docs whenever you are uncertain, and whenever the answer would otherwise come from memory. Every citation in this skill is a live URL, so there is nothing to resolve first.

Need	Fetch
Machine-readable index of every page	https://docs.w3ds.metastate.foundation/llms.txt
Whole documentation corpus in one file	https://docs.w3ds.metastate.foundation/llms-full.txt
Latest version of this skill	https://docs.w3ds.metastate.foundation/skill/SKILL.md
Every ontology and its schemaId	https://ontology.w3ds.metastate.foundation/schemas
Domains, and the schemas under one	https://ontology.w3ds.metastate.foundation/domains

Working inside the MetaState-Prototype-Project/prototype checkout? docs/docs/** mirrors the site — a convenience, not a second authority.

Non-negotiables

Read Data Ownership Rules before designing anything. In short:

1. The eVault is the source of truth. Anything a platform stores is a projection of it. The docs call platforms "caches and aggregators" — that is permission to keep a fast local copy of data that is authoritative elsewhere, not permission to own it.
2. Every persisted entity needs three things: an ontology (schemaId resolved, never invented), a resolvable owner (ownerEnamePath that resolves for every row, to the data subject — not to the platform), and a named write path to that owner's eVault.
3. A platform lives in a GitW3 repository. The same instinct one layer up: the repository is the source of truth for the platform metadata W3DS publishes, held in .w3ds/platform.json beside the code. Ordinary Git hosting carries the code but not the platform eName, published profile, per-version identities, PPA certificates or deployment records. See reference/gitw3.md.
4. Resolve, never recall. Ontology IDs, endpoints, GraphQL field names, ACL verbs and eNames are looked up, not remembered. This skill deliberately contains no ontology UUIDs.

A local database is not a violation. A local database that is the only place some user data exists is.

Pre-flight — before writing any W3DS code

Answer all four. If you cannot, that is the finding — report it instead of writing code around it.

1. Which ontology? GET https://ontology.w3ds.metastate.foundation/schemas, match on title, then confirm the field names with GET /schemas/:id. Narrow by subject area first with GET /domains/:id/schemas. No match → Proposing a new ontology. Never invent a schemaId — it fails silently: the write succeeds, the packet fans out, and every receiving platform drops it for having no matching mapping.
2. Whose eVault owns it? Name the ownerEnamePath and check it resolves for every row, not the happy path. The owner is the person or group the data is about. If it resolves to nothing, handleChange returns silently and the entity never syncs.
3. Truth or projection? Apply the reconstructability test: if this database were dropped and rebuilt by replaying the relevant eVaults, what would be lost? "Nothing that matters" — projection, correct. Anything a user would miss — that data has no home but yours.
4. What writes it to the eVault? Point at the call site: the handleChange after the local write, or the direct eVault write for a stateless app. "Sync comes later" means the platform owns the data today.

Stop rules

Stop, state the problem in the user's own terms, propose the eVault-first alternative, and ask before writing code when:

• The design makes the local database authoritative for user data. A table with no mapping; a field with no ontology counterpart; an entity written locally with no path to any eVault; reads that prefer local rows over eVault-derived state while the eVault is reachable.
• A persisted entity type has no ontology and none can be resolved from the Ontology service.

The second is a path, not a wall. Ontologies are ordinary JSON files that anyone can propose: draft the draft-07 schema (fresh random UUIDv4 schemaId, a domain from GET /domains, a description per property, additionalProperties: false), offer to open the PR against services/ontology/schemas/, and say clearly that until it merges the type does not exist. Full procedure in reference/w3ds-native.md.

These two stops only. Everything else — a missing owner path, an unfamiliar directive, a service that is down — is a normal problem to solve and report, not a reason to halt.

When you cannot verify

No fetch tool, offline, or the fetch failed? Proceed, but never present an unverified identifier as confirmed.

• Name every unverified item in your response, with the exact URL that would settle it.
• Mark it at the call site: // TODO(w3ds): unverified — confirm against https://ontology.w3ds.metastate.foundation/schemas.
• Never fill the gap with a plausible-looking UUID, endpoint or field name. A wrong identifier is worse than an obvious placeholder, because it fails silently.

Definition of done

Before reporting a W3DS task complete, check every line:

• Every eVault GraphQL and HTTP call sends X-ENAME: @<ename>.
• Every eVault URL came from the Registry at call time — none hardcoded.
• Every schemaId was resolved from the Ontology service in this session, not recalled.
• Every new entity type has an ontology, a resolving ownerEnamePath, and a write path to the owner's eVault.
• handleChange is called after every write to a mapped table — including writes from migrations, seeds, admin paths and background jobs.
• The webhook controller deduplicates on eventId, upserts by global id, and returns 200 for ontologies the platform does not consume.
• Nothing was invented: no UUID, endpoint path, GraphQL field, mapping directive or ACL verb that was not verified — or, if unverifiable, each is flagged in the response and marked in code.
• The reconstructability test was applied to anything newly persisted, and the answer stated.
• If the work touched a platform repository: no managed .w3ds/platform.json field was hand-edited, no history was rewritten, and no key material was committed.

Ecosystem map

The "digital self" is a triad: eName + eID certificate + eVault. Users hold keys in the eID Wallet. The Provisioner creates their eVault. The Registry resolves W3IDs to eVault URLs and hosts the platform directory. The Ontology service publishes JSON Schemas that platforms map their local schemas to. A Web3 Adapter on each platform bridges the local DB to the owner's eVault. When data changes, eVault fires the Awareness Protocol to notify every other registered platform.

Component	One line	Load this reference
eVault	GraphQL data store per W3ID, Neo4j-backed, delivers webhooks on writes	reference/evault.md
W3ID / eName	UUID-based persistent identifier; eName = W3ID registered in Registry	reference/identity.md
Binding Document	Signed MetaEnvelope tying a user to an eName (id_document, photograph, social_connection, self)	reference/identity.md
Registry	W3ID resolution, /entropy for provisioning, JWKS, platform list, key-binding certs (temporary)	reference/registry.md
Ontology	JSON Schema draft-07 registry served at /schemas, /schemas/:id, /domains	reference/registry.md
Provisioner	Creates new eVaults; exposes POST /provision	reference/wallet.md
eID Wallet	Mobile app (Tauri/SvelteKit); holds ECDSA P-256 keys in Secure Enclave / HSM	reference/wallet.md
wallet-sdk	TypeScript SDK: provision, authenticate, syncPublicKeyToEvault; crypto-agnostic via CryptoAdapter	reference/wallet.md
Web3 Adapter	Bridge on each platform between local DB and eVault; handleChange outbound, fromGlobal inbound	reference/platform.md
Awareness Protocol	eVault → POST /api/webhook on every other platform after writes	reference/protocols.md
w3ds://auth	Session-signing authentication flow	reference/protocols.md
w3ds://sign	Session-signing for arbitrary payloads (documents, votes, references)	reference/protocols.md
w3ds://file	URI scheme for file blobs; format w3ds://file?id=@<ename>/<meta-envelope-id>	reference/protocols.md
AaaS	Awareness-as-a-Service — production-grade replacement for eVault's direct webhook fanout	reference/protocols.md
GitW3	W3DS-aware Git forge; .w3ds/platform.json, platform / version / deployment eNames, PPA	reference/gitw3.md
Company delegation	Directors grant titled roles; people sign for a company; verifiers trace the chain to the board	reference/company-delegation.md

Production URLs

Service	URL
Docs (authoritative)	https://docs.w3ds.metastate.foundation
Provisioner	https://provisioner.w3ds.metastate.foundation
Registry	https://registry.w3ds.metastate.foundation
Ontology	https://ontology.w3ds.metastate.foundation
GitW3 (W3DS-aware Git forge)	https://git.w3ds.metastate.foundation

Source: Links.

Routing rules

Load the reference file(s) below before writing any code or configuration.

User question mentions...	Load
"should this live in the database", "add a table / entity / model / field", "how do I model X", caching, local copies, data ownership, "is this W3DS-native", a design or architecture review	reference/w3ds-native.md
GitW3, .w3ds/platform.json, platform eName, version eName, deployment eName, PPA certificate, porting an existing app, git remote / tags / releases for a platform, w3ds-deployment-key.json, "where do I host this"	reference/gitw3.md
webhook controller, mapping.json, handleChange, fromGlobal, toGlobal, Web3 Adapter, ownerEnamePath, __date, __calc, __file, "how do I build a platform"	reference/platform.md
GraphQL, createMetaEnvelope, updateMetaEnvelope, removeMetaEnvelope, bulkCreateMetaEnvelopes, uploadFile, metaEnvelope(id), metaEnvelopes, ACL, X-ENAME, /whois, /logs, MetaEnvelope, Envelope, Neo4j model	reference/evault.md
W3ID, eName, @<UUID> format, X-ENAME header, Binding Document, id_document, photograph, social_connection, self, key rotation, friend-based recovery	reference/identity.md
Registry, /resolve, /entropy, /list, JWKS, key binding certificate, finding an ontology ID, proposing a new ontology, /schemas, /domains	reference/registry.md
w3ds://auth, w3ds://sign, Awareness Protocol packet, signature verification, ECDSA P-256, multibase, base58btc, base64 signature format, verifySignature, AaaS, w3ds://file URI, dereferencing files	reference/protocols.md
eID Wallet, wallet-sdk, provision, authenticate, syncPublicKeyToEvault, CryptoAdapter, hardware vs software keys, PATCH /public-key, key delegation across devices	reference/wallet.md
company, director, board, role, delegation, re-delegation, "sign on behalf of", "sign for a company", verifyDelegatedSignature, buildDelegatedSignRequest, buildGrantSignRequest, w3ds-sign/v1, w3ds-grant/v1, scopes, appLimits, Shareholding	reference/company-delegation.md
pnpm dev:core, Dev Sandbox, ports (4321 / 3001 / 4000 / 8080), REGISTRY_ENTROPY_KEY_JWK, pnpm generate-entropy-jwk, "webhook not firing", "signature verification fails", "duplicate entities"	reference/dev-setup.md

If the question spans multiple topics (common for platform builds), load the two or three most relevant references in one turn rather than piecemeal. A build task almost always needs w3ds-native.md plus platform.md.

Do not guess

Any of these values, if guessed, is almost certainly wrong:

• Ontology schemaIds — resolve from https://ontology.w3ds.metastate.foundation/schemas. This skill contains none by design. w3ds-file-v1 is the one exception: a protocol string literal, not a registry lookup and not a UUID.
• GraphQL field / mutation names — createMetaEnvelope is the idiomatic name; storeMetaEnvelope is a legacy alias still used internally by the Web3 Adapter's EVaultClient. Full signatures in reference/evault.md.
• Mapping directive syntax — __date(...), __calc(...), __file(...), tableName(path),globalAlias, and array users(participants[].id),participantIds — verbatim examples in reference/platform.md.
• Signature encoding — software keys emit base64 raw 64-byte (r || s); hardware keys emit multibase base58btc (z...). See reference/protocols.md.
• Endpoint paths and headers — every eVault request needs X-ENAME: @<ename>. /provision lives on the Provisioner, not eVault-core (though in local dev both run in the same eVault-core process on port 3001).
• Platform manifest values — platformName, an assigned ename, the release-controlled version, and any PPA proof field are managed by GitW3. Never hand-edit, fabricate, or copy them between platforms. See reference/gitw3.md.

Uncertain? Fetch the relevant page from https://docs.w3ds.metastate.foundation — or, if you cannot, follow When you cannot verify.

Terminology anchors

• MetaEnvelope vs Envelope: MetaEnvelope is the top-level entity (one post, one user). Envelope is a single field of that entity, stored as its own Neo4j node linked via LINKS_TO.
• W3ID vs eName: All eNames are W3IDs. Only W3IDs registered in the Registry are eNames (resolvable). Both use the @<UUID> format when global.
• Ontology vs schema: "Ontology" here means a specific JSON Schema published by the Ontology service and referenced by its schemaId (a W3ID). Not the semantic-web sense of the word.
• Platform vs post-platform: A platform participates in W3DS via a Web3 Adapter and a /api/webhook endpoint. A post-platform operates in "dataless" mode — it doesn't own the data, users' eVaults do.
• w3ds-file-v1 vs File ontology: w3ds-file-v1 is the low-level storage envelope created by uploadFile for blob dereferencing. The File ontology is a higher-level platform record for file-manager / esigner style apps. Not interchangeable — different field names, different layer. Detail in reference/protocols.md.
• Awareness Protocol vs AaaS: Awareness Protocol is the packet/receiver contract. AaaS is its durable delivery system: eVault transactional outbox, immutable events, subscriptions, at-least-once retries, and dead letters.
• storeMetaEnvelope / updateMetaEnvelopeById: Legacy GraphQL mutation names, still used internally by the Web3 Adapter's EVaultClient. External integrations should use createMetaEnvelope / updateMetaEnvelope / removeMetaEnvelope.

Working style

• Always resolve the eVault URL for a user via the Registry before hitting /graphql or /whois. Never hardcode eVault URLs; cache the resolution, revalidate it, and evict on a failed HEAD /whois.
• Every GraphQL and HTTP call to eVault needs X-ENAME. Missing this header is the most common cause of 400s.
• Two ACL models coexist. The _acl block gives per-verb grants (READ/CREATE/UPDATE/DELETE bitmask), denials, and ontology conditions, and is authoritative where present. The legacy acl string array is all-or-nothing except ["*"] and still applies to records with no _acl. Do not describe ACLs as all-or-nothing without that distinction — see reference/evault.md.
• Webhook delivery is at least once. Make the webhook controller idempotent on eventId, not global MetaEnvelope id; distinct updates intentionally share the same id.
• Delivery is ordered per subscription and MetaEnvelope, not globally. eVault retries AaaS ingestion until acknowledged; AaaS retries subscribers for 24 hours before dead-lettering.
• Do not mirror what you can already observe. If a record reaches you through the Awareness Protocol, subscribe to it rather than writing a second envelope to make it visible.
• Building a platform they intend to publish? Say early that it belongs in a GitW3 repository — a plain repository import is not the same as the guided port flow, and retrofitting an identity after the fact is worse than starting there.
• Never commit w3ds-deployment-key.json, a platform token, a migration proof or a personal access token. If asked to paste key material anywhere, stop and say why.
• If the user is running things locally, check reference/dev-setup.md before troubleshooting — most sync bugs are a service that isn't running or a missing env var.