Skip to content

chore(poi): make poi-rs its own workspace on iota v1.35.2 - #356

Draft
eike-hass wants to merge 6 commits into
mainfrom
chore/poi-own-workspace
Draft

eike-hass wants to merge 6 commits into
mainfrom
chore/poi-own-workspace

Conversation

@eike-hass

@eike-hass eike-hass commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Description of change

Fast path for Proof of Inclusion: poi-rs becomes its own Cargo workspace (own Cargo.lock, excluded from the root workspace) and moves on its own to iota v1.35.2 (the current mainnet release) and to the crates.io releases of the iota-rust-sdk crates it uses (iota-sdk-types and iota-sdk-grpc-client 1.0.0-rc.2, iota-sdk-grpc-types 1.0.0-rc.1). Single Notarization, Audit Trails and product-core stay on iota v1.29.0, so this needs no product-core release.

Proof of Inclusion does not depend on product-core. In the shared workspace it still had to follow product-core's iota version, because one lockfile allows one version of iota-types. As its own workspace it can follow node and SDK releases independently, and the root workspace no longer compiles test-cluster.

This is the isolated alternative to the Proof of Inclusion part of #355, which bumps the whole workspace and waits for iotaledger/product-core#153. Both change poi-rs, so whichever merges second needs a rebase. If this one goes first, #355 keeps the Single Notarization, Audit Trails and product-core bump only.

Proof format version 2

iota-sdk-types 1.0.0-rc.1 renamed six identifiers that can occur in a proof: CancelledTransactions and cancelled_transactions in the consensus commit prologue, the Cancelled kind of unchanged shared objects, the three ExecutionCancelledDueTo* errors and MoveAuthenticationError. Their binary (BCS) encoding is unchanged, so signatures and verification are unaffected, but their JSON names differ.

Following the compatibility contract in proof.rs, this adds a ProofV2 variant instead of changing ProofV1:

  • ProofBuilder creates ProofV2 proofs, which use the current names.
  • ProofV1 proofs keep their original JSON: reading maps the six old names to the current ones and writing maps them back, limited to the places in a proof where those types occur. Existing proofs deserialize, verify and round-trip unchanged. ProofV2::from converts a version 1 proof.
  • Releases before 0.2.0 cannot read ProofV2 proofs (unknown variant ProofV2), so consumers that exchange proofs with older versions need to upgrade first.

The BREAKING CHANGE: footer of the first commit predates ProofV2 and is wrong now (version 1 proofs keep working). Please replace it in the squash commit message with:

BREAKING CHANGE: poi-rs uses IOTA v1.35.2 and iota-rust-sdk 1.0.0-rc.2 types in its
public API and the builder-style gRPC client. New proofs use format version 2, which
releases before 0.2.0 cannot read. Rust 1.95 or later is required.

Changes

  • poi-rs: standalone manifest (own [workspace], explicit dependency versions, own fastcrypto patch, own Cargo.lock), gRPC source ported to the builder-style GrpcClient API, TransactionEffects and TransactionEvents taken from iota-sdk-types, TransactionEnvelope and OwnedObjectReference changes followed.
  • poi_wasm: same pins and renames. iota-sdk-types is pinned exactly because the package has no tracked lockfile.
  • examples: the Proof of Inclusion examples take the newer types through renamed dependencies (poi-iota-grpc-client, poi-iota-sdk-types, poi-iota-types) and carry the identifiers of the notarization they prove over by their bytes. The examples crate is the only place that builds both iota versions.
  • CI: poi-rs check (Ubuntu), build of library and CLI (all platforms), test-cluster tests (Ubuntu, as proposed in Isolate PoI test-cluster tests from default workspace builds #334), clippy, fmt, docs (into target/doc, so the published docs keep poi_rs) and cargo audit of poi-rs/Cargo.lock. The scheduled dependency refresh updates both lockfiles.
  • Docs: README, fixture README and CLAUDE.md commands use --manifest-path poi-rs/Cargo.toml. poi-rs/target is ignored. Both Proof of Inclusion READMEs describe ProofV2.
  • Fixtures and tests: a frozen version 1 consensus commit prologue fixture generated on the v1.29 release that contains the old names, a v2 fixture directory, unit tests that check each renamed identifier against JSON produced by both SDK versions, and poi_wasm tests for both versions.
  • Version 0.2.0: poi-rs and poi_wasm crates 0.2.0-alpha, @iota/proof-of-inclusion 0.2.0. rust-version 1.95 for both crates (sysinfo 0.39.6 from iota-types requires it), READMEs updated.
  • poi-rs/Cargo.lock: patch updates of quinn, rustls-webpki, webpki-roots, zstd, libz-sys and pulldown-cmark for current RustSec advisories, so the new cargo audit step for this lockfile passes.

Release

  • Version 0.2.0, because the Rust API and the proof format change (see Type of change). After merge: tag poi-v0.2.0 and a moving poi-v0.2, as v0.1 and trails-v0.1 do for the other components.
  • @iota/proof-of-inclusion (npm): 0.2.0, releasable after merge through the Wasm publish workflow (package: proof-of-inclusion).
  • poi-rs (crates.io): not publishable yet. It still has git dependencies on the iota monorepo (iota-types, and iota-config behind the cli feature). The Rust publish workflow runs cargo-release on the root workspace and no longer includes poi-rs, which it could not publish before either.

Links to any relevant issues

Type of change

  • Breaking change (fix or feature that would cause existing functionality to not work as expected)

Rust users get IOTA v1.35.2 and iota-rust-sdk types in the public API, the builder-style gRPC client and Rust 1.95 as the minimum. Existing proofs keep working. New proofs use format version 2, which earlier releases cannot read.

How the change has been tested

CI steps reproduced against an iota v1.35.2 localnet started from the release binaries:

  • Root workspace: per-member feature checks, cargo test --workspace -- --test-threads=1 (132 tests including the Single Notarization and Audit Trails e2e suites), all 32 Rust examples. The 7 Proof of Inclusion examples notarize with the v1.29 client and prove with poi-rs on v1.35.2.
  • poi-rs: checks for all feature sets, 79 tests (including the version 1 and version 2 fixtures), clippy on stable 1.100 with -D warnings, fmt, docs. The poi CLI creates and verifies a live testnet proof.
  • poi_wasm: npm ci, npm run build, 30 unit tests (both proof versions), 6 Node examples, which create and verify version 2 proofs.

Not run locally: release-mode builds, Windows and macOS (CI covers them). All localnet proofs are in epoch 0, so the committee walk across an epoch change is covered by the poi-rs tests only.

To reproduce the Proof of Inclusion part:

cargo test --manifest-path poi-rs/Cargo.toml --all-features -- --test-threads=1
cargo clippy --manifest-path poi-rs/Cargo.toml --all-targets --all-features -- -D warnings
cargo check --workspace --all-targets   # root workspace including the bridged examples

Change checklist

  • I have followed the contribution guidelines for this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • I have checked that new and existing unit tests pass locally with my changes

Move poi-rs into its own Cargo workspace (own Cargo.lock, excluded from the
root workspace) and bump only Proof of Inclusion to iota v1.35.2 and to the
crates.io releases of the iota-rust-sdk crates (iota-sdk-types and
iota-sdk-grpc-client 1.0.0-rc.2, iota-sdk-grpc-types 1.0.0-rc.1). Single
Notarization, Audit Trails and product-core stay on iota v1.29.0.

- poi-rs: standalone manifest, gRPC source ported to the builder-style
  GrpcClient API, TransactionEffects and TransactionEvents taken from
  iota-sdk-types, TransactionEnvelope and OwnedObjectReference changes
  followed.
- poi_wasm: same pins (iota-sdk-types pinned exactly, the package has no
  tracked lockfile) and renames.
- examples: the Proof of Inclusion examples take the newer types through
  renamed dependencies (poi-iota-*) and carry the identifiers of the
  notarization they prove over by their bytes.
- CI: check, build (all platforms), test, clippy, fmt, docs and cargo
  audit cover the poi-rs workspace, and the scheduled dependency refresh
  updates both lockfiles. poi-rs builds into the shared target dir.
- Docs and housekeeping: README, fixture and CLAUDE.md commands use
  --manifest-path poi-rs/Cargo.toml, poi-rs/target is ignored, and the root
  workspace drops dependencies only poi-rs used.

BREAKING CHANGE: iota-sdk-types renamed several serde variants (for example
CancelledTransactions to CanceledTransactions), so ProofV1 JSON that
contains them does not deserialize across this upgrade in either
direction. The proof format is now documented as unstable before 1.0.
Build the Proof of Inclusion library and CLI on every platform without
tests, and run the test-cluster tests on Ubuntu only, as proposed in #334.
The root workspace no longer compiles test-cluster since poi-rs moved into
its own workspace.

Fixes #334
iota-sdk-types 1.0.0-rc.1 renamed six identifiers that can occur in a
proof: CancelledTransactions and cancelled_transactions in the consensus
commit prologue, the Cancelled kind of unchanged shared objects, the three
ExecutionCancelledDueTo* errors and MoveAuthenticationError. Their BCS
encoding is unchanged.

Keep the documented ProofV1 compatibility contract and add a version 2
format instead:

- ProofV2 has the same fields and serializes with the current names.
  ProofBuilder creates it.
- ProofV1 reads and writes its original names through a JSON rename limited
  to the places where the affected types occur, so existing proofs
  deserialize, verify and round-trip unchanged. ProofV2::from converts a
  version 1 proof.
- Fixtures: a version 1 consensus commit prologue proof generated on the
  v1.29 release that contains the old names, and a v2 directory with every
  v1 fixture converted. Unit tests check each renamed identifier against
  JSON produced by both SDK versions.
- poi_wasm tests cover both versions. The docs restore the compatibility
  contract and describe version 2.

Proofs created by this release are ProofV2, which earlier releases cannot
read.
Patch and minor updates in poi-rs/Cargo.lock for current RustSec
advisories, so the cargo audit step for this lockfile passes: libz-sys
1.1.33, pulldown-cmark 0.13.6, quinn-proto 0.11.19, quinn-udp 0.5.16,
rustls-webpki 0.103.17, webpki-root-certs and webpki-roots 1.0.12, zstd
0.13.5, zstd-safe 7.4.1, zstd-sys 2.1.3. RUSTSEC-2026-0387 (crypto-bigint
0.5) has no patched release and is ignored repository-wide.
- poi-rs and poi_wasm crates 0.2.0-alpha, @iota/proof-of-inclusion 0.2.0.
  The Rust API now uses IOTA v1.35.2 and iota-rust-sdk types and the
  builder-style gRPC client, and new proofs use format version 2, which
  0.1.x cannot read. Release tags: poi-v0.2.0 and a moving poi-v0.2.
- rust-version 1.95 for both crates, READMEs updated. iota-types v1.35.2
  pulls in sysinfo 0.39.6, which requires Rust 1.95 (cargo +1.94 refuses
  the locked tree). poi_wasm alone needs 1.90 and is aligned to one number.

This branch has not been deployed

No deployments
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.

Isolate PoI test-cluster tests from default workspace builds

1 participant