tessl/npm-walletconnect--types

TypeScript type definitions and interfaces for the WalletConnect Protocol v2, enabling type-safe development across the WalletConnect ecosystem

1.18x

Quality

Pending

Does it follow best practices?

Impact

70%

1.18x

Average score across 10 eval scenarios

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

WalletConnect Types

Name: tessl/npm-walletconnect--types
Rating: 70 (1 reviews)
Author: tessl

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.

Package Information

Package Name: @walletconnect/types
Package Type: npm
Language: TypeScript
Installation: npm install @walletconnect/types

Core Imports

import { 
  // Core types
  ICore, CoreTypes, ICrypto, CryptoTypes,
  // Sign client types  
  ISignClient, SignClientTypes, SessionTypes,
  // Engine and protocol types
  IEngine, EngineTypes, JsonRpcTypes,
  // Communication interfaces
  IRelayer, RelayerTypes, IPairing, PairingTypes,
  IPublisher, ISubscriber, IMessageTracker,
  // Storage and utility interfaces
  IExpirer, IKeyChain, IVerify, IEchoClient, IEventClient,
  // Additional type namespaces
  PublisherTypes, SubscriberTypes, PendingRequestTypes,
  ProposalTypes, AuthTypes
} from "@walletconnect/types";

For CommonJS:

const { 
  ICore, CoreTypes, ICrypto, CryptoTypes,
  ISignClient, SignClientTypes, SessionTypes,
  IEngine, EngineTypes, JsonRpcTypes,
  IRelayer, RelayerTypes, IPairing, PairingTypes,
  IPublisher, ISubscriber, IMessageTracker,
  IExpirer, IKeyChain, IVerify, IEchoClient, IEventClient,
  PublisherTypes, SubscriberTypes, PendingRequestTypes,
  ProposalTypes, AuthTypes
} = require("@walletconnect/types");

Basic Usage

import { SignClientTypes, SessionTypes, ProposalTypes } from "@walletconnect/types";

// Define session proposal parameters
const proposal: ProposalTypes.Struct = {
  id: 1,
  pairingTopic: "abc123",
  expiry: Date.now() + 300000, // 5 minutes
  relays: [{ protocol: "irn" }],
  proposer: {
    publicKey: "0x...",
    metadata: {
      name: "Example dApp",
      description: "An example dApp",
      url: "https://example.com",
      icons: ["https://example.com/icon.png"]
    }
  },
  requiredNamespaces: {
    eip155: {
      methods: ["eth_sendTransaction", "personal_sign"],
      chains: ["eip155:1", "eip155:137"],
      events: ["chainChanged", "accountsChanged"]
    }
  }
};

// Define session configuration
const session: SessionTypes.Struct = {
  topic: "session_topic",
  pairingTopic: "pairing_topic", 
  relay: { protocol: "irn" },
  expiry: Date.now() + 604800000, // 7 days
  acknowledged: true,
  controller: "0x...",
  namespaces: {
    eip155: {
      methods: ["eth_sendTransaction", "personal_sign"],
      chains: ["eip155:1", "eip155:137"],
      events: ["chainChanged", "accountsChanged"],
      accounts: ["eip155:1:0x...", "eip155:137:0x..."]
    }
  },
  self: {
    publicKey: "0x...",
    metadata: {
      name: "Example Wallet",
      description: "An example wallet",
      url: "https://wallet.example.com", 
      icons: ["https://wallet.example.com/icon.png"]
    }
  },
  peer: {
    publicKey: "0x...",
    metadata: {
      name: "Example dApp",
      description: "An example dApp", 
      url: "https://example.com",
      icons: ["https://example.com/icon.png"]
    }
  }
};

Architecture

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

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

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.

Capabilities

Core Protocol Types

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

interface ICore extends IEvents {
  readonly name: string;
  readonly context: string;
  readonly logger: ILogger;
  readonly heartbeat: IHeartBeat;
  readonly relayer: IRelayer;
  readonly crypto: ICrypto;
  readonly storage: IKeyValueStorage;
  readonly history: IJsonRpcHistory;
  readonly expirer: IExpirer;
  readonly pairing: IPairing;
  readonly verify: IVerify;
  readonly echoClient: IEchoClient;
  readonly eventClient: IEventClient;
  readonly projectId?: string;
  readonly relayUrl?: string;
  readonly customStoragePrefix: string;
  readonly linkModeSupportedApps: string[];

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

namespace CoreTypes {
  interface Options {
    projectId: string;
    relayUrl?: string;
    storage?: IKeyValueStorage;
    logger?: string | ILogger;
    keychain?: IKeyChain;
    name?: string;
    storageOptions?: KeyValueStorageOptions;
    maxLogBlobSizeInBytes?: number;
    customStoragePrefix?: string;
    telemetryEnabled?: boolean;
  }

  interface Metadata {
    name: string;
    description: string;
    url: string;
    icons: string[];
    verifyUrl?: string;
    linkMode?: boolean;
    redirect?: {
      native?: string;
      universal?: string;
      linkMode?: boolean;
    };
  }
}

Core Protocol Types

Cryptographic Types

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

interface ICrypto extends IEvents {
  readonly name: string;
  readonly context: string;
  readonly keychain: IKeyChain;
  readonly randomSessionIdentifier: string;
  
