feat: add encode_members helper + fix README accuracy (#2, #3) - #17
Open
peetzweg wants to merge 3 commits into
Open
feat: add encode_members helper + fix README accuracy (#2, #3)#17peetzweg wants to merge 3 commits into
peetzweg wants to merge 3 commits into
Conversation
Implements feedback items #2 and #3 from web3-citizenship-web's library-feedback.md. #2 — add `encode_members(members: Uint8Array[]): Uint8Array`, a built-in WASM helper that SCALE-encodes 32-byte member keys into the `Vec<Member>` shape every ring function expects, so callers no longer hand-roll the encoding or import a separate codec. Validates each element is exactly 32 bytes and a valid member key. Adds round-trip + negative tests. #3 — README accuracy: - Fix Quick Start: `domain_size` 11/12/16 → `ring_exponent` 9/10/14 (the values the API actually accepts). - Surface `validate_with_commitment` as the recommended local pre-flight before an on-chain submission, in both READMEs. - Point both READMEs at `encode_members` for building the `members` argument; keep the hand-rolled encoding only as a no-WASM fallback. Phantom multi-context docs are intentionally left for a separate PR.
The READMEs documented `create_multi_context`, `validate_multi_context`, `is_valid_multi_context`, and `MultiContextResult` as public API, but none of these are implemented in lib.rs — only a test named `test_multi_context_aliases_are_unlinkable` exists (it exercises `alias_in_context`). Documenting a non-existent API misleads consumers. Removes the TOC entry, concept section, full API-reference section, the orphaned "Encoding Contexts" helper, the @polkadot/types contexts example (repurposed to members), and the `MultiContextResult` type. Also drops the three phantom rows from the package README's API table.
docs: remove phantom multi-context proof API
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
encode_membershelperAdds a built-in WASM function:
It SCALE-encodes an array of 32-byte member public keys into the
Vec<Member>shape that every ring function (one_shot,validate,is_valid,batch_validate,members_root,members_intermediate) expects for itsmembersparameter. Previously every caller had to hand-roll the SCALEVec<[u8; 32]>encoding or reach for@polkadot-api/substrate-bindings/@polkadot/util.Member(not just byte concatenation), so the output round-trips with the existing internal decode and each key is validated.README accuracy
The published package README was stale and never mentioned the pre-flight validator the feedback specifically asks for:
domain_size11/12/16→ring_exponent9/10/14(the values the API actually accepts;one_shot(11, …)would have thrown).validate_with_commitmentin both READMEs as the recommended local pre-flight before an on-chain submission — validate against the 768-byte ring root the chain exposes.encode_membersfor building themembersargument, keeping the hand-rolled encoding only as a no-WASM fallback.Out of scope (follow-up PR)
The root README also documents
create_multi_context/validate_multi_context/is_valid_multi_context/MultiContextResult, which do not exist inlib.rs. Removing those phantom docs is handled in a separate PR.Verification
cargo check --target wasm32-unknown-unknownandcargo check --tests --target wasm32-unknown-unknownboth pass.dprint checkclean on changed files.wasm-packis not installed locally, sopnpm testcouldn't run. The new tests type-check but should be run in CI before merge.