0
# Sign Client Interface
1

2
Main client interface and engine types for WalletConnect sign operations including connection establishment, session management, and JSON-RPC communication.
3

4
## Capabilities
5

6
### Sign Client Interface
7

8
Main client interface providing high-level API for WalletConnect sign operations and session lifecycle management.
9

10
```typescript { .api }
11
/**
12
 * Main sign client interface with session management capabilities
13
 * Provides the primary API for WalletConnect sign operations
14
 */
15
interface ISignClient extends IEvents {
16
  /** Client metadata for identification */
17
  readonly metadata: CoreTypes.Metadata;
18
  /** Protocol identifier */
19
  readonly protocol: string;
20
  /** Protocol version */
21
  readonly version: number;
22
  /** Core protocol instance */
23
  readonly core: ICore;
24
  /** Logger instance */
25
  readonly logger: ILogger;
26
  /** Event emitter */
27
  readonly events: EventEmitter;
28
  /** Engine instance for session management */
29
  readonly engine: IEngine;
30
  /** Session store */
31
  readonly session: ISession;
32
  /** Proposal store */
33
  readonly proposal: IProposal;
34
  /** Pending request store */
35
  readonly pendingRequest: IPendingRequest;
36
  /** Authentication interface */
37
  readonly auth: IAuth;
38

39
  /** Initiate a new session connection */
40
  connect(params?: SignClientTypes.ConnectParams): Promise<{ 
41
    uri?: string; 
42
    approval(): Promise<SessionTypes.Struct>; 
43
  }>;
44
  /** Pair with a peer using URI */
45
  pair(params: { uri: string }): Promise<PairingTypes.Struct>;
46
  /** Approve a session proposal */
47
  approve(params: {
48
    id: number;
49
    namespaces: SessionTypes.Namespaces;
50
    sessionProperties?: ProposalTypes.SessionProperties;
51
  }): Promise<SessionTypes.Struct>;
52
  /** Reject a session proposal */
53
  reject(params: { id: number; reason: ErrorResponse }): Promise<void>;
54
  /** Update session namespaces */
55
  update(params: { topic: string; namespaces: SessionTypes.Namespaces }): Promise<void>;
56
  /** Extend session expiry */
57
  extend(params: { topic: string }): Promise<void>;
58
  /** Send a request to peer */
59
  request(params: { 
60
    topic: string; 
61
    request: RequestArguments; 
62
    chainId: string 
63
  }): Promise<any>;
64
  /** Respond to a peer request */
65
  respond(params: { topic: string; response: JsonRpcResponse }): Promise<void>;
66
  /** Ping peer connection */
67
  ping(params: { topic: string }): Promise<void>;
68
  /** Emit an event to peer */
69
  emit(params: { 
70
    topic: string; 
71
    event: SessionTypes.EventArguments; 
72
    chainId: string 
73
  }): Promise<void>;
74
  /** Disconnect from session */
75
  disconnect(params: { topic: string; reason: ErrorResponse }): Promise<void>;
76
  /** Find sessions matching criteria */
77
  find(params: { 
78
    requiredNamespaces: ProposalTypes.RequiredNamespaces 
79
  }): SessionTypes.Struct[];
80
}
81
```
82

83
### Sign Client Configuration
84

85
Configuration types and options for initializing sign client instances.
86

87
```typescript { .api }
88
namespace SignClientTypes {
89
  /**
90
   * All sign client event types
91
   */
92
  type Event = 
93
    | "session_proposal"
94
    | "session_update" 
95
    | "session_extend"
96
    | "session_ping"
97
    | "session_delete"
98
    | "session_expire"
99
    | "session_request"
100
    | "session_request_sent"
101
    | "session_event"
102
    | "proposal_expire"
103
    | "session_authenticate";
104

105
  /**
106
   * Base event arguments structure
107
   */
108
  interface BaseEventArgs<T = {}> {
109
    id: number;
110
    topic: string;
111
    params: T;
112
  }
113

114
  /**
115
   * Event arguments for all sign client events
116
   */
117
  interface EventArguments {
118
    session_proposal: Omit<BaseEventArgs<{
119
      id: number;
120
      pairingTopic: string;
121
      expiry: number;
122
      relays: RelayerTypes.ProtocolOptions[];
123
      proposer: SessionTypes.Participant;
124
      requiredNamespaces: ProposalTypes.RequiredNamespaces;
125
      optionalNamespaces?: ProposalTypes.OptionalNamespaces;
126
      sessionProperties?: ProposalTypes.SessionProperties;
127
    }>, "topic">;
128
    session_update: BaseEventArgs<{ namespaces: SessionTypes.Namespaces }>;
129
    session_extend: BaseEventArgs<{}>;
130
    session_ping: BaseEventArgs<{}>;
131
    session_delete: BaseEventArgs<{ code: number; message: string }>;
132
    session_expire: { topic: string };
133
    session_request: BaseEventArgs<{ 
134
      request: { method: string; params: any }; 
135
      chainId: string;
136
    }>;
137
    session_request_sent: { 
138
      request: { method: string; params: any };
139
      topic: string;
140
      chainId: string;
141
      id: number;
142
    };
143
    session_event: BaseEventArgs<{ 
144
      event: { name: string; data: any }; 
145
      chainId: string;
146
    }>;
147
    proposal_expire: { id: number };
148
    session_authenticate: AuthTypes.SessionAuthenticateRequest;
149
  }
150

151
  /**
152
   * Client metadata type (alias for CoreTypes.Metadata)
153
   */
154
   type Metadata = CoreTypes.Metadata;
155

156
  /**
157
   * Sign client configuration options
158
   */
159
  interface SignConfig {
160
    /** Project ID for WalletConnect Cloud */
161
    projectId: string;
162
    /** Custom relay URL (optional) */
163
    relayUrl?: string;
164
    /** Client metadata */
165
    metadata: Metadata;
166
    /** Custom storage implementation (optional) */
167
    storage?: IKeyValueStorage;
168
    /** Custom logger (optional) */
169
    logger?: string | ILogger;
170
  }
171

172
  /**
173
   * Sign client initialization options
174
   */
175
  interface Options extends SignConfig {
176
    /** Custom core instance (optional) */
177
    core?: ICore;
178
    /** Custom name for client (optional) */
179
    name?: string;
180
  }
181

182
  /**
183
   * Connection parameters for initiating sessions
184
   */
185
  interface ConnectParams {
186
    /** Required namespaces for the session */
187
    requiredNamespaces: ProposalTypes.RequiredNamespaces;
188
    /** Optional namespaces for the session */
189
    optionalNamespaces?: ProposalTypes.OptionalNamespaces;
190
    /** Custom session properties */
191
    sessionProperties?: ProposalTypes.SessionProperties;
192
    /** Existing pairing topic (optional) */
193
    pairingTopic?: string;
194
  }
195
}
196

197
/**
198
 * Sign client event emitter interface
199
 */
200
interface ISignClientEvents extends IEvents {
201
  on<E extends SignClientTypes.Event>(
202
    event: E, 
203
    listener: (args: SignClientTypes.EventArguments[E]) => void
204
  ): this;
205
  
206
  once<E extends SignClientTypes.Event>(
207
    event: E, 
208
    listener: (args: SignClientTypes.EventArguments[E]) => void
209
  ): this;
210
  
211
  off<E extends SignClientTypes.Event>(
212
    event: E, 
213
    listener: (args: SignClientTypes.EventArguments[E]) => void
214
  ): this;
215
  
216
  removeAllListeners<E extends SignClientTypes.Event>(event?: E): this;
217
  
218
  emit<E extends SignClientTypes.Event>(
219
    event: E, 
220
    args: SignClientTypes.EventArguments[E]
221
  ): boolean;
222
}
223
```
224

225
### Engine Interface
226

227
Core engine interface handling session lifecycle, requests, and protocol operations.
228

