0
# WalletConnect Types
1

2
WalletConnect Types provides comprehensive TypeScript type definitions and interfaces for the WalletConnect Protocol v2, a decentralized protocol for connecting wallets to decentralized applications (dApps). This package serves as the foundational typing layer for WalletConnect's ecosystem, enabling type-safe development across all WalletConnect implementations.
3

4
## Package Information
5

6
- **Package Name**: @walletconnect/types
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @walletconnect/types`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  // Core types
16
  ICore, CoreTypes, ICrypto, CryptoTypes,
17
  // Sign client types  
18
  ISignClient, SignClientTypes, SessionTypes,
19
  // Engine and protocol types
20
  IEngine, EngineTypes, JsonRpcTypes,
21
  // Communication interfaces
22
  IRelayer, RelayerTypes, IPairing, PairingTypes,
23
  IPublisher, ISubscriber, IMessageTracker,
24
  // Storage and utility interfaces
25
  IExpirer, IKeyChain, IVerify, IEchoClient, IEventClient,
26
  // Additional type namespaces
27
  PublisherTypes, SubscriberTypes, PendingRequestTypes,
28
  ProposalTypes, AuthTypes
29
} from "@walletconnect/types";
30
```
31

32
For CommonJS:
33

34
```javascript
35
const { 
36
  ICore, CoreTypes, ICrypto, CryptoTypes,
37
  ISignClient, SignClientTypes, SessionTypes,
38
  IEngine, EngineTypes, JsonRpcTypes,
39
  IRelayer, RelayerTypes, IPairing, PairingTypes,
40
  IPublisher, ISubscriber, IMessageTracker,
41
  IExpirer, IKeyChain, IVerify, IEchoClient, IEventClient,
42
  PublisherTypes, SubscriberTypes, PendingRequestTypes,
43
  ProposalTypes, AuthTypes
44
} = require("@walletconnect/types");
45
```
46

47
## Basic Usage
48

49
```typescript
50
import { SignClientTypes, SessionTypes, ProposalTypes } from "@walletconnect/types";
51

52
// Define session proposal parameters
53
const proposal: ProposalTypes.Struct = {
54
  id: 1,
55
  pairingTopic: "abc123",
56
  expiry: Date.now() + 300000, // 5 minutes
57
  relays: [{ protocol: "irn" }],
58
  proposer: {
59
    publicKey: "0x...",
60
    metadata: {
61
      name: "Example dApp",
62
      description: "An example dApp",
63
      url: "https://example.com",
64
      icons: ["https://example.com/icon.png"]
65
    }
66
  },
67
  requiredNamespaces: {
68
    eip155: {
69
      methods: ["eth_sendTransaction", "personal_sign"],
70
      chains: ["eip155:1", "eip155:137"],
71
      events: ["chainChanged", "accountsChanged"]
72
    }
73
  }
74
};
75

76
// Define session configuration
77
const session: SessionTypes.Struct = {
78
  topic: "session_topic",
79
  pairingTopic: "pairing_topic", 
80
  relay: { protocol: "irn" },
81
  expiry: Date.now() + 604800000, // 7 days
82
  acknowledged: true,
83
  controller: "0x...",
84
  namespaces: {
85
    eip155: {
86
      methods: ["eth_sendTransaction", "personal_sign"],
87
      chains: ["eip155:1", "eip155:137"],
88
      events: ["chainChanged", "accountsChanged"],
89
      accounts: ["eip155:1:0x...", "eip155:137:0x..."]
90
    }
91
  },
92
  self: {
93
    publicKey: "0x...",
94
    metadata: {
95
      name: "Example Wallet",
96
      description: "An example wallet",
97
      url: "https://wallet.example.com", 
98
      icons: ["https://wallet.example.com/icon.png"]
99
    }
100
  },
101
  peer: {
102
    publicKey: "0x...",
103
    metadata: {
104
      name: "Example dApp",
105
      description: "An example dApp", 
106
      url: "https://example.com",
107
      icons: ["https://example.com/icon.png"]
108
    }
109
  }
110
};
111
```
112

113
## Architecture
114

115
WalletConnect Types is organized into two main modules representing the core protocol layers:
116

117
- **Core Module**: Foundation types for protocol infrastructure including cryptography, relay communication, pairing, storage, and event handling
118
- **Sign Client Module**: Higher-level types for session management, authentication, proposals, and JSON-RPC communication
119

120
The type system follows a hierarchical structure where abstract classes define interfaces for implementations, namespaces group related type definitions, and comprehensive parameter objects enable type-safe function calls across the WalletConnect ecosystem.
121

122
## Capabilities
123

124
### Core Protocol Types
125

126
Core infrastructure types including cryptographic operations, relay communication, pairing management, and protocol-level interfaces.
127

128
```typescript { .api }
129
interface ICore extends IEvents {
130
  readonly name: string;
131
  readonly context: string;
132
  readonly logger: ILogger;
133
  readonly heartbeat: IHeartBeat;
134
  readonly relayer: IRelayer;
135
  readonly crypto: ICrypto;
136
  readonly storage: IKeyValueStorage;
137
  readonly history: IJsonRpcHistory;
138
  readonly expirer: IExpirer;
139
  readonly pairing: IPairing;
140
  readonly verify: IVerify;
141
  readonly echoClient: IEchoClient;
142
  readonly eventClient: IEventClient;
143
  readonly projectId?: string;
144
  readonly relayUrl?: string;
145
  readonly customStoragePrefix: string;
146
  readonly linkModeSupportedApps: string[];
147

148
  dispatchEnvelope(params: { topic: string; message: string; sessionExists: boolean }): void;
149
  addLinkModeSupportedApp(universalLink: string): void;
150
}
151

152
namespace CoreTypes {
153
  interface Options {
154
    projectId: string;
155
    relayUrl?: string;
156
    storage?: IKeyValueStorage;
157
    logger?: string | ILogger;
158
    keychain?: IKeyChain;
159
    name?: string;
160
    storageOptions?: KeyValueStorageOptions;
161
    maxLogBlobSizeInBytes?: number;
162
    customStoragePrefix?: string;
163
    telemetryEnabled?: boolean;
164
  }
165

166
  interface Metadata {
167
    name: string;
168
    description: string;
169
    url: string;
170
    icons: string[];
171
    verifyUrl?: string;
172
    linkMode?: boolean;
173
    redirect?: {
174
      native?: string;
175
      universal?: string;
176
      linkMode?: boolean;
177
    };
178
  }
179
}
180
```
181

182
[Core Protocol Types](./core-protocol.md)
183

184
### Cryptographic Types
185

186
Cryptographic operations including key management, encryption/decryption, and encoding/decoding functionality.
187

188
```typescript { .api }
189
interface ICrypto extends IEvents {
190
  readonly name: string;
191
  readonly context: string;
192
  readonly keychain: IKeyChain;
193
  readonly randomSessionIdentifier: string;
194
  
195
  init(): Promise<void>;
196
  hasKeys(tag: string): boolean;
197
  getClientId(): Promise<string>;
198
  generateKeyPair(): Promise<string>;
199
  generateSharedKey(self: string, peer: string, overrideTopic?: string): Promise<string>;
200
  setSymKey(symKey: string, overrideTopic?: string): Promise<string>;
201
  deleteKeyPair(publicKey: string): Promise<void>;
202
  deleteSymKey(topic: string): Promise<void>;
203
  encode(topic: string, payload: JsonRpcPayload, opts?: CryptoTypes.EncodeOptions): Promise<string>;
204
  decode(topic: string, encrypted: string, opts?: CryptoTypes.DecodeOptions): Promise<JsonRpcPayload>;
205
  signJWT(aud: string): Promise<string>;
206
  getPayloadType(encoded: string, encoding?: CryptoTypes.EncodingType): number;
207
  getPayloadSenderPublicKey(encoded: string, encoding?: CryptoTypes.EncodingType): string | undefined;
208
}
209

210
namespace CryptoTypes {
211
  interface KeyPair {
212
    privateKey: string;
213
    publicKey: string;
214
  }
215

216
  interface EncryptParams {
217
    message: string;
218
    symKey: string;
219
    type?: number;
220
    iv?: string;
221
    senderPublicKey?: string;
222
  }
223

224
  interface DecryptParams {
225
    symKey: string;
226
    encoded: string;
227
  }
228
}
229
```
230

231
[Cryptographic Types](./crypto.md)
232

233
### Session Management
234

235
Session lifecycle management including proposals, approvals, updates, and session structures for WalletConnect connections.
236

237
```typescript { .api }
238
namespace SessionTypes {
239
  interface Struct {
240
    topic: string;
241
    pairingTopic: string;
242
    relay: RelayerTypes.ProtocolOptions;
243
    expiry: number;
244
    acknowledged: boolean;
245
    controller: string;
246
    namespaces: Namespaces;
247
    self: Participant;
248
    peer: Participant;
249
    requiredNamespaces?: ProposalTypes.RequiredNamespaces;
250
    optionalNamespaces?: ProposalTypes.OptionalNamespaces;
251
    sessionProperties?: SessionProperties;
252
    transportType?: RelayerTypes.TransportType;
253
  }
254

255
  interface Namespace {
256
    chains?: string[];
257
    accounts: string[];
258
    methods: string[];
259
    events: string[];
260
  }
261

262
  type Namespaces = Record<string, Namespace>;
263
}
264

265
namespace ProposalTypes {
266
  interface Struct {
267
    id: number;
268
    pairingTopic: string;
269
    expiry: number;
270
    relays: RelayerTypes.ProtocolOptions[];
271
    proposer: {
272
      publicKey: string;
273
      metadata: CoreTypes.Metadata;
274
    };
275
    requiredNamespaces: RequiredNamespaces;
276
    optionalNamespaces?: OptionalNamespaces;
277
    sessionProperties?: SessionProperties;
278
  }
279

280
  interface RequiredNamespace {
281
    chains?: string[];
282
    methods: string[];
283
    events: string[];
284
  }
285

286
  type RequiredNamespaces = Record<string, RequiredNamespace>;
287
}
288
```
289

290
[Session Management](./session-management.md)
291

292
### Sign Client Interface
293

294
Main client interface for WalletConnect sign operations including connection establishment and session management.
295

296
```typescript { .api }
297
interface ISignClient extends IEvents {
298
  readonly metadata: CoreTypes.Metadata;
299
  readonly protocol: string;
300
  readonly version: number;
301
  readonly core: ICore;
302
  readonly logger: ILogger;
303
  readonly events: EventEmitter;
304
  readonly engine: IEngine;
305
  readonly session: ISession;
306
  readonly proposal: IProposal;
307
  readonly pendingRequest: IPendingRequest;
308
  readonly auth: IAuth;
309

310
  connect(params?: SignClientTypes.ConnectParams): Promise<{ uri?: string; approval(): Promise<SessionTypes.Struct> }>;
311
  pair(params: { uri: string }): Promise<PairingTypes.Struct>;
312
  approve(params: {
313
    id: number;
314
    namespaces: SessionTypes.Namespaces;
315
    sessionProperties?: ProposalTypes.SessionProperties;
316
  }): Promise<SessionTypes.Struct>;
317
  reject(params: { id: number; reason: ErrorResponse }): Promise<void>;
318
  update(params: { topic: string; namespaces: SessionTypes.Namespaces }): Promise<void>;
319
  extend(params: { topic: string }): Promise<void>;
320
  request(params: { topic: string; request: RequestArguments; chainId: string }): Promise<any>;
321
  respond(params: { topic: string; response: JsonRpcResponse }): Promise<void>;
322
  ping(params: { topic: string }): Promise<void>;
323
  emit(params: { topic: string; event: SessionTypes.EventArguments; chainId: string }): Promise<void>;
324
  disconnect(params: { topic: string; reason: ErrorResponse }): Promise<void>;
325
  find(params: { requiredNamespaces: ProposalTypes.RequiredNamespaces }): SessionTypes.Struct[];
326
}
327
```
328

329
[Sign Client Interface](./sign-client.md)
330

331
### Relay Communication
332

333
Relay protocol types for message routing, subscription management, and network communication in the WalletConnect infrastructure.
334

335
```typescript { .api }
336
interface IRelayer extends IEvents {
337
  readonly core: ICore;
338
  readonly logger: ILogger;
339
  readonly events: EventEmitter;
340
  readonly provider: JsonRpcProvider;
341
  readonly messages: IMessageTracker;
342
  readonly subscriber: ISubscriber;
343
  readonly publisher: IPublisher;
344
  readonly transportExplicitlyClosed: boolean;
345

346
  init(): Promise<void>;
347
  publish(topic: string, message: string, opts?: RelayerTypes.PublishOptions): Promise<void>;
348
  subscribe(topic: string, opts?: RelayerTypes.SubscribeOptions): Promise<string>;
349
  unsubscribe(topic: string, opts?: RelayerTypes.UnsubscribeOptions): Promise<void>;
350
}
351

352
namespace RelayerTypes {
353
  interface PublishOptions {
354
    relay?: ProtocolOptions;
355
    ttl?: number;
356
    prompt?: boolean;
357
    tag?: number;
358
    id?: number;
359
    attestation?: string;
360
  }
361

362
  interface ProtocolOptions {
363
    protocol: string;
364
    data?: string;
365
  }
366

367
  interface MessageEvent {
368
    topic: string;
369
    message: string;
370
    publishedAt: number;
371
    attestation?: string;
372
  }
373
}
374
```
375

376
[Relay Communication](./relay.md)
377

378
### Authentication & Authorization
379

380
Authentication flows including CACAO (Chain Agnostic CApability Object) support and session authentication mechanisms.
381

382
```typescript { .api }
383
namespace AuthTypes {
384
  interface Cacao {
385
    h: CacaoHeader;
386
    p: CacaoPayload;  
387
    s: CacaoSignature;
388
  }
389

390
  interface CacaoHeader {
391
    t: string;
392
  }
393

394
  interface CacaoPayload {
395
    domain: string;
396
    aud: string;
397
    version: string;
398
    nonce: string;
399
    iat: string;
400
    nbf?: string;
401
    exp?: string;
402
    statement?: string;
403
    requestId?: string;
404
    resources?: string[];
405
  }
406

407
  interface SessionAuthenticateParams {
408
    chains: string[];
409
    domain: string;
410
    nonce: string;
411
    uri: string;
412
    nbf?: string;
413
    exp?: string;
414
    statement?: string;
415
    requestId?: string;
416
    resources?: string[];
417
  }
418
}
419
```
420

421
[Authentication & Authorization](./auth.md)