Skip to content

RFC: Redesign RingLocation in host_account_create_proof#18

Open
filvecchiato wants to merge 11 commits into
mainfrom
rfc/0004-ringlocation-redesign
Open

RFC: Redesign RingLocation in host_account_create_proof#18
filvecchiato wants to merge 11 commits into
mainfrom
rfc/0004-ringlocation-redesign

Conversation

@filvecchiato

@filvecchiato filvecchiato commented Apr 23, 2026 •
edited by valentunn
Loading

Copy link
Copy Markdown
Collaborator

RFC: Redesign RingLocation in host_account_create_proof

Summary

Redesigns the RingLocation parameter in host_account_create_proof to better support the evolving ring membership model.

Checklist

  • Added docs/rfcs/0004-ringlocation-redesign.md with completed frontmatter
  • Filled all RFC sections (Summary, Motivation, Detailed Design, Drawbacks, Alternatives, Unresolved Questions)
  • Updated docs/rfcs/_index.md with a link to the new RFC
  • Added labels: rfc, proposal

Motivation

The current RingLocation design does not adequately support the proof-of-personhood ring membership model. Migrated from paritytech/triangle-js-sdks#81.

Rendered

29-06-26 changes

  1. Enriched the proof response — added contextual_alias, ring_index, and ring_revision to RingVrfProof.
  2. Introduced ProductProofContext — replaced the confusing domain: ProductAccountId with an explicit product-scoped context + product_context_bytes derivation.
  3. Specified host member-key selection — PoP-collection definition and the MUST rules; flagged explicit member-key management as out of scope for a future RFC.
  4. Adjusted get_alias — now takes (ProductProofContext, RingLocation) so its alias matches create_proof.
  5. Added the NotMember error — distinguishes "not yet a member" from "ring not found".
  6. Made RingLocation a struct with required chain_id — removed the Chain junction so the chain is mandatory at the type level.

30-06-26 changes

Include Accounts Protocol companion

@filvecchiato
Move ring_index from input to output, address review feedback
c41d057 
Incorporate feedback from triangle-js-sdks#81 (@Zebedeusz):

