docs: add docs for w3id, w3 adapter and awareness protocol #745
Conversation
📝 WalkthroughWalkthroughAdds three new documentation pages: Web3 Adapter design, W3ID/eName identity guide, and Awareness Protocol webhook specification. All changes are documentation-only; no code or public API entities were modified. Changes
Sequence Diagram(s)(omitted) Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/docs/Infrastructure/Web3-Adapter.md`:
- Line 115: Remove the duplicate reference to the mapping rules by deleting the
second mention of "Web3 Adapter Mapping Rules" that points to
`infrastructure/web3-adapter/MAPPING_RULES.md` (the one around line 125),
leaving the initial reference (the one that mentions mapping configs and
`__date`, `__calc`, owner path) intact so the docs only point once to the
MAPPING_RULES.md file.
🧹 Nitpick comments (2)
docs/docs/Infrastructure/Web3-Adapter.md (2)
21-21: Consider consolidating redundant reassurances.The documentation mentions twice that ID mapping is handled automatically by the TypeScript implementation (lines 21 and 38). Consider consolidating these statements or removing one to improve conciseness.
✂️ Suggested consolidation
Option 1: Keep only the first mention (line 21) and remove the parenthetical note on line 38.
Option 2: Move both reassurances to a single "Implementation Notes" callout that applies to the entire ID mapping discussion.
Also applies to: 38-38
103-103: Clarify "fire-and-forget" update behavior.The documentation states that updates are "fire-and-forget," meaning the adapter doesn't wait for confirmation. This could lead to silent failures if the eVault update fails.
Consider either:
- Adding retry logic or error handling for update operations
- Clarifying in the documentation what happens when updates fail and how platforms should monitor for failures
- Explaining why fire-and-forget is acceptable in this context (e.g., eventual consistency model, idempotent updates, monitoring elsewhere)
coodos
force-pushed
the
docs/w3id-w3adapter-and-awareness-docs
branch
from
dc2e5b8 to
6b05e3b
Compare
coodos
force-pushed
the
docs/w3id-w3adapter-and-awareness-docs
branch
from
6b05e3b to
6859d8e
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Around line 28-29: The text for storeMetaEnvelope contradicts the token
behavior; update the documentation for storeMetaEnvelope and
updateMetaEnvelopeById to explicitly state why a 3-second delay is used: either
(A) the Bearer token includes a platform claim but the platform's webhook URL
may require an asynchronous lookup/registration propagation (so the URL might
not be resolvable instantly), or (B) the delay is solely to avoid webhook
ping-pong even when the platform URL is known; pick the correct rationale,
remove the contradictory sentence about the token not identifying the requester,
and clearly note that updateMetaEnvelopeById sends webhooks immediately
(fire-and-forget). Reference storeMetaEnvelope, updateMetaEnvelopeById,
MetaEnvelope, eVault, and the Bearer token platform claim when making the
clarification.
🧹 Nitpick comments (5)
docs/docs/W3DS Protocol/Awareness-Protocol.md (5)
57-57: Clarify what "normalized" URL comparison means.The statement "URL comparison is normalized so that equivalent URLs are treated as the same" would benefit from a brief explanation. Does normalization handle trailing slashes, protocol differences (http vs https), port numbers, case sensitivity, etc.?
Adding a sentence or example would help implementors understand exactly how platform URLs are matched for exclusion.
64-70: Optional: Fix table formatting for markdown linting.The table has minor spacing inconsistencies around the pipes. For strict markdown compliance, add spaces around pipes on the separator row.
📝 Proposed formatting fix
| Field | Description | -|-------|-------------| +| ----- | ----------- | | `id` | Global MetaEnvelope ID (UUID). |
100-100: Optional: Consider using natural spaces in documentation link.The link uses URL encoding (
%20) for spaces, which is technically correct but less readable in the source. Most documentation systems handle spaces automatically, so you could use natural spaces for better readability.📝 Suggested alternative
-For a step-by-step implementation guide, see the [Webhook Controller Guide](/docs/Post%20Platform%20Guide/webhook-controller) in the Post Platform Guide. +For a step-by-step implementation guide, see the [Webhook Controller Guide](/docs/Post Platform Guide/webhook-controller) in the Post Platform Guide.Note: Only apply this if your documentation system handles spaces in paths correctly.
104-104: Minor style improvement: use "will" instead of "going to".For more formal technical documentation, consider using "will" instead of "going to" when describing planned improvements.
✏️ Suggested revision
-The current protocol has limitations which are going to be improved in subsequent versions: +The current protocol has limitations which will be improved in subsequent versions:(Also fixes the double space before "limitations")
109-109: Add hyphen to compound adjective.When "prototype level" modifies a noun, it should be hyphenated as "prototype-level" for correct grammar.
✏️ Suggested revision
-- **Platform list from Registry**: The set of recipients is whatever the Registry returns for `GET /platforms`. This is a prototype level shortcut and will be phased out. +- **Platform list from Registry**: The set of recipients is whatever the Registry returns for `GET /platforms`. This is a prototype-level shortcut and will be phased out.(Also fixes the double space after the first sentence)
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Around line 104-109: Update the wording in the "limitations" paragraph and
bullets: change "which are going to be improved in subsequent versions" to
"which will be improved in subsequent versions"; hyphenate "prototype level" to
"prototype-level" in the "Platform list from Registry" bullet; and tighten
bullet phrasing for clarity (e.g., "No ordering guarantee" → "No ordering
guarantees", "No at-least-once guarantee" → "No at-least-once delivery
guarantee") while keeping the same meaning.
- Around line 64-66: The markdown table header row spacing is inconsistent and
triggers MD060; edit the header and separator rows (the lines containing the
column names and the ---- separator) to normalize pipe spacing so each pipe has
a single space on either side (e.g., "| Field | Description |") and ensure the
separator row matches the same pipe positions; adjust the `id` row if needed to
align with the header formatting so all columns are consistently spaced.
|
|
||
| Platforms keep their own schemas and databases. To participate in W3DS, they need a component that: | ||
|
|
||
| - **Outbound**: Detects local changes, maps local data to the global ontology, resolves the owner's eVault (via the user's [eName](/docs/W3DS%20Basics/W3ID) / Registry), and writes to the eVault (GraphQL). |
There was a problem hiding this comment.
owner and/or target evault, I guess?
| - **Outbound**: Detects local changes, maps local data to the global ontology, resolves the owner's eVault (via the user's [eName](/docs/W3DS%20Basics/W3ID) / Registry), and writes to the eVault (GraphQL). | ||
| - **Inbound**: Receives awareness protocol packets at `POST /api/webhook`, maps global data to the local schema, and creates or updates local entities while maintaining global-ID-to-local-ID mappings. | ||
|
|
||
| The Web3 Adapter implements this bridge. Understanding its core ideas helps you design better ontologies, mappings, and consistency strategies. |
There was a problem hiding this comment.
maybe worth explaining the scope of this bridge. E.g., it will not come pre-assembled with all the hooks to your favorite database perhaps
| Platforms keep their own schemas and databases. To participate in W3DS, they need a component that: | ||
|
|
||
| - **Outbound**: Detects local changes, maps local data to the global ontology, resolves the owner's eVault (via the user's [eName](/docs/W3DS%20Basics/W3ID) / Registry), and writes to the eVault (GraphQL). | ||
| - **Inbound**: Receives awareness protocol packets at `POST /api/webhook`, maps global data to the local schema, and creates or updates local entities while maintaining global-ID-to-local-ID mappings. |
There was a problem hiding this comment.
[a] can we cross reference the awareness doc. here? you did it below in some place
[b] should we say that both are not strictly immedate -- it can take time for the data to sync. both ways
|
|
||
| ### 1. Universal ontology as the common language | ||
|
|
||
| All platforms agree on a small set of global schemas (e.g. User, Post, Group) identified by UUIDs. Each platform maps its local tables to these schemas. The ontology is the contract: if you store data in that shape in an eVault, other platforms can interpret it via their own mappings. Better ontology design (versioning, optional fields, extensibility) leads to easier evolution and fewer breaking changes. |
There was a problem hiding this comment.
where do we get the mapping from uuid to schema -- link here. Also, if it is uuid, why not already consider it w3id?
|
|
||
| # Web3 Adapter | ||
|
|
||
| The Web3 Adapter is the bridge between a platform's local database and eVault. It enables "write once, sync everywhere": when data changes locally, the adapter converts it to the global schema and stores it in the owner's eVault; when awareness protocol packets arrive from other platforms, the adapter converts them back to the local schema and applies them locally. |
There was a problem hiding this comment.
maybe we can also say that you don't have to use it. For example, if you don't have a database or can't access it for sync.
|
|
||
| | Field | Description | | ||
| |-------|-------------| | ||
| | `id` | Global MetaEnvelope ID (UUID). | |
There was a problem hiding this comment.
is it not w3id too, just not an ename? perhaps at least call it mid?
| | Field | Description | | ||
| |-------|-------------| | ||
| | `id` | Global MetaEnvelope ID (UUID). | | ||
| | `w3id` | Owner eName (eVault owner W3ID). | |
| | `id` | Global MetaEnvelope ID (UUID). | | ||
| | `w3id` | Owner eName (eVault owner W3ID). | | ||
| | `schemaId` | Ontology/schema UUID (identifies the type of entity and which mapping the platform should use). | | ||
| | `data` | The entity payload in the **global ontology** shape (parsed key-value structure). | |
There was a problem hiding this comment.
I think we should stress the fact that the whole pauload is sent to every platform in the world in plain text -- people may have concernse about security and about bandwisth.
We are already dealing with multi-megabyte blob updates
| | `w3id` | Owner eName (eVault owner W3ID). | | ||
| | `schemaId` | Ontology/schema UUID (identifies the type of entity and which mapping the platform should use). | | ||
| | `data` | The entity payload in the **global ontology** shape (parsed key-value structure). | | ||
| | `evaultPublicKey` | Optional; eVault public key. | |
There was a problem hiding this comment.
is this a raw key, or as Alex likes JWT (he really likes x.509, but w.e.)?
|
|
||
| - **Method and path**: `POST /api/webhook` | ||
| - **Request**: JSON body as described above. | ||
| - **Behavior**: The platform should (1) use `schemaId` to find the correct mapping from global ontology to local schema, (2) transform `data` from global to local format (e.g. using the Web3 Adapter's `fromGlobal`), (3) resolve or create the local entity and store the global-ID-to-local-ID mapping, (4) return HTTP 200 on success. |
There was a problem hiding this comment.
where are the global onotologies located?
There was a problem hiding this comment.
we are making a frontend which we will host at ontology.w3ds.metatate.foundation, I am skipping addressing this atm, it will be ~1 day before we have it up.
…etaState-Prototype-Project/prototype into docs/w3id-w3adapter-and-awareness-docs
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Line 71: Fix the typo in the sentence containing "entitre" by replacing it
with "entire" so the sentence reads "In the current version of the
implementation the entire payload is sent in"; locate the occurrence of the
misspelled word "entitre" in the Awareness-Protocol.md content and update it to
"entire".
🧹 Nitpick comments (1)
docs/docs/W3DS Protocol/Awareness-Protocol.md (1)
71-76: Consider improving paragraph readability.This paragraph is a single long run-on sentence. Consider breaking it into multiple sentences for better clarity and readability.
♻️ Suggested improvement
-In the current version of the implementation the entitre payload is sent in -plain text to any registered platform, so all data is sent to every platform and -it's the platform's responsibility to reject any packets it doesn't use, in -future versions of awareness protocol, it will be changed so that platforms can -subscribe to certain ontology changes and they will be provided details of the -updated MetaEnvelope by reference instead of value. +In the current version of the implementation, the entire payload is sent in +plain text to any registered platform. All data is sent to every platform, and +it is the platform's responsibility to reject any packets it doesn't use. In +future versions of the awareness protocol, it will be changed so that platforms can +subscribe to certain ontology changes, and they will be provided details of the +updated MetaEnvelope by reference instead of by value.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Line 11: The sentence contains a subject–verb agreement error: change the
phrase "every registered platforms" to the singular "every registered platform"
in the sentence that starts "When data in an eVault changes (create or update),
the eVault notifies every registered platforms so they can stay in sync." Update
that exact phrase to "every registered platform" to fix the agreement while
preserving the rest of the sentence.
- Line 28: Update the sentence in the Awareness-Protocol doc referring to the
storeMetaEnvelope (create) behavior: change the compound phrase "write back" to
the hyphenated form "write-back" so it reads "...preventing the same platform
from receiving its own write-back and creating a feedback loop..."; ensure the
change is applied in the line describing the MetaEnvelope storage in the eVault.
| The Awareness Protocol described here is **prototype-level**. The packet format, delivery behavior, and platform contract are subject to change in upcoming updates | ||
| ::: | ||
|
|
||
| The Awareness Protocol is the webhook delivery mechanism in W3DS. When data in an eVault changes (create or update), the eVault notifies every registered platforms so they can stay in sync. "Awareness" means platforms become aware of changes that happened elsewhere. |
There was a problem hiding this comment.
Fix subject–verb agreement.
“every registered platforms” should be singular.
✏️ Suggested tweak
-The Awareness Protocol is the webhook delivery mechanism in W3DS. When data in an eVault changes (create or update), the eVault notifies every registered platforms so they can stay in sync.
+The Awareness Protocol is the webhook delivery mechanism in W3DS. When data in an eVault changes (create or update), the eVault notifies every registered platform so they can stay in sync.🤖 Prompt for AI Agents
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md at line 11, The sentence
contains a subject–verb agreement error: change the phrase "every registered
platforms" to the singular "every registered platform" in the sentence that
starts "When data in an eVault changes (create or update), the eVault notifies
every registered platforms so they can stay in sync." Update that exact phrase
to "every registered platform" to fix the agreement while preserving the rest of
the sentence.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Around line 71-76: The paragraph describing how payloads are sent is a long
run-on sentence; split it into 2–3 clear sentences: one stating that the current
implementation sends the entire payload in plain text to all registered
platforms and that platforms must ignore packets they don't use, another stating
that future protocol versions will allow platforms to subscribe to ontology
changes, and a final short sentence noting updated MetaEnvelope details will be
provided by reference instead of by value (keep mentions of "awareness protocol"
and "MetaEnvelope" so readers can locate related text).
| In the current version of the implementation the entire payload is sent in | ||
| plain text to any registered platform, so all data is sent to every platform and | ||
| it's the platform's responsibility to reject any packets it doesn't use, in | ||
| future versions of awareness protocol, it will be changed so that platforms can | ||
| subscribe to certain ontology changes and they will be provided details of the | ||
| updated MetaEnvelope by reference instead of value. |
There was a problem hiding this comment.
Split the run-on sentence for clarity.
This block is a long, comma-spliced sentence and is hard to parse.
✏️ Suggested rewrite
-In the current version of the implementation the entire payload is sent in
-plain text to any registered platform, so all data is sent to every platform and
-it's the platform's responsibility to reject any packets it doesn't use, in
-future versions of awareness protocol, it will be changed so that platforms can
-subscribe to certain ontology changes and they will be provided details of the
-updated MetaEnvelope by reference instead of value.
+In the current version of the implementation, the entire payload is sent in
+plain text to any registered platform. As a result, all data is sent to every
+platform, and it is the platform’s responsibility to reject any packets it
+doesn’t use. In future versions of the Awareness Protocol, platforms will be
+able to subscribe to specific ontology changes and receive updated MetaEnvelope
+details by reference instead of value.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| In the current version of the implementation the entire payload is sent in | |
| plain text to any registered platform, so all data is sent to every platform and | |
| it's the platform's responsibility to reject any packets it doesn't use, in | |
| future versions of awareness protocol, it will be changed so that platforms can | |
| subscribe to certain ontology changes and they will be provided details of the | |
| updated MetaEnvelope by reference instead of value. | |
| In the current version of the implementation, the entire payload is sent in | |
| plain text to any registered platform. As a result, all data is sent to every | |
| platform, and it is the platform's responsibility to reject any packets it | |
| doesn't use. In future versions of the Awareness Protocol, platforms will be | |
| able to subscribe to specific ontology changes and receive updated MetaEnvelope | |
| details by reference instead of value. |
🤖 Prompt for AI Agents
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md around lines 71 - 76, The
paragraph describing how payloads are sent is a long run-on sentence; split it
into 2–3 clear sentences: one stating that the current implementation sends the
entire payload in plain text to all registered platforms and that platforms must
ignore packets they don't use, another stating that future protocol versions
will allow platforms to subscribe to ontology changes, and a final short
sentence noting updated MetaEnvelope details will be provided by reference
instead of by value (keep mentions of "awareness protocol" and "MetaEnvelope" so
readers can locate related text).
Description of change
Add docs for W3ID, Web 3 Adapter, Awareness Protocol
Issue Number
Type of change
How the change has been tested
Change checklist
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.