Skip to content

feat: add encode_members helper + fix README accuracy (#2, #3) - #17

Open
peetzweg wants to merge 3 commits into
mainfrom
feat/encode-members-and-docs
Open

feat: add encode_members helper + fix README accuracy (#2, #3)#17
peetzweg wants to merge 3 commits into
mainfrom
feat/encode-members-and-docs

Conversation

@peetzweg

@peetzweg peetzweg commented Jun 8, 2026

Copy link
Copy Markdown
Member

encode_members helper

Adds a built-in WASM function:

import { encode_members } from 'verifiablejs/nodejs'
const encodedMembers = encode_members(memberKeys) // Uint8Array[] of 32-byte keys

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 its members parameter. Previously every caller had to hand-roll the SCALE Vec<[u8; 32]> encoding or reach for @polkadot-api/substrate-bindings / @polkadot/util.

  • Decodes each element as a Member (not just byte concatenation), so the output round-trips with the existing internal decode and each key is validated.
  • Explicit 32-byte length guard → clear error instead of silent truncation.
  • Adds a round-trip test and a wrong-length negative test.

README accuracy

The published package README was stale and never mentioned the pre-flight validator the feedback specifically asks for:

  • Fixed Quick Start: domain_size 11/12/16ring_exponent 9/10/14 (the values the API actually accepts; one_shot(11, …) would have thrown).
  • Surfaced validate_with_commitment in both READMEs as the recommended local pre-flight before an on-chain submission — validate against the 768-byte ring root the chain exposes.
  • Both READMEs now point at encode_members for building the members argument, 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 in lib.rs. Removing those phantom docs is handled in a separate PR.

Verification

  • cargo check --target wasm32-unknown-unknown and cargo check --tests --target wasm32-unknown-unknown both pass.
  • dprint check clean on changed files.
  • ⚠️ The wasm-bindgen tests were not executedwasm-pack is not installed locally, so pnpm test couldn't run. The new tests type-check but should be run in CI before merge.

peetzweg added 2 commits June 8, 2026 11:25
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant