Channel Not Found Error After Creation - ClearNode Integration Issue

[a-singh09]

Channel Not Found Error After Creation - ClearNode Integration Issue

Environment

• Network: Polygon Mainnet (Chain ID: 137)
• ClearNode URL: wss://clearnet.yellow.com/ws
• Nitrolite SDK: @erc7824/nitrolite v0.4.0
• Token: USDC (0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359)
• Framework: Next.js with React hooks
• Wallet: MetaMask

Problem Statement

Symptom

Channel is successfully created on-chain with confirmed transaction, but subsequent operations (specifically resize_channel RPC) fail with error:

Error: channel 0x240a4b4e8e0024e024b42a8a5b6dad69e49f1ff16e6017151798f76dffc84798 not found

Impact

• Users deposit USDC and create channels successfully
• Channels exist on-chain (verified via transaction hash)
• ClearNode RPC returns "channel not found" when trying to perform operations
• Funds are locked in on-chain channel but inaccessible via ClearNode API
• Payment flow completely blocked

Current Implementation Flow

1. Channel Creation Process

// Step 1: Connect to ClearNode WebSocket
await clearNodeClient.connect({
  walletAddress,
  signerAddress: walletAddress,
  walletClient,
});

// Step 2: Get broker configuration
const { createGetConfigMessage } = await import("@erc7824/nitrolite");
const messageSigner = clearNodeClient.getMessageSigner();
const signer = async (payload: any) => {
  return messageSigner({ payload, walletClient });
};

const getConfigMsg = await createGetConfigMessage(signer);
const brokerConfig = await clearNodeClient.sendRequest(getConfigMsg);

const polygonNetwork = brokerConfig.networks.find((n) => n.chain_id === 137);

// Step 3: Initialize Nitrolite client
const nitroliteClient = new NitroliteClient({
  publicClient,
  walletClient,
  stateSigner,
  addresses: {
    custody: polygonNetwork.custody_address,
    adjudicator: polygonNetwork.adjudicator_address,
    guestAddress: config.broker_address,
  },
  chainId: 137,
  challengeDuration: 3600n,
});

// Step 4: Request broker signature for channel
const { createCreateChannelMessage } = await import("@erc7824/nitrolite");
const signedChannelRequest = await createCreateChannelMessage(signer, {
  chain_id: 137,
  token: tokenAddress,
  amount: amountBigInt.toString(),
});

const brokerResponse = await clearNodeClient.sendRequest(signedChannelRequest);

// Step 5: Approve USDC for custody contract
const approveHash = await walletClient.writeContract({
  account: walletClient.account,
  address: tokenAddress,
  abi: [
    /* ERC20 approve ABI */
  ],
  functionName: "approve",
  args: [polygonNetwork.custody_address, amountBigInt],
  chain: null,
});

// Wait for approval confirmation
await new Promise((resolve) => setTimeout(resolve, 3000));

// Step 6: Create channel on-chain
const channelResult = await nitroliteClient.createChannel({
  channel: {
    participants: channelData.channel.participants,
    adjudicator: channelData.channel.adjudicator,
    challenge: BigInt(channelData.channel.challenge),
    nonce: BigInt(channelData.channel.nonce),
  },
  unsignedInitialState: {
    intent: channelData.state.intent,
    version: BigInt(channelData.state.version),
    data: channelData.state.state_data,
    allocations: channelData.state.allocations.map((a) => ({
      destination: a.destination,
      token: a.token,
      amount: BigInt(a.amount),
    })),
  },
  serverSignature: channelData.server_signature,
});

console.log("✅ Channel created on-chain!");
console.log("   Channel ID:", channelData.channel_id);
console.log("   Tx hash:", channelResult.txHash);

Result:
✅ Transaction succeeds, channel ID generated: 0x240a4b4e8e0024e024b42a8a5b6dad69e49f1ff16e6017151798f76dffc84798

Transaction URL: https://polygonscan.com/tx/0x107e8d0ed2ea4f53e70c8e27a49e7a313311c592b8d07c0716a56555959f54f9

2. Channel Registration Listener (Implemented)

After channel creation, we listen for ClearNode's channel registration:

const channelRegisteredPromise = new Promise<void>((resolve, reject) => {
  const timeout = setTimeout(() => {
    unsubscribe();
    reject(new Error("Timeout waiting for channel registration (60s)"));
  }, 60000); // 60 second timeout

  const unsubscribe = clearNodeClient.onMessage((message: any) => {
    if (message.res && Array.isArray(message.res)) {
      const method = message.res[1];
      const data = message.res[2];

      // Listen for individual channel update "cu"
      if (method === "cu" && data.channel_id === channelData.channel_id) {
        console.log("✅ ClearNode registered channel!");
        clearTimeout(timeout);
        unsubscribe();
        resolve();
      }

      // Listen for batch channel list "channels"
      else if (method === "channels" && data.channels) {
        if (
          data.channels.some(
            (c: any) => c.channel_id === channelData.channel_id,
          )
        ) {
          console.log("✅ ClearNode registered channel (batch)!");
          clearTimeout(timeout);
          unsubscribe();
          resolve();
        }
      }
    }
  });
});

try {
  await channelRegisteredPromise;
} catch (err) {
  console.warn("⚠️ Channel registration timeout - will try resize anyway");
}

Result: ❌ Timeout after 60 seconds - NO "cu" message received from ClearNode

3. Attempted Resize Operation

After timeout, we attempt to resize the channel to move funds to unified balance:

const resizeRequest = {
  channel_id: channelData.channel_id,
  allocate_amount: amountBigInt.toString(), // Move ALL to unified balance
  resize_amount: "0", // Don't resize, just deallocate
  funds_destination: walletAddress,
};

const timestamp = Date.now();
const reqId = timestamp;

const requestPayload: [number, string, any, number] = [
  reqId,
  "resize_channel",
  resizeRequest,
  timestamp,
];

const payloadString = JSON.stringify(requestPayload.slice(1, -1));
const signature = await messageSigner({
  payload: payloadString,
  walletClient,
});

const request = {
  req: requestPayload,
  sig: [signature],
};

const resizeResponse = await clearNodeClient.sendRequest(
  JSON.stringify(request),
);

Result: ❌ Error: channel 0x240a4b4e8e0024e024b42a8a5b6dad69e49f1ff16e6017151798f76dffc84798 not found

4. Verification with get_channels RPC

const { createGetChannelsMessage } = await import("@erc7824/nitrolite");
const getChannelsMsg = await createGetChannelsMessage(signer, walletAddress);
const channelsResponse = await clearNodeClient.sendRequest(getChannelsMsg);

console.log("Channels response:", channelsResponse);

Result:

{
  "channels": []
}

ClearNode returns empty array - no knowledge of the channel we just created.

Extended WebSocket listener timeout from 30s to 60s.

Result: ❌ Still timeout, no "cu" message

Expected Behavior

According to Nitrolite Documentation

From ClearNode API docs:

Channel Updates: For channel updates, the server sends them in these scenarios:

1. When a channel is created
2. When a channel's status changes (open, joined, closed)
3. When a channel is resized.

Individual channel updates are sent as unsolicited server messages with the "cu" method.

Expected Message:

{
  "res": [
    1234567890123,
    "cu",
    {
      "channel_id": "0x240a4b4e8e0024e024b42a8a5b6dad69e49f1ff16e6017151798f76dffc84798",
      "participant": "0x5b8fc87af470a7f7f86f7633f5019e4a24bcac9a5a22cf2d4dfc6aa72de08c23",
      "status": "open",
      "token": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
      "amount": "10000",
      "chain_id": 137,
      "adjudicator": "0x14980dF216722f14c42CA7357b06dEa7eB408b10",
      "challenge": 3600,
      "nonce": 1,
      "version": 0,
      "created_at": "2025-10-21T...",
      "updated_at": "2025-10-21T..."
    },
    1619123456789
  ],
  "sig": ["0x..."]
}

Actual Behavior: NO message received

Use Case Architecture

Our payment system relies on ClearNode's 3-layer architecture:

┌─────────────────────────────────────────────────────────┐
│                  LEDGER CHANNELS                         │
│  (On-chain Nitrolite channels for custody)              │
│  - Created via create_channel RPC + on-chain tx         │
│  - Holds USDC deposits                                   │
│  - Status: "joining" → "open"                            │
└───────────────────┬─────────────────────────────────────┘
                    │ resize_channel (allocate_amount)
                    ↓
┌─────────────────────────────────────────────────────────┐
│               UNIFIED BALANCE                            │
│  (Off-chain aggregated balance)                          │
│  - Instant transfers between users                       │
│  - No gas fees                                           │
│  - Used for Virtual App Sessions                         │
└───────────────────┬─────────────────────────────────────┘
                    │ create_app_session
                    ↓
┌─────────────────────────────────────────────────────────┐
│            VIRTUAL APP SESSIONS                          │
│  (Structured payment applications)                       │
│  - Shop payments (buyer → vendor)                        │
│  - Escrow, subscriptions, etc.                           │
└─────────────────────────────────────────────────────────┘

Blocked Step: Cannot move from Ledger Channel → Unified Balance because resize_channel fails with "channel not found"

Reproduction Steps

Prerequisites

