0
# Relay Communication
1

2
Relay protocol types for message routing, subscription management, and network communication in the WalletConnect infrastructure including pairing and message handling.
3

4
## Capabilities
5

6
### Relayer Interface
7

8
Main relay interface for message routing and network communication throughout the WalletConnect protocol.
9

10
```typescript { .api }
11
/**
12
 * Main relay interface extending IEvents for message routing
13
 * Handles all network communication in the WalletConnect protocol
14
 */
15
interface IRelayer extends IEvents {
16
  /** Core protocol instance */
17
  readonly core: ICore;
18
  /** Logger instance */
19
  readonly logger: ILogger;
20
  /** Event emitter */
21
  readonly events: EventEmitter;
22
  /** JSON-RPC provider for relay communication */
23
  readonly provider: JsonRpcProvider;
24
  /** Message tracking interface */
25
  readonly messages: IMessageTracker;
26
  /** Subscription management interface */
27
  readonly subscriber: ISubscriber;
28
  /** Publishing interface */
29
  readonly publisher: IPublisher;
30
  /** Whether transport was explicitly closed */
31
  readonly transportExplicitlyClosed: boolean;
32

33
  /** Initialize the relayer */
34
  init(): Promise<void>;
35
  /** Publish message to topic */
36
  publish(topic: string, message: string, opts?: RelayerTypes.PublishOptions): Promise<void>;
37
  /** Subscribe to topic for incoming messages */
38
  subscribe(topic: string, opts?: RelayerTypes.SubscribeOptions): Promise<string>;
39
  /** Unsubscribe from topic */
40
  unsubscribe(topic: string, opts?: RelayerTypes.UnsubscribeOptions): Promise<void>;
41
}
42
```
43

44
### Relay Configuration
45

46
Configuration types and protocol options for relay initialization and operation.
47

48
```typescript { .api }
49
namespace RelayerTypes {
50
  /**
51
   * Relay protocol configuration
52
   */
53
  interface ProtocolOptions {
54
    /** Protocol name (e.g., "irn") */
55
    protocol: string;
56
    /** Optional protocol-specific data */
57
    data?: string;
58
  }
59

60
  /**
61
   * Transport method options for communication
62
   */
63
  type TransportType = "relay" | "link_mode";
64

65
  /**
66
   * Message publishing options with TTL, tags, and attestation
67
   */
68
  interface PublishOptions {
69
    /** Relay protocol options */
70
    relay?: ProtocolOptions;
71
    /** Time-to-live in seconds */
72
    ttl?: number;
73
    /** Whether to prompt user for confirmation */
74
    prompt?: boolean;
75
    /** Message tag for categorization */
76
    tag?: number;
77
    /** Request ID for tracking */
78
    id?: number;
79
    /** Attestation string for verification */
80
    attestation?: string;
81
  }
82

83
  /**
84
   * Subscription options for topics
85
   */
86
  interface SubscribeOptions {
87
    /** Relay protocol options */
88
    relay?: ProtocolOptions;
89
  }
90

91
  /**
92
   * Unsubscription options
93
   */
94
  interface UnsubscribeOptions {
95
    /** Unsubscription ID */
96
    id?: string;
97
    /** Relay protocol options */
98
    relay?: ProtocolOptions;
99
  }
100

101
  /**
102
   * Union of all request option types
103
   */
104
  type RequestOptions = PublishOptions | SubscribeOptions | UnsubscribeOptions;
105

106
  /**
107
   * Message direction for tracking
108
   */
109
  type MessageDirection = "inbound" | "outbound";
110
}
111
```
112

113
### Message Handling
114

115
Message structures and events for relay communication including payloads and message tracking.
116

117
```typescript { .api }
118
namespace RelayerTypes {
119
  /**
120
   * Payload structure for publishing messages
121
   */
122
  interface PublishPayload {
123
    /** Message topic */
124
    topic: string;
125
    /** Message content */
126
    message: string;
127
    /** Publishing options */
128
    opts?: PublishOptions;
129
  }
130

131
  /**
132
   * Incoming message event structure
133
   */
134
  interface MessageEvent {
135
    /** Message topic */
136
    topic: string;
137
    /** Message content */
138
    message: string;
139
    /** Publication timestamp */
140
    publishedAt: number;
141
    /** Optional attestation for verification */
142
    attestation?: string;
143
  }
144

145
  /**
146
   * RPC URL construction parameters
147
   */
148
  interface RpcUrlParams {
149
    /** WalletConnect Cloud project ID */
150
    projectId: string;
151
    /** Relay URL */
152
    relayUrl: string;
153
    /** SDK version */
154
    sdkVersion: string;
155
    /** Authentication token (optional) */
156
    auth?: string;
157
    /** User agent string (optional) */
158
    userAgent?: string;
159
  }
160

161
  /**
162
   * Transaction verification framework parameters
163
   */
164
  interface ITVF {
165
    /** Verification URL */
166
    url: string;
167
    /** Validation type */
168
    validation: string;
169
  }
170
}
171

172
/**
173
 * Relayer initialization options
174
 */
175
interface RelayerOptions {
176
  /** Core protocol instance */
177
  core: ICore;
178
  /** Logger instance */
179
  logger: ILogger;
180
  /** Relay URL */
181
  relayUrl: string;
182
  /** WalletConnect Cloud project ID */
183
  projectId: string;
184
}
185

186
/**
187
 * Client metadata for relayer identification
188
 */
189
interface RelayerClientMetadata {
190
  /** Protocol name */
191
  protocol: string;
192
  /** Protocol version */
193
  version: number;
194
  /** Environment (e.g., "browser", "react-native") */
195
  env: string;
196
  /** Host information (optional) */
197
  host?: string;
198
}
199
```
200

201
### Publisher Interface
202

203
Message publishing interface for sending messages through the relay network.
204

205
```typescript { .api }
206
/**
207
 * Message publishing interface extending IEvents
208
 * Handles outbound message transmission
209
 */
210
interface IPublisher extends IEvents {
211
  readonly name: string;
212
  readonly context: string;
213

214
  /** Publish message to topic */
215
  publish(topic: string, message: string, opts?: PublisherTypes.Params): Promise<void>;
216
}
217

218
namespace PublisherTypes {
219
  /**
220
   * Publishing parameters with topic, message, and options
221
   */
222
  interface Params {
223
    /** Target topic */
224
    topic: string;
225
    /** Message content */
226
    message: string;
227
    /** Publishing options */
228
    opts?: RelayerTypes.PublishOptions;
229
  }
230
}
231
```
232

233
### Subscriber Interface
234

235
Subscription management interface for receiving messages from the relay network.
236

237
```typescript { .api }
238
/**
239
 * Subscription management interface extending IEvents
240
 * Handles topic subscriptions and message receipt
241
 */
242
interface ISubscriber extends IEvents {
243
  readonly name: string;
244
  readonly context: string;
245
  readonly logger: ILogger;
246
  readonly subscription: ISubscriberTopicMap;
247

248
  /** Initialize subscriber */
249
  init(): Promise<void>;
250
  /** Subscribe to topic */
251
  subscribe(topic: string, opts?: SubscriberTypes.Params): Promise<string>;
252
  /** Unsubscribe from topic with optional ID */
253
  unsubscribe(topic: string, opts?: { id?: string }): Promise<void>;
254
  /** Check if subscribed to topic */
255
  isSubscribed(topic: string): boolean;
256
}
257

258
namespace SubscriberTypes {
259
  /**
260
   * Subscription parameters extending relay options
261
   */
262
  interface Params extends RelayerTypes.SubscribeOptions {
263
    /** Relay protocol options */
264
    relay?: RelayerTypes.ProtocolOptions;
265
  }
266

267
  /**
268
   * Active subscription with ID
269
   */
270
  interface Active {
271
    /** Subscription topic */
272
    topic: string;
273
    /** Subscription ID */
274
    id: string;
275
  }
276
}
277

278
namespace SubscriberEvents {
279
  /**
280
   * Created subscription event
281
   */
282
  type Created = SubscriberTypes.Active;
283

284
  /**
285
   * Deleted subscription event with reason
286
   */
287
  interface Deleted extends SubscriberTypes.Active {
288
    /** Deletion reason */
289
    reason: string;
290
  }
291

292
  /**
293
   * Expired subscription event
294
   */
295
  type Expired = SubscriberTypes.Active;
296
}
297

298
/**
299
 * Topic-to-subscription mapping interface
300
 */
301
interface ISubscriberTopicMap extends IEvents {
302
  readonly map: Map<string, string>;
303

304
  /** Check if topic exists */
305
  exists(topic: string, id: string): boolean;
306
  /** Set topic mapping */
307
  set(topic: string, id: string): void;
308
  /** Get subscription ID for topic */
309
  get(topic: string): string;
310
  /** Delete topic mapping */
311
  delete(topic: string, id: string): void;
312
  /** Clear all mappings */
313
  clear(): void;
314
}
315
```
316

317
### Pairing Management
318

319
Pairing types and interfaces for establishing connections between clients.
320

321
```typescript { .api }
322
/**
323
 * Pairing management interface for creating, managing, and querying pairings
324
 */
325
interface IPairing extends IEvents {
326
  readonly core: ICore;
327
  readonly logger: ILogger;
328
  readonly events: EventEmitter;
329
  readonly pairings: IPairingStore;
330

331
  /** Initialize pairing module */
332
  init(): Promise<void>;
333
  /** Create new pairing */
334
  create(): Promise<PairingTypes.Struct>;
335
  /** Pair using URI */
336
  pair(params: { uri: string; activatePairing?: boolean }): Promise<PairingTypes.Struct>;
337
  /** Activate existing pairing */
338
  activate(params: { topic: string }): Promise<void>;
339
  /** Register pairing */
340
  register(params: { topic: string; peerMetadata: CoreTypes.Metadata; relay: RelayerTypes.ProtocolOptions }): Promise<PairingTypes.Struct>;
341
  /** Update pairing metadata */
342
  update(params: { topic: string; metadata: CoreTypes.Metadata }): Promise<void>;
343
  /** Ping pairing */
344
  ping(params: { topic: string }): Promise<void>;
345
  /** Disconnect pairing */
346
  disconnect(params: { topic: string }): Promise<void>;
347
  /** Get pairing by topic */
348
  getPairings(): PairingTypes.Struct[];
349
}
350

351
/**
352
 * Private pairing methods for internal operations
353
 */
354
interface IPairingPrivate {
355
  sendRequest<T>(params: { topic: string; method: string; params: any; ttl?: number }): Promise<T>;
356
  sendResult(params: { id: number; topic: string; result: any; throwOnFailedPublish?: boolean }): Promise<void>;
357
  sendError(params: { id: number; topic: string; error: ErrorResponse }): Promise<void>;
358
}
359

360
namespace PairingTypes {
361
  /**
362
   * Pairing structure with topic, expiry, relay options, and metadata
363
   */
364
  interface Struct {
365
    /** Pairing topic */
366
    topic: string;
367
    /** Pairing expiry timestamp */
368
    expiry: number;
369
    /** Relay protocol options */
370
    relay: RelayerTypes.ProtocolOptions;
371
    /** Whether pairing is active */
372
    active: boolean;
373
    /** Peer metadata (optional) */
374
    peerMetadata?: CoreTypes.Metadata;
375
  }
376
}
377

378
namespace PairingJsonRpcTypes {
379
  /**
380
   * Standard pairing response type
381
   */
382
  type DefaultResponse = true;
383

384
  /**
385
   * Pairing method names for JSON-RPC communication
386
   */
387
  type WcMethod = "wc_pairingDelete" | "wc_pairingPing";
388

389
  /**
390
   * Pairing error response type
391
   */
392
  type Error = ErrorResponse;
393

394
  /**
395
   * Request parameters for pairing methods
396
   */
397
  interface RequestParams {
398
    wc_pairingDelete: { code: number; message: string };
399
    wc_pairingPing: {};
400
  }
401

402
  /**
403
   * Response results for pairing methods
404
   */
405
  interface Results {
406
    wc_pairingDelete: DefaultResponse;
407
    wc_pairingPing: DefaultResponse;
408
  }
409

410
  /**
411
   * Event callback structure for pairing
412
   */
413
  interface EventCallback<T = any> {
414
    resolve: (value: T) => void;
415
    reject: (reason: any) => void;
416
  }
417
}
418

419
/**
420
 * Store interface for pairing data
421
 */
422
type IPairingStore = IStore<PairingTypes.Struct>;
423
```
424

425
### Message Tracker Interface
426

427
Message tracking interface for managing message acknowledgments and delivery status.
428

429
```typescript { .api }
430
interface IMessageTracker extends IEvents {
431
  readonly name: string;
432
  readonly context: string;
433
  readonly map: Map<string, MessageRecord>;
434

435
  init(): Promise<void>;
436
  set(topic: string, message: string): Promise<void>;
437
  get(topic: string): MessageRecord | undefined;
438
  has(topic: string): boolean;
439
  delete(topic: string): Promise<void>;
440
  clear(): Promise<void>;
441
  on(event: MessageTrackerTypes.Event, listener: (args: MessageTrackerTypes.EventArguments[MessageTrackerTypes.Event]) => void): this;
442
  once(event: MessageTrackerTypes.Event, listener: (args: MessageTrackerTypes.EventArguments[MessageTrackerTypes.Event]) => void): this;
443
  off(event: MessageTrackerTypes.Event, listener: (args: MessageTrackerTypes.EventArguments[MessageTrackerTypes.Event]) => void): this;
444
  removeAllListeners(event?: MessageTrackerTypes.Event): this;
445
}
446

447
namespace MessageTrackerTypes {
448
  interface MessageRecord {
449
    topic: string;
450
    message: string;
451
    publishedAt: number;
452
    transportType: RelayerTypes.TransportType;
453
  }
454

455
  type Event = "message_ack" | "message_delivered";
456

457
  interface EventArguments {
458
    message_ack: {
459
      topic: string;
460
      message: string;
461
      publishedAt: number;
462
    };
463
    message_delivered: {
464
      topic: string;
465
      message: string;
466
      publishedAt: number;
467
    };
468
  }
469
}
470
```
471

