feat(permission0): stream funnels

[saiintbrisson]

This patch adds a new operation for stream permissions that happens when distributing the tokens. A "funnel" means that incoming streams for a permission will be emitted as a new, unified stream ID under this permission. The funneling mechanism allows localization and isolation of tokens in complex streaming systems.

I had some trouble doing this as the initial solution was still not clear to me. For some reason, I initially thought I'd have to alter the entire accumulation logic, but it eventually came to me that I'd only have to override when distributing. It took me a while to come to this conclusion.

Closes CHAIN-136.

Summary by CodeRabbit

• New Features

  • Introduced optional stream “funneling” to route distributions through derived streams, improving separation and observability.
  • Permission updates and delegation now support enabling/disabling funnels; events now emit source and target stream IDs.
  • Enforced a per-permission funnel limit.

• Documentation

  • Added a “Funneling Streams” section with diagrams and updated API usage.

• Tests

  • Added end-to-end funnel scenarios and updated existing cases to new parameters.

• Chores

  • Runtime upgrade with migration and storage version bump; runtime/config updated to include funnel limits.

[linear]

CHAIN-136 rework stream delegation to allow for isolated streams

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

Introduces an opt-in “funneling” mechanism for stream permissions: new API parameters, storage/event changes, and runtime migration to v8. Updates docs, runtime config/version, and tests. Adds funnel-derived stream ID generation, enable/disable funnel toggling, and emits source/target stream IDs during distribution. Minor IDE config tweak includes tests in cargo check.

Changes

Cohort / File(s)	Summary
IDE config .helix/languages.toml	Rust analyzer override now runs cargo check with --tests --all-targets and JSON output.
Docs: permission0 funneling docs/permission0.md	Documents funneling, updates update_stream_permission signature and semantics, adds diagrams, events, and integration notes.
Permission0 API surface pallets/permission0/api/src/lib.rs	Adds FUNNEL_STREAM_PREFIX, generate_funnel_stream_id(...), and enable_funnel: bool to delegate_stream_permission.
Permission0 stream impl pallets/permission0/src/ext/stream_impl.rs	Propagates enable_funnel to delegation/update; adds funnel: Option<bool) to updates; toggles funnels with auth checks.
Permission0 pallet core pallets/permission0/src/lib.rs	Storage version 7→8; new Config::MaxFunnelsPerPermission; Event::StreamDistribution now source_stream/target_stream; new Error::TooManyStreamFunnels; extrinsics accept enable_funnel/funnel.
Permission0 stream logic pallets/permission0/src/permission/stream.rs	Adds StreamScope.funnels, FunnelStream<T>, enable_funnel(...)/disable_funnel(...); routes distribution via derived funnel stream; emits source/target stream IDs.
Migration v8 pallets/permission0/src/migrations.rs	Adds v8 migration translating stored permissions to new structures; initializes funnel fields; exposes MigrationToV8.
Runtime integration runtime/src/lib.rs, runtime/src/configs.rs	Bumps spec_version 26→27; sets Migrations to include v8 migration; configures MaxFunnelsPerPermission = ConstU32<1>.
Tests: funnel feature pallets/permission0/tests/funnel.rs	New tests covering enable/disable funnels, derived stream propagation, and multi-level chains.
Tests: signature updates pallets/permission0/tests/stream.rs, test-utils/src/lib.rs	Updates call sites for new params; adds MaxFunnelsPerPermission in test config; passes final boolean arg to delegation.
Faucet test config pallets/faucet/tests/faucet.rs	Adds MaxFunnelsPerPermission = ConstU32<1> to permission0 config in tests.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User as Caller
  participant Pallet as permission0::Pallet
  participant Stream as StreamScope
  participant Events as Event

  rect rgba(230,240,255,0.5)
  note over User,Pallet: Delegate with optional funnel
  User->>Pallet: delegate_stream_permission(..., enable_funnel)
  Pallet->>Stream: create scope (recipients/streams/accumulation)
  alt enable_funnel == true
    Stream->>Stream: enable_funnel(permission_id) -> derive StreamId
  end
  Stream-->>Pallet: scope ready
  Pallet-->>User: Ok (PermissionId)
  end

  rect rgba(240,255,230,0.5)
  note over User,Pallet: Update toggling funnel
  User->>Pallet: update_stream_permission(..., funnel: Option<bool>)
  alt funnel is Some(true/false)
    Pallet->>Stream: enable_funnel / disable_funnel
  end
  Pallet-->>User: Ok
  end

  rect rgba(255,245,230,0.5)
  note over Pallet,Events: Distribution with source/target stream IDs
  Pallet->>Stream: execute(permission)
  Stream->>Stream: resolve source_stream
  alt funnel present
    Stream->>Stream: target_stream = derived funnel stream
  else
    Stream->>Stream: target_stream = source_stream
  end
  Stream->>Events: emit StreamDistribution{source_stream, target_stream}
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60–90 minutes

Possibly related PRs

• sync: merge spec 24 and 25 to main #139 — Prior work on stream-based permission APIs; closely overlaps with funneling additions and migrations in the same modules.
• Syncing Dev to Main #132 — Adjusts rust-analyzer command; related to the .helix/languages.toml update in this PR.

Suggested reviewers

