feat: Make Pallas WASM compatible

[bkioshn]

Description

We are currently implementing Hermes WebAssembly (WASM) application engine designed to provide secure, sandboxed execution of modular applications. Because Hermes targets the WASM platform, it inherits WASM’s inherent limitations - that WASM modules cannot directly access operating system features such as I/O, networking, or threading.

The primary obstacle preventing the WASM module from importing Pallas (either directly or through transitive dependencies) is the pallas-network crate. This crate relies on Tokio and socket APIs for networking, which are incompatible with the WASM environment. Meanwhile, Hermes requires certain constants and general-purpose types currently defined within pallas-network. Attempting to import pallas-network into Hermes results in build failures due to these I/O and async runtime dependencies.

To resolve this, we propose extracting these constants and primitive types into a existing crate, pallas-primitive, which has no dependencies on Tokio or socket APIs. This restructuring allows Hermes to use the necessary shared definitions without bringing in incompatible code. Additionally, this PR includes cleanup of redundant types across the Pallas crates, improving overall code clarity and maintainability.

In addiiton, pallas itself, when import directly should be WASM compatible by disable some feature like pallas-hardano and pallas-network for wasm family architect.

Summary of changes

• Extract Point and constant out of pallas-network to pallas-primitives. Note the old one as deprecated
• Remove redundant constant in pallas-traverse
• Disable pallas-network and pallas-hardano when architect family is wasm

Summary by CodeRabbit

• New Features

  • Introduces centralized network constants and a canonical Point type for consistent use across the ecosystem.

• Chores

  • Legacy constants and Point locations deprecated and re-exported — update imports to the new canonical paths.
  • Network and Hardano-related exports now gated away from wasm targets to improve cross-target compatibility.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[scarmuega]

Thanks @bkioshn, I agree with that this is something we need to support.

The Point struct should be moved to primitives, but the I'm not so sure about the network constants. Those are pretty coupled with code that actually does networking.

What would be the use case of having those constants available in a environment that doesn't support networking?

[bkioshn]

Thanks @bkioshn, I agree with that this is something we need to support.

The Point struct should be moved to primitives, but the I'm not so sure about the network constants. Those are pretty coupled with code that actually does networking.

What would be the use case of having those constants available in a environment that doesn't support networking?

We are using those constant network in our cardano-blockchain-types
https://github.com/input-output-hk/catalyst-libs/blob/main/rust/cardano-blockchain-types/src/network.rs
This crate is design to be WASM compatible, so if this is WASM compatible, it cannot use the pallas-network directly

[coderabbitai]

Walkthrough

Centralizes network constants and Point into pallas-primitives, adds a new types module with CBOR Encode/Decode for Point, replaces in-crate constants with deprecated aliases to the new canonical definitions, adds pallas-primitives as a local dependency, and gates network/hardano exports behind a non-wasm cfg.

Changes

Cohort / File(s)	Summary
Dependency / manifest updates pallas-network/Cargo.toml, pallas/Cargo.toml	Adds local pallas-primitives = { version = "=1.0.0-alpha.3", path = "../pallas-primitives" } to pallas-network/Cargo.toml; moves pallas-network to a target-specific [target.'cfg(not(target_family = "wasm"))'.dependencies] block in pallas/Cargo.toml and adds optional pallas-hardano there.
Library module & exports pallas-primitives/src/lib.rs, pallas-primitives/src/types/mod.rs	Adds pub mod types; and declares pub mod network_constant; and pub mod point;, reorders pub use plutus_data::* to follow the new types export.
Network constants (new canonical source) pallas-primitives/src/types/network_constant.rs	New module defining public network magic numbers, network IDs, protocol role bitflags (client/server), N2N and N2C protocol channel constants, and MAX_SEGMENT_PAYLOAD_LENGTH.
Point type with CBOR support pallas-primitives/src/types/point.rs	New Point enum (Origin / Specific(u64, Vec<u8>)) with new and slot_or_default, Debug impl, and minicbor Encode/Decode implementations including validation and decode error handling.
Deprecation wrappers & re-exports pallas-network/src/miniprotocols/common.rs, pallas-network/src/multiplexer.rs, pallas-traverse/src/wellknown.rs	Replaces in-crate literal constants and the local Point with deprecated public aliases that reference pallas_primitives::types::network_constant::* and pallas_primitives::types::point::Point, preserving existing public names but marking them deprecated.
Wasm gating of network/hardano pallas/src/lib.rs	Makes pub use pallas_network as network conditional on #[cfg(not(target_family = "wasm"))]; gates the interop::hardano module and hardano storage re-export with the same non-wasm cfg in addition to the existing feature flag.

Sequence Diagram(s)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Areas to review closely:

• pallas-primitives/src/types/point.rs — CBOR Encode/Decode correctness, boundary cases, and error messages.
• pallas-primitives/src/types/network_constant.rs — numeric values and protocol/channel assignments.
• Deprecation wrappers in pallas-network and pallas-traverse — ensure API compatibility and deprecation notes.
• Cargo manifest changes in pallas/Cargo.toml — target gating and optional feature interactions.

Poem

🐰
I hopped through constants, neat and trim,
Rehomed the Point with a tiny grin,
CBOR tucked in my pouch so bright,
Deprecated signs point to the light,
Wasm gates closed — but carrots still in sight. 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: Make Pallas WASM compatible' directly and accurately summarizes the main objective of the changeset, which is to refactor Pallas to support WebAssembly environments by extracting WASM-compatible definitions and conditionally disabling network features.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d140b4c and da55afb.