  init(): Promise<void>;
  hasKeys(tag: string): boolean;
  getClientId(): Promise<string>;
  generateKeyPair(): Promise<string>;
  generateSharedKey(self: string, peer: string, overrideTopic?: string): Promise<string>;
  setSymKey(symKey: string, overrideTopic?: string): Promise<string>;
  deleteKeyPair(publicKey: string): Promise<void>;
  deleteSymKey(topic: string): Promise<void>;
  encode(topic: string, payload: JsonRpcPayload, opts?: CryptoTypes.EncodeOptions): Promise<string>;
  decode(topic: string, encrypted: string, opts?: CryptoTypes.DecodeOptions): Promise<JsonRpcPayload>;
  signJWT(aud: string): Promise<string>;
  getPayloadType(encoded: string, encoding?: CryptoTypes.EncodingType): number;
  getPayloadSenderPublicKey(encoded: string, encoding?: CryptoTypes.EncodingType): string | undefined;
}

namespace CryptoTypes {
  interface KeyPair {
    privateKey: string;
    publicKey: string;
  }

  interface EncryptParams {
    message: string;
    symKey: string;
    type?: number;
    iv?: string;
    senderPublicKey?: string;
  }

  interface DecryptParams {
    symKey: string;
    encoded: string;
  }
}

Cryptographic Types

Session Management

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

namespace SessionTypes {
  interface Struct {
    topic: string;
    pairingTopic: string;
    relay: RelayerTypes.ProtocolOptions;
    expiry: number;
    acknowledged: boolean;
    controller: string;
    namespaces: Namespaces;
    self: Participant;
    peer: Participant;
    requiredNamespaces?: ProposalTypes.RequiredNamespaces;
    optionalNamespaces?: ProposalTypes.OptionalNamespaces;
    sessionProperties?: SessionProperties;
    transportType?: RelayerTypes.TransportType;
  }

  interface Namespace {
    chains?: string[];
    accounts: string[];
    methods: string[];
    events: string[];
  }

  type Namespaces = Record<string, Namespace>;
}

namespace ProposalTypes {
  interface Struct {
    id: number;
    pairingTopic: string;
    expiry: number;
    relays: RelayerTypes.ProtocolOptions[];
    proposer: {
      publicKey: string;
      metadata: CoreTypes.Metadata;
    };
    requiredNamespaces: RequiredNamespaces;
    optionalNamespaces?: OptionalNamespaces;
    sessionProperties?: SessionProperties;
  }

  interface RequiredNamespace {
    chains?: string[];
    methods: string[];
    events: string[];
  }

  type RequiredNamespaces = Record<string, RequiredNamespace>;
}

Session Management

Sign Client Interface

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

interface ISignClient extends IEvents {
  readonly metadata: CoreTypes.Metadata;
  readonly protocol: string;
  readonly version: number;
  readonly core: ICore;
  readonly logger: ILogger;
  readonly events: EventEmitter;
  readonly engine: IEngine;
  readonly session: ISession;
  readonly proposal: IProposal;
  readonly pendingRequest: IPendingRequest;
  readonly auth: IAuth;

  connect(params?: SignClientTypes.ConnectParams): Promise<{ uri?: string; approval(): Promise<SessionTypes.Struct> }>;
  pair(params: { uri: string }): Promise<PairingTypes.Struct>;
  approve(params: {
    id: number;
    namespaces: SessionTypes.Namespaces;
    sessionProperties?: ProposalTypes.SessionProperties;
  }): Promise<SessionTypes.Struct>;
  reject(params: { id: number; reason: ErrorResponse }): Promise<void>;
  update(params: { topic: string; namespaces: SessionTypes.Namespaces }): Promise<void>;
  extend(params: { topic: string }): Promise<void>;
  request(params: { topic: string; request: RequestArguments; chainId: string }): Promise<any>;
  respond(params: { topic: string; response: JsonRpcResponse }): Promise<void>;
  ping(params: { topic: string }): Promise<void>;
  emit(params: { topic: string; event: SessionTypes.EventArguments; chainId: string }): Promise<void>;
  disconnect(params: { topic: string; reason: ErrorResponse }): Promise<void>;
  find(params: { requiredNamespaces: ProposalTypes.RequiredNamespaces }): SessionTypes.Struct[];
}

Sign Client Interface

Relay Communication

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

interface IRelayer extends IEvents {
  readonly core: ICore;
  readonly logger: ILogger;
  readonly events: EventEmitter;
  readonly provider: JsonRpcProvider;
  readonly messages: IMessageTracker;
  readonly subscriber: ISubscriber;
  readonly publisher: IPublisher;
  readonly transportExplicitlyClosed: boolean;

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

namespace RelayerTypes {
  interface PublishOptions {
    relay?: ProtocolOptions;
    ttl?: number;
    prompt?: boolean;
    tag?: number;
    id?: number;
    attestation?: string;
  }

  interface ProtocolOptions {
    protocol: string;
    data?: string;
  }

  interface MessageEvent {
    topic: string;
    message: string;
    publishedAt: number;
    attestation?: string;
  }
}

Relay Communication

Authentication & Authorization

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

namespace AuthTypes {
  interface Cacao {
    h: CacaoHeader;
    p: CacaoPayload;  
    s: CacaoSignature;
  }

  interface CacaoHeader {
    t: string;
  }

  interface CacaoPayload {
    domain: string;
    aud: string;
    version: string;
    nonce: string;
    iat: string;
    nbf?: string;
    exp?: string;
    statement?: string;
    requestId?: string;
    resources?: string[];
  }

  interface SessionAuthenticateParams {
    chains: string[];
    domain: string;
    nonce: string;
    uri: string;
    nbf?: string;
    exp?: string;
    statement?: string;
    requestId?: string;
    resources?: string[];
  }
}

Authentication & Authorization

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 2 months ago
Describes: pkg:npm/@walletconnect/types@2.21.x
Publish Source: CLI
Badge