NymConform: Reusable CI Conformance Tests for Nym Mixnet Integrations

Nym Squad League Phase 1: Proposals
1

NymConform: Reusable CI Conformance Tests for Nym Mixnet Integrations

Grant: Build with Nym
Project status: Pre-MVP
Proposed duration: 6 weeks
Team: Carl and Zynorr
Requested reward: 98,800 NYM (approximately $2,700 USD ; the USD equivalent will fluctuate)

Payout address: To be provided through the program’s agreed process

1. Project Summary

NymConform is a proposed open-source developer toolkit for testing application integrations with Nym’s TypeScript-based mixnet clients.

It will provide a reusable test runner, controlled test fixtures, client-specific adapters, and continuous integration (CI) examples. Developers will be able to test request handling, connection lifecycle, error behavior and shutdown across two initial integrations: @nymproject/mix-fetch and @nymproject/mix-websocket.

NymConform will help developers identify integration failures before releasing their applications, while reusing Nym’s existing clients and public interfaces rather than building another proxy, monitoring dashboard or privacy application.

The project will begin with a review of existing tools and a working test specification, followed by the implementation of a browser-compatible test harness, client adapters, structured reporting and a reusable GitHub Actions example.

2. Problem Statement

Nym’s mixnet provides network-level privacy, but applications must still correctly implement the networking interfaces used to communicate through it.

Nym’s current TypeScript packages expose different interfaces over the shared mix-tunnel and smolmix infrastructure. mix-fetch provides HTTP(S) requests, while mix-websocket supports WebSocket connections.

Application developers need to test more than whether a package installs or a connection succeeds. They need to verify request and response handling, connection startup and shutdown, timeout behavior, error propagation, and the behavior of their application when the configured route becomes unavailable.

Existing ecosystem projects already address some related issues. Mixpool, for example, includes mixnet routing and failure-handling tests for its application. Other projects provide network-isolated integration tests, connectivity checks and timing experiments.

However, we have not yet established whether a reusable test harness covering these behaviors across Nym’s TypeScript client packages already exists. This will be the first task, not an assumption on which the project depends.

NymConform will address the potential gap by providing a shared, repeatable testing layer that developers can reuse instead of writing separate integration tests for every application.

3. Proposed Solution

NymConform will deliver five core capabilities.

A. Shared test runner

A TypeScript command-line interface will select the client adapter, test profile and execution mode, producing consistent results across supported integrations.

B. Browser-compatible test harness

The runner will orchestrate tests in a compatible browser environment supporting Web Workers and WebAssembly. This is important because the current mix-fetch implementation uses the browser/WebAssembly-based mix-tunnel runtime; the project will not assume that it runs directly in bare Node.js.

C. Client integration tests

The initial suite will cover:

  • mix-fetch: HTTP request and response handling, status and body validation, timeouts, cancellation, startup errors and cleanup.

  • mix-websocket: Connection establishment, message exchange, connection closure, error handling, timeout behavior and cleanup.

  • Shared tunnel behavior: Relevant lifecycle and failure cases where the current documented interfaces permit reliable testing.

D. Controlled live-mixnet validation

An opt-in test will use a controlled endpoint to check observable routing behavior. It will compare the configured direct reference path with the Nym-routed request and record whether the expected difference was observed.

The test report will retain a pass/fail outcome rather than raw source IP addresses. Such a check validates only the tested request and environment; it does not prove anonymity or establish that every application request is private.

E. CI integration and structured reporting

NymConform will provide a GitHub Actions example and JSON/Markdown reports that distinguish failed assertions, unsupported tests and infrastructure failures.

Deterministic tests will run by default. Live-mixnet tests will be optional because network availability and routing conditions can vary.

4. Technical Architecture

The project will use TypeScript and Node.js for the CLI and test orchestration, with Playwright or an equivalent browser automation framework for browser-dependent tests.

The test environment will include:

  • Controlled HTTP and WebSocket test fixtures.

  • Version-pinned Nym client packages and a committed lockfile.

  • Deterministic test profiles for request handling, lifecycle and error behavior.

  • A browser runner compatible with the selected package versions.

  • An opt-in live-mixnet test using a controlled public endpoint.

  • JSON and Markdown reports for local and CI use.

Package versions and APIs will be verified during Milestone 1 before being committed to the implementation. The architecture will account for the shared mix-tunnel runtime instead of creating separate, incompatible tunnel instances for each test.

The tool will not modify Nym’s core protocol, collect general user traffic, or store raw network identifiers in its reports. It will test observable integration behavior, not claim to prove anonymity or eliminate every possible metadata leak.

5. Milestones and Acceptance Criteria

Milestone 1: Scope Validation and Test Specification

Duration: Weeks 1–2
Proposed reward: 19,760 NYM