229
```typescript { .api }
230
/**
231
 * Main engine interface for session lifecycle management
232
 * Handles the core protocol operations and state management
233
 */
234
interface IEngine extends IEvents {
235
  readonly name: string;
236
  readonly context: string;
237
  readonly client: ISignClient;
238
  readonly signClient: ISignClient;
239

240
  /** Initialize the engine */
241
  init(): Promise<void>;
242
  /** Connect to a peer and create session */
243
  connect(params?: EngineTypes.ConnectParams): Promise<{ uri?: string; approval(): Promise<SessionTypes.Struct> }>;
244
  /** Pair with a peer using URI */
245
  pair(params: EngineTypes.PairParams): Promise<PairingTypes.Struct>;
246
  /** Approve a session proposal */
247
  approve(params: EngineTypes.ApproveParams): Promise<SessionTypes.Struct>;
248
  /** Reject a session proposal */
249
  reject(params: EngineTypes.RejectParams): Promise<void>;
250
  /** Update an existing session */
251
  update(params: EngineTypes.UpdateParams): Promise<void>;
252
  /** Extend session expiry */
253
  extend(params: EngineTypes.ExtendParams): Promise<void>;
254
  /** Send a request to the peer */
255
  request(params: EngineTypes.RequestParams): Promise<any>;
256
  /** Respond to a peer request */
257
  respond(params: EngineTypes.RespondParams): Promise<void>;
258
  /** Ping the peer */
259
  ping(params: EngineTypes.PingParams): Promise<void>;
260
  /** Emit an event to the peer */
261
  emit(params: EngineTypes.EmitParams): Promise<void>;
262
  /** Disconnect from a session */
263
  disconnect(params: EngineTypes.DisconnectParams): Promise<void>;
264
  /** Find sessions matching criteria */
265
  find(params: { requiredNamespaces: ProposalTypes.RequiredNamespaces }): SessionTypes.Struct[];
266
  /** Get active pairings */
267
  getPairings(): PairingTypes.Struct[];
268
  /** Get active sessions */
269
  getActiveSessions(): Record<string, SessionTypes.Struct>;
270
  /** Get pending session proposals */
271
  getPendingSessionProposals(): Record<number, ProposalTypes.Struct>;
272
  /** Get pending session requests */
273
  getPendingSessionRequests(): PendingRequestTypes.Struct[];
274
}
275

276
/**
277
 * Engine event emitter interface
278
 */
279
interface IEngineEvents extends IEvents {
280
  on<E extends EngineTypes.Event>(
281
    event: E,
282
    listener: (args: EngineTypes.EventArguments[E]) => void
283
  ): this;
284
}
285

286
/**
287
 * Private engine methods for internal operations
288
 */
289
interface EnginePrivate {
290
  /** Private session management methods */
291
  sendRequest<T>(params: EngineTypes.RequestParams): Promise<T>;
292
  sendResult(params: EngineTypes.RespondParams): Promise<void>;
293
  sendError(id: number, topic: string, error: ErrorResponse): Promise<void>;
294
}
295
```
296

297
### Engine Types and Parameters
298

299
Parameter types and configurations for engine operations including requests, responses, and session management.
300