472
### Publisher Interface
473

474
Message publishing interface for sending messages through the relay network.
475

476
```typescript { .api }
477
interface IPublisher extends IEvents {
478
  readonly name: string;
479
  readonly context: string;
480
  readonly queue: Map<string, any>;
481

482
  init(): Promise<void>;
483
  publish(topic: string, message: string, opts?: PublisherTypes.PublishOptions): Promise<number>;
484
  on(event: PublisherTypes.Event, listener: (args: PublisherTypes.EventArguments[PublisherTypes.Event]) => void): this;
485
  once(event: PublisherTypes.Event, listener: (args: PublisherTypes.EventArguments[PublisherTypes.Event]) => void): this;
486
  off(event: PublisherTypes.Event, listener: (args: PublisherTypes.EventArguments[PublisherTypes.Event]) => void): this;
487
  removeAllListeners(event?: PublisherTypes.Event): this;
488
}
489

490
namespace PublisherTypes {
491
  interface PublishOptions {
492
    relay?: RelayerTypes.ProtocolOptions;
493
    ttl?: number;
494
    prompt?: boolean;
495
    tag?: number;
496
    id?: number;
497
    attestation?: string;
498
  }
499

500
  type Event = "publisher_publish";
501

502
  interface EventArguments {
503
    publisher_publish: {
504
      topic: string;
505
      message: string;
506
      publishedAt: number;
507
      transportType: RelayerTypes.TransportType;
508
    };
509
  }
510
}
511
```
512

513
### Subscriber Interface
514

515
Message subscription interface for receiving messages from the relay network.
516

517
```typescript { .api }
518
interface ISubscriber extends IEvents {
519
  readonly name: string;
520
  readonly context: string;
521
  readonly pending: Map<string, any>;
522
  readonly cached: string[];
523
  readonly initialized: boolean;
524

525
  init(): Promise<void>;
526
  subscribe(topic: string, opts?: SubscriberTypes.SubscribeOptions): Promise<string>;
527
  unsubscribe(topic: string, opts?: SubscriberTypes.UnsubscribeOptions): Promise<void>;
528
  isSubscribed(topic: string): boolean;
529
  on(event: SubscriberTypes.Event, listener: (args: SubscriberTypes.EventArguments[SubscriberTypes.Event]) => void): this;
530
  once(event: SubscriberTypes.Event, listener: (args: SubscriberTypes.EventArguments[SubscriberTypes.Event]) => void): this;
531
  off(event: SubscriberTypes.Event, listener: (args: SubscriberTypes.EventArguments[SubscriberTypes.Event]) => void): this;
532
  removeAllListeners(event?: SubscriberTypes.Event): this;
533
}
534

535
namespace SubscriberTypes {
536
  interface SubscribeOptions {
537
    relay?: RelayerTypes.ProtocolOptions;
538
  }
539

540
  interface UnsubscribeOptions {
541
    id?: string;
542
    relay?: RelayerTypes.ProtocolOptions;
543
  }
544

545
  type Event = "subscriber_subscription" | "subscriber_message" | "subscriber_ping" | "subscriber_disconnect" | "subscriber_connection_stalled";
546

547
  interface EventArguments {
548
    subscriber_subscription: {
549
      id: string;
550
      topic: string;
551
    };
552
    subscriber_message: RelayerTypes.MessageEvent;
553
    subscriber_ping: {};
554
    subscriber_disconnect: {};
555
    subscriber_connection_stalled: {};
556
  }
557
}
558
```
559

560
**Usage Examples:**
561

562
```typescript
563
import { IRelayer, RelayerTypes, IPairing, PairingTypes } from "@walletconnect/types";
564

565
// Publish a message to relay
566
const publishOptions: RelayerTypes.PublishOptions = {
567
  relay: { protocol: "irn" },
568
  ttl: 300, // 5 minutes
569
  prompt: true,
570
  tag: 1100
571
};
572

573
await relayer.publish("session_topic", JSON.stringify(payload), publishOptions);
574

575
// Subscribe to topic for incoming messages
576
const subscriptionId = await relayer.subscribe("session_topic", {
577
  relay: { protocol: "irn" }
578
});
579

580
// Create a pairing
581
const pairing: PairingTypes.Struct = await pairing.create();
582
console.log("Pairing topic:", pairing.topic);
583

584
// Pair using URI
585
const existingPairing = await pairing.pair({ 
586
  uri: "wc:abc123@2?relay-protocol=irn&symKey=def456" 
587
});
588

589
// Handle incoming messages
590
relayer.on("relayer_message", (event: RelayerTypes.MessageEvent) => {
591
  console.log("Received message on topic:", event.topic);
592
  console.log("Message content:", event.message);
593
  console.log("Published at:", event.publishedAt);
594
});
595
```