- Remove RingIndex from RingLocationJunction (no longer an input)
- Add ring_index and ring_revision (non-optional) to RingVrfProof so
  products can pass them to downstream precompiles (e.g.
  personhoodInfoByProof from individuality#891) without extra queries
- Add "Abstraction-friendly" rationale addressing whether products
  should need to know ring location details at all
- Add unresolved question about a well-known default RingLocation
- Reference individuality#878, #891, and the original review thread
@filvecchiato filvecchiato mentioned this pull request May 7, 2026
Closed
4 tasks
pgherveou added a commit that referenced this pull request May 17, 2026
@pgherveou
feat(truapi-codegen): emit TS HostCallbacks interface from truapi-pla…
1a62857 
…tform (#18)

UniFFI already gives Kotlin (Android) and Swift (iOS) trait surfaces
straight from `truapi-platform`. Web hosts had hand-written TS types
in `@parity/truapi-host-shared/src/runtime.ts` that mirrored the Rust
traits manually — drift hazard. Codegen now covers TS too so all three
platforms track the same Rust source.

What's new:

- `truapi-codegen` gains a platform-crate rustdoc parser
  (`src/platform.rs`, ~470 LOC). Walks each `pub trait`, classifies
  method return types (`Unit` / `Result<...>` / `BoxStream` / `Box<dyn T>` /
  plain), records `impl Future + Send` returns as async. Detects the
  `Platform` super-trait (method-less, composed of other local traits)
  and preserves the composition order.
- New TS emitter `src/ts/host_callbacks.rs` (~250 LOC) emits one
  `export interface` per Rust capability trait plus a composite
  `HostCallbacks extends Storage, Navigation, ...` interface that
  mirrors `Platform`. Types resolve to existing imports from
  `@parity/truapi`.
- CLI flags `--platform-input` and `--platform-ts-output` wire the
  emitter into the workflow. Existing `--input`/`--output`/`--host-output`/
  `--rust-output` flags are unchanged.
- `scripts/codegen.sh` runs `cargo +nightly rustdoc -p truapi-platform`
  alongside the existing `-p truapi` step and emits to
  `js/packages/truapi-host-shared/src/generated/host-callbacks.ts`.

Consumer integration in `@parity/truapi-host-shared`:

- `src/generated/` and `dist/generated/` added to `.gitignore` (matches
  the `@parity/truapi` policy).
- `runtime.ts` re-exports the typed surface (`HostCallbacks`,
  `Storage`, `Navigation`, ...) from the generated file.
  `WasmRawCallbacks` stays in place — it's the byte-level WASM bridge
  surface and additionally covers core-internal account/sign/statement-
  store callbacks that aren't part of `truapi-platform`. A short
  doc-block makes the typed-vs-raw layering explicit. Bridging the two
  via a SCALE adapter is a deliberate follow-up.

Tests:
- `golden_host_callbacks_ts` integration test pairs rustdoc-of-both-
  crates with the codegen binary and diffs against a checked-in golden.
- 178 workspace tests passing (was 177; +1 for the new golden).
- wasm32 target builds clean.
- `npm install && npm run build && npm test` clean in
  `@parity/truapi-host-shared`.
pgherveou added a commit that referenced this pull request May 17, 2026
@pgherveou
refactor(truapi-codegen): use writedoc!/formatdoc! in host_callbacks …
c004d95 
…emitter

The new TS HostCallbacks emitter from #18 hand-chained 15 writeln! calls
to build the output. CLAUDE.md (this commit also) now requires codegen
modules to prefer indoc::writedoc! / formatdoc! over writeln! chains so
the emitted shape stays visible in source.

Switched host_callbacks.rs to:
- writedoc! for the header + import block (two multi-line writes)
- formatdoc! returning strings for trait interfaces, methods, and the
  super-interface; the parent function joins them
- render_jsdoc returns a String instead of writing through a sink

writeln! count: 15 → 2 (both inside writedoc! invocations themselves).
Golden test rebuilt clean; workspace tests all pass.
@filvecchiato filvecchiato changed the title RFC-0004: Redesign RingLocation in host_account_create_proof RFC: Redesign RingLocation in host_account_create_proof Jun 4, 2026
@pgherveou pgherveou requested review from a team June 22, 2026 10:21
@pgherveou

pgherveou commented Jun 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Looked at what building a sybil resistant app using this API would look like.
There are still some gap in the API I believe.

see my write-up here https://hackmd.io/@pgherveou/ryxz50Iffx

@valentunn

valentunn commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

@pgherveou cannot access the hackmd doc, can you inline here please? Is that related to paritytech/triangle-js-sdks#81 (comment)?

@pgherveou

pgherveou commented Jun 23, 2026

Copy link
Copy Markdown
Collaborator

@valentunn updated the link should work now

@valentunn

valentunn commented Jun 24, 2026

Copy link
Copy Markdown
Contributor

Okay so the only concern right now seems to be related to the contexts we allow to generate proofs in. Current version uses ProductAccountId as domain to generate a proof in product-scoped context. But I see how this restriction blocks contract interactions where contract defines the context. Thus, allowing arbitrary context in the signature might be reasonable with the caveat that hosts should try to triage the context to understand how "dangerous" the proof is

pgherveou
pgherveou approved these changes Jun 29, 2026
View reviewed changes
Comment thread rust/crates/truapi/src/v01/account.rs
Comment on lines +62 to +66
/// dotNS product identifier (e.g. `"my-product.dot"`).
pub type ProductId = String;

/// Arbitrary-byte suffix distinguishing contexts within a single product.
pub type ProductProofContextSuffix = Vec<u8>;

@pgherveou pgherveou Jun 29, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not a big fan of creating type alias, can we avoid it, and just use named field in ProductContext below, this also translate to a better generated JS API

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@pgherveou pgherveou pgherveou approved these changes
@valentunn valentunn valentunn approved these changes

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

proposal rfc

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@filvecchiato @pgherveou @valentunn