1. Connect wallet to Polygon mainnet
2. Have USDC in wallet (minimum 0.01 USDC + gas)
3. Establish WebSocket connection to wss://clearnet.yellow.com/ws
4. Authenticate with ClearNode

Additional Context

Multiple Channel Attempts

This issue is consistent across multiple channel creation attempts:

1. Channel 1: 0x072bbb2ac30c088534919d016bed33d55d83da676f61eeec137868dddaf78080

   • Created successfully on-chain
   • Never appeared in ClearNode
   • Funds: 0.01 USDC (locked)

2. Channel 2: 0xdd8fb06fc669e7a0d552f8a681bad8208c9c5c689064d7e9bf628fc961d69f71

   • Created successfully on-chain
   • Never appeared in ClearNode
   • Funds: 0.01 USDC (locked)

3. Channel 3: 0x240a4b4e8e0024e024b42a8a5b6dad69e49f1ff16e6017151798f76dffc84798 (current)

   • Created successfully on-chain
   • Never appeared in ClearNode
   • Funds: 0.01 USDC (locked)

Pattern: 100% failure rate on channel detection/registration

ClearNode Client Implementation

Our WebSocket client wrapper:

// clearNodeClient.ts
class ClearNodeClient {
  private ws: WebSocket | null = null;
  private messageHandlers: Set<(message: any) => void> = new Set();
  private requestMap: Map<number, PendingRequest> = new Map();

  async connect({ walletAddress, signerAddress, walletClient }) {
    this.ws = new WebSocket("wss://clearnet.yellow.com/ws");

    this.ws.onopen = async () => {
      // Authenticate immediately
      const authMsg = await createAuthRequestMessage(signer, walletAddress);
      this.ws.send(authMsg);
    };

    this.ws.onmessage = (event) => {
      const message = JSON.parse(event.data);

      // Handle RPC responses
      if (message.res && Array.isArray(message.res)) {
        const reqId = message.res[0];
        const pending = this.requestMap.get(reqId);
        if (pending) {
          pending.resolve(message.res[2]); // Response data
          this.requestMap.delete(reqId);
        }

        // ALSO notify all registered handlers (for unsolicited messages like "cu")
        this.messageHandlers.forEach((handler) => handler(message));
      }
    };
  }

  onMessage(handler: (message: any) => void): () => void {
    this.messageHandlers.add(handler);
    return () => this.messageHandlers.delete(handler); // Unsubscribe function
  }

  async sendRequest(message: string): Promise<any> {
    const parsed = JSON.parse(message);
    const reqId = parsed.req[0];

    return new Promise((resolve, reject) => {
      const timeout = setTimeout(() => {
        this.requestMap.delete(reqId);
        reject(new Error("Request timeout"));
      }, 30000);

      this.requestMap.set(reqId, { resolve, reject, timeout });
      this.ws.send(message);
    });
  }
}

Any help would be greatly appreciated! We're blocked on implementing our payment system for the project and need to understand why channels aren't being registered by ClearNode despite successful on-chain creation.

System Information

• Node.js: v20.x
• TypeScript: 5.x
• Next.js: 14.x
• Viem: 2.30.5 and 2.38.3
• @erc7824/nitrolite: 2.x (latest from npm)
• Browser: Chrome 130.x
• Wallet Type: Dynamic Embedded Wallet

---

Thank you for your time and assistance! 🙏

[nksazonov]

@a-singh09 , thanks for such a detailed report!
We are investigating the issue. In the meantime, I have noticed something strange: you specify that the @erc7824/nitrolite SDK you use is 2.x and that it is latest, although the latest version now is 0.4.0: nitrolite sdk npm page.
Could you verify the version you use, please?

[a-singh09]

@nksazonov Thanks for the quick reply!
Actually we're using @erc7824/nitrolite": "0.4.0", the version written in the message seems to be typo which I've fixed now.

[nksazonov]

@a-singh09 We have identified the issue.
The problem is that for the channel creation the tx sender ("the wallet") and channel participant specified on your behalf ("the signer" / "the session key") must be different. You can read more about "wallet-signer" restrictions here. These restrictions are true for all operations, not only Authentication (we will change that in the docs).

As you are specifying the wallet and the session key to be equal in the create channel request, the Clearnode should have denied signing your request. However, this check is missing in the handler, thus you got the response and sent a create(...) tx, which emitted the Created(...) event. Still, the Created(...) event handler saw that you had specified equal wallet and session key addresses, and denied adding a channel to its DB. This is why you are getting a silent error.

We will add the missing check in the next patch. Then your current code should be failing.

[a-singh09]

@nksazonov Thanks, the channels creation issue has been resolved.