301
```typescript { .api }
302
namespace EngineTypes {
303
  /**
304
   * Engine event types
305
   */
306
  type Event = SignClientTypes.Event;
307

308
  /**
309
   * Engine event argument types
310
   */
311
  interface EventArguments extends SignClientTypes.EventArguments {}
312

313
  /**
314
   * URI parsing parameters
315
   */
316
  interface UriParameters {
317
    /** Protocol version */
318
    protocol: string;
319
    /** Protocol version number */
320
    version: number;
321
    /** Pairing topic */
322
    topic: string;
323
    /** Symmetric key */
324
    symKey: string;
325
    /** Relay protocol */
326
    relay: RelayerTypes.ProtocolOptions;
327
    /** Optional expiry timestamp */
328
    expiry?: number;
329
  }
330

331
  /**
332
   * Engine event callback structure
333
   */
334
  interface EventCallback<T = any> {
335
    resolve: (value: T) => void;
336
    reject: (reason: any) => void;
337
  }
338

339
  /**
340
   * Connection parameters for engine
341
   */
342
  interface ConnectParams extends SignClientTypes.ConnectParams {}
343

344
  /**
345
   * Pairing parameters
346
   */
347
  interface PairParams {
348
    /** Pairing URI */
349
    uri: string;
350
  }
351

352
  /**
353
   * Approval parameters
354
   */
355
  interface ApproveParams {
356
    /** Proposal ID */
357
    id: number;
358
    /** Approved namespaces */
359
    namespaces: SessionTypes.Namespaces;
360
    /** Optional session properties */
361
    sessionProperties?: ProposalTypes.SessionProperties;
362
  }
363

364
  /**
365
   * Rejection parameters
366
   */
367
  interface RejectParams {
368
    /** Proposal ID */
369
    id: number;
370
    /** Rejection reason */
371
    reason: ErrorResponse;
372
  }
373

374
  /**
375
   * Update parameters
376
   */
377
  interface UpdateParams {
378
    /** Session topic */
379
    topic: string;
380
    /** Updated namespaces */
381
    namespaces: SessionTypes.Namespaces;
382
  }
383

384
  /**
385
   * Extension parameters
386
   */
387
  interface ExtendParams {
388
    /** Session topic */
389
    topic: string;
390
  }
391

392
  /**
393
   * Request parameters
394
   */
395
  interface RequestParams {
396
    /** Session topic */
397
    topic: string;
398
    /** JSON-RPC request */
399
    request: RequestArguments;
400
    /** Target chain ID */
401
    chainId: string;
402
    /** Request expiry (optional) */
403
    expiry?: number;
404
  }
405

406
  /**
407
   * Response parameters
408
   */
409
  interface RespondParams {
410
    /** Session topic */
411
    topic: string;
412
    /** JSON-RPC response */
413
    response: JsonRpcResponse;
414
  }
415

416
  /**
417
   * Event emission parameters
418
   */
419
  interface EmitParams {
420
    /** Session topic */
421
    topic: string;
422
    /** Event to emit */
423
    event: SessionTypes.EventArguments;
424
    /** Target chain ID */
425
    chainId: string;
426
  }
427

428
  /**
429
   * Ping parameters
430
   */
431
  interface PingParams {
432
    /** Session topic */
433
    topic: string;
434
  }
435

436
  /**
437
   * Disconnection parameters
438
   */
439
  interface DisconnectParams {
440
    /** Session topic */
441
    topic: string;
442
    /** Disconnection reason */
443
    reason: ErrorResponse;
444
  }
445

446
  /**
447
   * Session finding parameters
448
   */
449
  interface FindParams {
450
    /** Required namespaces to match */
451
    requiredNamespaces: ProposalTypes.RequiredNamespaces;
452
  }
453

454
  /**
455
   * Promise with acknowledgment callback
456
   */
457
  type AcknowledgedPromise<T> = Promise<T> & {
458
    acknowledged: () => Promise<SessionTypes.Struct>;
459
  };
460

461
  /**
462
   * Authentication response promise structure
463
   */
464
  interface SessionAuthenticateResponsePromise {
465
    /** Authentication response promise */
466
    response: Promise<SessionTypes.Struct>;
467
    /** Acknowledgment callback */
468
    acknowledged: () => Promise<SessionTypes.Struct>;
469
  }
470

471
  /**
472
   * RPC options structure
473
   */
474
  interface RpcOpts {
475
    /** Request TTL in milliseconds */
476
    ttl: number;
477
    /** Whether to prompt user */
478
    prompt: boolean;
479
    /** Request tag */
480
    tag: number;
481
  }
482

483
  /**
484
   * RPC options mapping
485
   */
486
  type RpcOptsMap = Record<string, RpcOpts>;
487

488
  /**
489
   * Engine queue structure for managing operations
490
   */
491
  interface EngineQueue {
492
    /** Queue state */
493
    state: "IDLE" | "ACTIVE";
494
    /** Queued operations */
495
    queue: Array<() => Promise<void>>;
496
  }
497
}
498
```
499

500
**Usage Examples:**
501

502
```typescript
503
import { ISignClient, SignClientTypes, EngineTypes } from "@walletconnect/types";
504

505
// Initialize sign client
506
const signClient: ISignClient = await SignClient.init({
507
  projectId: "your_project_id",
508
  metadata: {
509
    name: "Example dApp",
510
    description: "An example dApp using WalletConnect",
511
    url: "https://example.com",
512
    icons: ["https://example.com/icon.png"]
513
  }
514
});
515

516
// Connect to wallet
517
const connectParams: SignClientTypes.ConnectParams = {
518
  requiredNamespaces: {
519
    eip155: {
520
      methods: ["eth_sendTransaction", "personal_sign"],
521
      chains: ["eip155:1"],
522
      events: ["chainChanged", "accountsChanged"]
523
    }
524
  }
525
};
526

527
const { uri, approval } = await signClient.connect(connectParams);
528

529
// Handle session approval
530
approval().then((session) => {
531
  console.log("Session approved:", session);
532
});
533

534
// Send a request
535
const result = await signClient.request({
536
  topic: session.topic,
537
  chainId: "eip155:1",
538
  request: {
539
    method: "personal_sign",
540
    params: ["0x48656c6c6f20576f726c64", account]
541
  }
542
});
543
```