Deliverables

  • Review Nym’s client documentation, package interfaces, existing integration tests and relevant ecosystem projects.

  • Publish an overlap and differentiation analysis.

  • Define the test matrix and threat model for mix-fetch and mix-websocket.

  • Create the public repository, initial fixtures and development plan.

Acceptance criteria

  • One published technical specification.

  • At least 10 defined test scenarios.

  • Documented findings on which capabilities already exist and what remains distinct.

  • A revised scope if Nym contributors identify substantial duplication.

This milestone will establish whether the proposed shared test harness provides enough additional value to justify continued development.

Milestone 2: Test Harness and Client Adapters

Duration: Weeks 3–4
Proposed reward: 39,520 NYM

Deliverables

  • Implement the CLI and browser-based test runner.

  • Add adapters for mix-fetch and mix-websocket.

  • Implement deterministic request/response, lifecycle and failure tests.

  • Generate structured reports containing results and relevant diagnostics.

Acceptance criteria

  • At least 12 reproducible automated tests.

  • Both client adapters execute their documented test profiles.

  • Reports distinguish test failures from unavailable infrastructure and unsupported scenarios.

  • Public installation and usage documentation.

Milestone 3: CI Integration and Public Release

Duration: Weeks 5–6
Proposed reward: 39,520 NYM

Deliverables

  • Publish a reusable GitHub Actions example.

  • Implement one opt-in live-mixnet test against a controlled endpoint.

  • Complete documentation, configuration examples and known limitations.

  • Publish a versioned release and final contribution report.

Acceptance criteria

  • Successful CI execution of the deterministic suite.

  • At least one documented live-mixnet test.

  • Two external developer reviews or pilot attempts targeted.

  • Public release and a final report covering test results, limitations and feedback.

External participation is a target rather than a confirmed commitment.

The proposed milestone rewards total 98,800 NYM. All deliverables will be documented publicly, and progress updates will be provided throughout the project.

6. Value to Nym

NymConform aims to make Nym’s developer interfaces easier to integrate and test reliably.

It will give application maintainers reusable integration tests, controlled fixtures, CI examples and structured reports, reducing the need to recreate basic verification workflows in each project.

The project will measure success through:

  • Supported client adapters and reproducible test cases.

  • Successful automated test and CI runs.

  • External developer reviews and pilot feedback.

  • Documented integration issues identified.

  • Adoption of the test kit by independent projects.

The tool will not claim to prove anonymity, guarantee application security, or replace broader security reviews.

7. Team

Carl (@duongja) — Project Lead

GitHub: duongja (Mad G) · GitHub

Carl will lead scope definition, requirements, developer outreach, documentation, coordination and reporting.

His public work includes ENSCLI, a TypeScript CLI for inspecting and debugging ENS names, as well as VeilSafe and COOLTOKEN. This work provides relevant context in developer tooling, blockchain applications and technical documentation.

Zynorr (@zynorr) — Integration Engineer

GitHub: zynorr (zynor) · GitHub

Zynorr will lead integration workflows, browser/API test fixtures, client adapters and CI implementation.

His public work includes the signed off-chain data starter kit, which combines TypeScript gateway components with EIP-3668 and EIP-712 integrations, alongside MX402 Exchange and TrustAgent.

The team brings relevant TypeScript, CLI and integration experience, but does not claim prior Nym-specific implementation experience. The first milestone will verify the architecture and confirm the remaining technical gaps.

8. Open-Source Commitment

The test runner, fixtures, client adapters, CI examples and documentation will be released under the MIT licence, subject to dependency compatibility.

The repository will document supported package versions, setup requirements, configuration, known limitations and contribution guidelines. The project will be designed so other developers can run it independently without ongoing assistance from Nym’s core engineering team.

9. Reward and Budget Justification

Requested reward: 98,800 NYM, approximately USD $2,700 at the reference market price. The grant will be denominated in NYM, so its USD-equivalent value can change.

Indicative use of funds:

  • Test runner, CLI and core implementation: $1,250

  • Client adapters and controlled fixtures: $550

  • CI integration and live-test infrastructure: $300

  • Documentation, examples and public release: $300

  • QA, coordination and reporting: $300

Total indicative budget: $2,700.

These amounts are planning estimates, not fixed USD payments. The final reward and milestone arrangements will be agreed with the Nym Squad League before work begins.

10. Closing

NymConform aims to turn Nym’s integration guidance into reusable, automated tests for developers building with its TypeScript mixnet clients.

We welcome feedback from Nym contributors on the proposed test scope, existing implementations and the most useful initial client coverage. The first milestone is deliberately designed to verify differentiation before the team commits to the full implementation.

Our goal is to deliver a focused, independently usable open-source tool that improves the repeatability of Nym application integration testing.