📒 Files selected for processing (1)

• pallas-primitives/src/types/network_constant.rs (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• pallas-primitives/src/types/network_constant.rs

---

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.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

pallas-primitives/src/types/point.rs (1)

52-68: Consider improving the error message.

The decode error message at line 64 is incomplete: "can't decode Point from array of size" doesn't include the actual size that was encountered. While this is a minor issue, including the size would help debugging.

Consider this improvement:

             _ => Err(decode::Error::message(
-                "can't decode Point from array of size",
+                &format!("can't decode Point from array of size {:?}", size),
             )),

Note: This requires the error message to be a String rather than a &str. If decode::Error::message only accepts &'static str, you might need to use a different error constructor or accept the current message.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d34b143 and 9c6322e.

📒 Files selected for processing (10)

• pallas-network/Cargo.toml (1 hunks)
• pallas-network/src/miniprotocols/common.rs (1 hunks)
• pallas-network/src/multiplexer.rs (1 hunks)
• pallas-primitives/src/lib.rs (1 hunks)
• pallas-primitives/src/types/mod.rs (1 hunks)
• pallas-primitives/src/types/network_constant.rs (1 hunks)
• pallas-primitives/src/types/point.rs (1 hunks)
• pallas-traverse/src/wellknown.rs (1 hunks)
• pallas/Cargo.toml (1 hunks)
• pallas/src/lib.rs (3 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

pallas-primitives/src/lib.rs (1)

pallas-traverse/src/witnesses.rs (1)

• plutus_data (106-128)

pallas-primitives/src/types/point.rs (1)

pallas-primitives/src/lib.rs (4)

• decode (181-189)
• decode (214-233)
• encode (193-203)
• encode (237-268)

🔇 Additional comments (14)

pallas-network/Cargo.toml (1)

19-19: LGTM! Dependency addition is correct.

The addition of pallas-primitives as a dependency is necessary for the multiplexer to reference the canonical network constants and aligns with the overall goal of centralizing these definitions.

pallas-primitives/src/lib.rs (1)

10-12: LGTM! Module structure is clean.

The addition of the types module properly exposes the new network_constant and point submodules. The reordering of the plutus_data re-export has no functional impact.

pallas-primitives/src/types/mod.rs (1)

1-2: LGTM! Module declarations are correct.

Clean module structure exposing network_constant and point.

pallas-network/src/multiplexer.rs (1)

490-494: LGTM! Deprecation strategy is sound.

The deprecation attribute provides a clear migration path, and the re-export ensures backward compatibility while pointing users to the canonical definition in pallas_primitives.

pallas/Cargo.toml (1)

24-26: LGTM! WASM gating is correctly implemented.

Moving pallas-network and pallas-hardano to target-specific dependencies for non-WASM targets is the correct approach to enable WASM compatibility while keeping these crates available for native builds.

pallas-primitives/src/types/point.rs (2)

1-35: LGTM! Point type definition and helpers are well-designed.

The Point enum with Origin and Specific variants is clean, and the helper methods (slot_or_default(), new()) provide good ergonomics. The Debug implementation with hex-encoded hash is appropriate for developer visibility.

---

37-50: LGTM! CBOR encoding is correctly implemented.

The encoding matches the expected format: Origin as an empty array and Specific as a 2-element array containing the slot and hash bytes.

pallas/src/lib.rs (3)

12-13: LGTM! WASM gating is correctly applied.

The conditional export of pallas_network for non-WASM targets aligns with the dependency gating in pallas/Cargo.toml.

---

55-65: LGTM! Hardano module is properly gated.

The WASM gating is correctly combined with the existing feature flag, ensuring the hardano module is only available when both the feature is enabled and the target is not WASM.

---

71-76: LGTM! Storage export gating is consistent.

The WASM gating on the deprecated hardano storage re-export maintains consistency with the changes to the interop::hardano module.

pallas-traverse/src/wellknown.rs (1)

4-31: Deprecation strategy verified and correct.

All eight constants exist in pallas_primitives::types::network_constant, are properly exported as pub const, and the re-exports in wellknown.rs will maintain the same values. The deprecation messages accurately guide users to the new location.

pallas-network/src/miniprotocols/common.rs (3)

2-26: Network magic constants successfully migrated to pallas-primitives with backward-compatible deprecation wrappers.

The deprecation pattern correctly re-exports constants from pallas_primitives::types::network_constant and provides clear migration guidance. All new constants exist with correct values, and existing usage in tests and examples continues to work through the deprecated re-exports.

---

142-143: Point type re-export verified and correct.

The Point type exists at pallas_primitives::types::point::Point as a public enum with variants Origin and Specific(u64, Vec<u8>). The re-export using pub use with deprecation is the appropriate pattern, and the API matches the usage throughout the codebase (verified in test files).

---

34-139: Protocol constants properly deprecated with verified migration path.

All 15 protocol constants in pallas-network/src/miniprotocols/common.rs (lines 34-139) are correctly deprecated with clear, actionable migration messages. Verification confirms:

• All target constants exist in pallas_primitives::types::network_constant
• Deprecation attributes are properly applied with consistent messaging
• Re-export pattern is correct and functional

Active usage throughout the codebase (106 instances in facades.rs and other files) is expected during transition and will generate appropriate deprecation warnings to guide further migration.