0
# Session Management
1

2
Session lifecycle management types including session structures, proposals, namespaces, and session configuration for WalletConnect connections between dApps and wallets.
3

4
## Capabilities
5

6
### Session Structure
7

8
Core session structure containing all information about an established WalletConnect connection.
9

10
```typescript { .api }
11
namespace SessionTypes {
12
  /**
13
   * Complete session structure representing an active WalletConnect connection
14
   */
15
  interface Struct {
16
    /** Unique session topic identifier */
17
    topic: string;
18
    /** Associated pairing topic */
19
    pairingTopic: string;
20
    /** Relay protocol configuration */
21
    relay: RelayerTypes.ProtocolOptions;
22
    /** Session expiry timestamp */
23
    expiry: number;
24
    /** Whether session has been acknowledged */
25
    acknowledged: boolean;
26
    /** Controller (proposer) public key */
27
    controller: string;
28
    /** Approved namespaces with accounts and methods */
29
    namespaces: Namespaces;
30
    /** Self participant (this client) metadata */
31
    self: Participant;
32
    /** Peer participant (other client) metadata */
33
    peer: Participant;
34
    /** Original required namespaces from proposal */
35
    requiredNamespaces: ProposalTypes.RequiredNamespaces;
36
    /** Optional namespaces from proposal */
37
    optionalNamespaces: ProposalTypes.OptionalNamespaces;
38
    /** Custom session properties (optional) */
39
    sessionProperties?: SessionProperties;
40
    /** Scoped properties for namespace-specific metadata (optional) */
41
    scopedProperties?: ScopedProperties;
42
    /** Session configuration options (optional) */
43
    sessionConfig?: SessionConfig;
44
    /** Authentication CACAOs (optional) */
45
    authentication?: AuthTypes.Cacao[];
46
    /** Transport type for communication (optional) */
47
    transportType?: RelayerTypes.TransportType;
48
  }
49

50
  /**
51
   * Session expiry timestamp type
52
   */
53
  type Expiry = number;
54

55
  /**
56
   * Session configuration options
57
   */
58
  interface SessionConfig {
59
    /** Disable deep link functionality (optional) */
60
    disableDeepLink?: boolean;
61
  }
62

63
  /**
64
   * Session participant information
65
   */
66
  interface Participant {
67
    /** Participant's public key */
68
    publicKey: string;
69
    /** Participant's metadata */
70
    metadata: SignClientTypes.Metadata;
71
  }
72
}
73
```
74

75
### Namespace Management
76

77
Namespace structures defining blockchain networks, methods, events, and accounts supported in a session.
78

79
```typescript { .api }
80
namespace SessionTypes {
81
  /**
82
   * Base namespace structure with accounts, methods, and events
83
   */
84
  interface BaseNamespace {
85
    /** Supported blockchain chain IDs (optional) */
86
    chains?: string[];
87
    /** Array of blockchain accounts in CAIP-10 format */
88
    accounts: string[];
89
    /** Supported RPC methods */
90
    methods: string[];
91
    /** Supported events */
92
    events: string[];
93
  }
94

95
  /**
96
   * Session namespace type (same as BaseNamespace)
97
   */
98
  type Namespace = BaseNamespace;
99

100
  /**
101
   * Session namespaces mapping
102
   * Maps namespace names to their configurations
103
   */
104
  type Namespaces = Record<string, Namespace>;
105

106
  /**
107
   * Session properties type for custom metadata
108
   */
109
  type SessionProperties = Record<string, string>;
110

111
  /**
112
   * Scoped properties type for namespace-specific metadata
113
   */
114
  type ScopedProperties = Record<string, Record<string, string>>;
115
}
116
```
117

118
### Proposal Structure
119

120
Proposal structures for initiating WalletConnect sessions with required and optional capabilities.
121