• functor-flow
• devwckd
• steinerkelvin

Poem

I burrowed new tunnels for streams to flow,
A funnel of bytes where the tokens go.
Source to target, hop by hop,
Events now tell each graceful drop.
Migrate the warren, version eight—
Tap-tap, tests pass—carrots await! 🥕🐇

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes Check	⚠️ Warning	The update to .helix/languages.toml for Rust language server configuration is unrelated to the funnel streams feature and CHAIN-136, introducing an editor tooling change outside the scope of this PR.	Remove the Helix configuration change from this PR or move it to a separate PR focused on editor/tooling configuration.
Description Check	⚠️ Warning	The provided description explains the funnel feature but does not follow the repository’s template: it omits the Pull Request checklist and the required “## Description” and “## Related Issues” headings, and does not explicitly link CHAIN-136 under its own section.	Please update the PR description to include the repository checklist, add a “## Description” section with a brief summary, and a “## Related Issues” section linking CHAIN-136.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title clearly and concisely describes the introduction of a “stream funnels” feature in the permission0 module, capturing the main enhancement without extraneous detail.
Linked Issues Check	✅ Passed	The changes implement the funneling mechanism described in CHAIN-136 by adding API parameters, storage fields, events, migration logic, and end-to-end tests to isolate stream token distributions per permission, directly fulfilling the issue’s requirements.
Docstring Coverage	✅ Passed	Docstring coverage is 84.85% which is sufficient. The required threshold is 80.00%.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[saiintbrisson]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/permission0.md (1)

262-404: Fix delegate_stream_permission signature in the docs

The spec still shows the old signature without the new enable_funnel: bool argument, so readers following this section will try to compile an outdated call. Please add the new parameter (and a short note about its meaning) to keep the docs in sync with the runtime API.

🧹 Nitpick comments (2)

.helix/languages.toml (1)

5-5: Avoid deprecated --all flag in the override command.

cargo check --all emits a deprecation warning on every run. Please switch to --workspace (and, if you need all targets, --all-targets) alongside --tests to keep the command clean.

pallets/permission0/src/permission/stream.rs (1)

33-56: Resolve the MaxFunnelsPerPermission wiring

We just introduced Config::MaxFunnelsPerPermission, but the storage and guard still hard-code a single funnel via ConstU32<1> and ensure!(self.funnels.is_empty()). Any runtime that sets the constant to something other than 1 will still hit TooManyStreamFunnels, so the new knob is effectively dead weight.

Please either (a) drop the Config item altogether or (b) wire it through by backing BoundedVec with T::MaxFunnelsPerPermission and comparing against T::MaxFunnelsPerPermission::get() instead of is_empty(). That keeps the configuration meaningful and avoids surprising downstream teams.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between b768d21 and 24f3bf2.

📒 Files selected for processing (13)

• .helix/languages.toml (1 hunks)
• docs/permission0.md (2 hunks)
• pallets/faucet/tests/faucet.rs (1 hunks)
• pallets/permission0/api/src/lib.rs (2 hunks)
• pallets/permission0/src/ext/stream_impl.rs (6 hunks)
• pallets/permission0/src/lib.rs (8 hunks)
• pallets/permission0/src/migrations.rs (1 hunks)
• pallets/permission0/src/permission/stream.rs (8 hunks)
• pallets/permission0/tests/funnel.rs (1 hunks)
• pallets/permission0/tests/stream.rs (31 hunks)
• runtime/src/configs.rs (1 hunks)
• runtime/src/lib.rs (2 hunks)
• test-utils/src/lib.rs (2 hunks)

🧰 Additional context used

🧠 Learnings (2)

📚 Learning: 2025-08-21T22:09:27.601Z

Learnt from: CR
PR: renlabs-dev/torus-substrate#0
File: CLAUDE.md:0-0
Timestamp: 2025-08-21T22:09:27.601Z
Learning: Applies to {pallets,runtime}/**/*.rs : Use VersionedMigration for storage migrations

Applied to files:

• runtime/src/lib.rs

📚 Learning: 2025-08-21T22:09:27.601Z

Learnt from: CR
PR: renlabs-dev/torus-substrate#0
File: CLAUDE.md:0-0
Timestamp: 2025-08-21T22:09:27.601Z
Learning: Applies to {pallets,runtime}/**/*.rs : Increment storage version when changing storage

Applied to files:

• pallets/permission0/src/lib.rs

[functor-flow]

can we add event for the funnel creation ? i think it's not there

[functor-flow]

before enabling or updating a funnel maybe we can check

 ensure!(matches!(scope.allocation, StreamAllocation::Streams(_)),
        Error::<T>::FunnelRequiresStreamsAllocation). 

so you can not enable funnel on FixedAmount etc

[github-actions]

Package	Line Rate	Health
pallets.governance.src	93%	✔
pallets.permission0.src	90%	✔
pallets.emission0.src.distribute	90%	✔
pallets.permission0.src.permission	86%	✔
pallets.emission0.src	92%	✔
pallets.permission0.api.src	92%	✔
pallets.permission0.src.ext	90%	✔
pallets.torus0.src	96%	✔
pallets.torus0.api.src	79%	✔
Summary	91% (3574 / 3909)	✔

[github-actions]

Detailed coverage report