122
```typescript { .api }
123
namespace ProposalTypes {
124
  /**
125
   * Complete proposal structure for session establishment
126
   */
127
  interface Struct {
128
    /** Unique proposal ID */
129
    id: number;
130
    /** Pairing topic for this proposal */
131
    pairingTopic: string;
132
    /** Proposal expiry timestamp */
133
    expiry: number;
134
    /** Available relay protocols */
135
    relays: RelayerTypes.ProtocolOptions[];
136
    /** Proposer information */
137
    proposer: {
138
      /** Proposer's public key */
139
      publicKey: string;
140
      /** Proposer's metadata */
141
      metadata: CoreTypes.Metadata;
142
    };
143
    /** Required namespace capabilities */
144
    requiredNamespaces: RequiredNamespaces;
145
    /** Optional namespace capabilities */
146
    optionalNamespaces?: OptionalNamespaces;
147
    /** Custom session properties */
148
    sessionProperties?: SessionProperties;
149
  }
150

151
  /**
152
   * Base required namespace requirements
153
   */
154
  interface BaseRequiredNamespace {
155
    /** Required blockchain chain IDs (optional) */
156
    chains?: string[];
157
    /** Required RPC methods */
158
    methods: string[];
159
    /** Required events */
160
    events: string[];
161
  }
162

163
  /**
164
   * Required namespace type (same as base)
165
   */
166
  type RequiredNamespace = BaseRequiredNamespace;
167

168
  /**
169
   * Required namespaces mapping
170
   * Maps namespace names to their requirements
171
   */
172
  type RequiredNamespaces = Record<string, RequiredNamespace>;
173

174
  /**
175
   * Optional namespaces mapping  
176
   * Maps namespace names to their optional capabilities
177
   */
178
  type OptionalNamespaces = Record<string, RequiredNamespace>;
179

180
  /**
181
   * Session properties mapping for custom metadata
182
   */
183
  type SessionProperties = Record<string, string>;
184

185
  /**
186
   * Scoped properties mapping for namespace-specific metadata
187
   */
188
  type ScopedProperties = Record<string, Record<string, string>>;
189
}
190
```
191

192
### Session Store Interfaces
193

194
Store interfaces for persisting session and proposal data.
195

196
```typescript { .api }
197
/**
198
 * Store interface for sessions
199
 * Handles CRUD operations for session persistence
200
 */
201
type ISession = IStore<SessionTypes.Struct>;
202

203
/**
204
 * Store interface for proposals  
205
 * Handles CRUD operations for proposal persistence
206
 */
207
type IProposal = IStore<ProposalTypes.Struct>;
208
```
209

210
**Usage Examples:**
211

212
```typescript
213
import { SessionTypes, ProposalTypes } from "@walletconnect/types";
214

215
// Create a session proposal
216
const proposal: ProposalTypes.Struct = {
217
  id: 1,
218
  pairingTopic: "pairing_topic_123",
219
  expiry: Date.now() + 300000, // 5 minutes
220
  relays: [{ protocol: "irn" }],
221
  proposer: {
222
    publicKey: "0x04...",
223
    metadata: {
224
      name: "Example dApp",
225
      description: "A sample decentralized application",
226
      url: "https://example.com",
227
      icons: ["https://example.com/icon.png"]
228
    }
229
  },
230
  requiredNamespaces: {
231
    eip155: {
232
      chains: ["eip155:1", "eip155:137"], // Ethereum mainnet and Polygon
233
      methods: ["eth_sendTransaction", "personal_sign"],
234
      events: ["chainChanged", "accountsChanged"]
235
    }
236
  },
237
  optionalNamespaces: {
238
    eip155: {
239
      chains: ["eip155:42161", "eip155:10"], // Arbitrum and Optimism
240
      methods: ["eth_signTypedData"],
241
      events: ["disconnect"]
242
    }
243
  }
244
};
245

246
// Create a session structure
247
const session: SessionTypes.Struct = {
248
  topic: "session_topic_456",
249
  pairingTopic: "pairing_topic_123",
250
  relay: { protocol: "irn" },
251
  expiry: Date.now() + 604800000, // 7 days
252
  acknowledged: true,
253
  controller: "0x04...", // Proposer's public key
254
  namespaces: {
255
    eip155: {
256
      chains: ["eip155:1", "eip155:137"],
257
      accounts: [
258
        "eip155:1:0x1234567890123456789012345678901234567890",
259
        "eip155:137:0x1234567890123456789012345678901234567890"
260
      ],
261
      methods: ["eth_sendTransaction", "personal_sign"],
262
      events: ["chainChanged", "accountsChanged"]
263
    }
264
  },
265
  self: {
266
    publicKey: "0x04...", // Wallet's public key
267
    metadata: {
268
      name: "Example Wallet",
269
      description: "A sample crypto wallet",
270
      url: "https://wallet.example.com",
271
      icons: ["https://wallet.example.com/icon.png"]
272
    }
273
  },
274
  peer: {
275
    publicKey: "0x04...", // dApp's public key  
276
    metadata: {
277
      name: "Example dApp",
278
      description: "A sample decentralized application",
279
      url: "https://example.com", 
280
      icons: ["https://example.com/icon.png"]
281
    }
282
  }
283
};
284

285
// Define namespaces
286
const namespaces: SessionTypes.Namespaces = {
287
  eip155: {
288
    chains: ["eip155:1"],
289
    accounts: ["eip155:1:0xabc..."],
290
    methods: ["eth_sendTransaction"],
291
    events: ["chainChanged"]
292
  }
293
};
294
```