# @fabianbormann/cardano-peer-connect

> This library aims to provide an abstract class to simplify to wallet implementation for CIP-0045

Latest version **1.2.21** (published 2026-09-05) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @fabianbormann/cardano-peer-connect
pnpm add @fabianbormann/cardano-peer-connect
yarn add @fabianbormann/cardano-peer-connect
bun add @fabianbormann/cardano-peer-connect
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.2.21 |
| Published | 2026-09-05 |
| First published | 2022-12-14 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 18 |
| Author | Fabian Bormann |
| Maintainers | fabianbormann |
| Keywords | WebRTC, WebTorrent, wallet, dapp |

## Links

- npm: https://www.npmjs.com/package/@fabianbormann/cardano-peer-connect
- Repository: https://github.com/fabianbormann/cardano-peer-connect
- Homepage: https://github.com/fabianbormann/cardano-peer-connect#readme
- Issues: https://github.com/fabianbormann/cardano-peer-connect/issues
- npm.io page: https://npm.io/package/@fabianbormann/cardano-peer-connect

## Dependencies (3)

- [peerjs](https://npm.io/package/peerjs.md) ^1.5.5
- [qrcode-svg](https://npm.io/package/qrcode-svg.md) ^1.1.0
- [@basementuniverse/marble-identicons](https://npm.io/package/@basementuniverse/marble-identicons.md) ^0.1.2

## Recent versions

- 1.2.21 (latest) — 2026-09-05
- 1.2.20 — 2026-08-31
- 1.2.19 — 2026-05-05
- 1.2.18 — 2024-11-27
- 1.2.17 — 2024-05-24
- 1.2.16 — 2024-05-21
- 1.2.15 — 2024-03-12
- 1.2.14 — 2023-11-16
- 1.2.13 — 2023-08-07
- 1.2.12 — 2023-08-06
- 1.2.11 — 2023-08-06
- 1.2.10 — 2023-04-06
- 1.2.7 — 2023-03-29
- 1.2.6 — 2023-03-28
- 1.2.5 — 2023-03-24
- … 14 more at https://npm.io/package/@fabianbormann/cardano-peer-connect/versions

## README

# Cardano Peer Connect

<p align="left">
<img alt="Tests" src="https://img.shields.io/github/actions/workflow/status/fabianbormann/cardano-peer-connect/test.yml?label=Tests&style=for-the-badge" />
<img alt="Release" src="https://img.shields.io/github/actions/workflow/status/fabianbormann/cardano-peer-connect/release.yml?label=Release&style=for-the-badge" />
<img alt="Bundle" src="https://img.shields.io/github/actions/workflow/status/fabianbormann/cardano-peer-connect/bundle.yml?label=Bundle&style=for-the-badge" />
<img alt="Publish" src="https://img.shields.io/github/actions/workflow/status/fabianbormann/cardano-peer-connect/publish.yml?label=Publish&style=for-the-badge" />
<a href="https://conventionalcommits.org"><img alt="conventionalcommits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&style=for-the-badge" /></a>
</p>

An updated [CIP-0045](https://github.com/cardano-foundation/CIPs/pull/395) implementation that lets wallets and DApps communicate directly over WebRTC using [PeerJS](https://peerjs.com) as the signaling layer. Previously WebTorrents were used but the user experience wasn't great and sometimes the connection would fail to establish. Some WebTorrent libraries became outdated and unmaintained. This updated approach is more robust and works across all major browsers.

## How it works

```
Wallet                          Signaling server              DApp
  │                                    │                        │
  │   new Peer(walletId)               │                        │
  │──────────────────────────────────> │                        │
  │                                    │   new Peer(dappId)     │
  │                                    │ <──────────────────────│
  │                                    │                        │
  │      wallet.connect(dappId)        │                        │
  │──────────────────────────────────> │ ──────────────────────>│
  │                                    │    WebRTC offer/answer │
  │ <──────────────────────────────────────────────────────────>│
  │                                    │                        │
  │◄══════════════ direct WebRTC data channel ════════════════► │
  │                                    │                        │
  │  connect RPC → DApp accepts        │                        │
  │  injectApi RPC → window.cardano[walletName] populated       │
  │                                    │                        │
```

The signaling server is only used to broker the initial WebRTC handshake. All CIP-30 traffic flows through the encrypted peer-to-peer data channel.

## Installation

```sh
npm install @fabianbormann/cardano-peer-connect
```

## DApp integration

```typescript
import { DAppPeerConnect } from '@fabianbormann/cardano-peer-connect';

const dAppConnect = new DAppPeerConnect({
  dAppInfo: {
    name: 'My DApp',
    url: 'https://my-dapp.io',
  },

  // Called when a wallet tries to connect. Omit to accept all connections.
  verifyConnection: (walletInfo, callback) => {
    const granted = window.confirm(
      `Connect wallet "${walletInfo.name}"?`
    );
    callback(granted, false);
  },

  onConnect: (address, walletInfo) => {
    console.log('Wallet connected:', walletInfo?.name, address);
  },

  onDisconnect: (address) => {
    console.log('Wallet disconnected:', address);
  },

  // Called once window.cardano[walletName] has been populated.
  onApiInject: (walletName, address) => {
    console.log(`${walletName} API ready`);
  },

  onApiEject: (walletName, address) => {
    console.log(`${walletName} API removed`);
  },
});

// Show the peer ID to the user (as text or QR code) so the wallet can connect.
console.log('DApp peer ID:', dAppConnect.getAddress());
dAppConnect.generateQRCode(document.getElementById('qr-code'));

// After onApiInject fires, call CIP-30 methods through window.cardano:
//
//   const api = await window.cardano['my-p2p-wallet'].enable();
//   const networkId = await api.getNetworkId();
```

### DAppPeerConnect parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `dAppInfo` | `{ name, url, icon? }` | Metadata shown to the connecting wallet. |
| `verifyConnection` | `(walletInfo, callback) => void` | Optional gating function. Call `callback(true, allowAutoConnect)` to accept. |
| `onConnect` | `(address, walletInfo?) => void` | Fires when a wallet establishes the connection. |
| `onDisconnect` | `(address) => void` | Fires when the wallet disconnects. |
| `onApiInject` | `(name, address) => void` | Fires when `window.cardano[name]` has been populated. |
| `onApiEject` | `(name, address) => void` | Fires when the wallet API has been removed from `window.cardano`. |
| `useWalletDiscovery` | `boolean` | Enable auto-connect via a stored wallet discovery peer ID. Default: `false`. |
| `walletDiscoveryPeerId` | `string` | Initial wallet discovery peer ID to connect to when `useWalletDiscovery` is `true`. |
| `peerJsConfig` | `PeerOptions` | PeerJS configuration. Defaults to the public `0.peerjs.com` server. |
| `loggingEnabled` | `boolean` | Enable console logging. |

## Wallet integration

Extend `CardanoPeerConnect` and implement all CIP-30 methods:

```typescript
import {
  CardanoPeerConnect,
  IConnectMessage,
} from '@fabianbormann/cardano-peer-connect';

class MyWallet extends CardanoPeerConnect {
  constructor() {
    super(
      {
        name: 'my-p2p-wallet',  // must contain 'p2p'
        version: '1.0.0',
        icon: 'data:image/png;base64,...',
        requestAutoconnect: false,
      },
      {
        // peerJsConfig: { ... },  // optional; defaults to 0.peerjs.com
      }
    );
  }

  // ── CIP-30 implementation ────────────────────────────────────

  async getNetworkId(): Promise<number> {
    return 1; // mainnet
  }

  async getUtxos(amount?, paginate?): Promise<Cbor[] | null> {
    return myWalletApi.getUtxos(amount, paginate);
  }

  async getBalance(): Promise<Cbor> {
    return myWalletApi.getBalance();
  }

  async getUsedAddresses(): Promise<Cbor[]> {
    return myWalletApi.getUsedAddresses();
  }

  async getUnusedAddresses(): Promise<Cbor[]> {
    return myWalletApi.getUnusedAddresses();
  }

  async getChangeAddress(): Promise<Cbor> {
    return myWalletApi.getChangeAddress();
  }

  async getRewardAddresses(): Promise<Cbor[]> {
    return myWalletApi.getRewardAddresses();
  }

  async getCollateral(params?): Promise<Cbor[] | null> {
    return myWalletApi.getCollateral(params);
  }

  async signTx(tx: Cbor, partialSign: boolean): Promise<Cbor> {
    return myWalletApi.signTx(tx, partialSign);
  }

  async signData(addr: string, payload: Bytes): Promise<Cip30DataSignature> {
    return myWalletApi.signData(addr, payload);
  }

  async submitTx(tx: Cbor): Promise<string> {
    return myWalletApi.submitTx(tx);
  }
}
```

Connect to a DApp by passing its peer ID:

```typescript
const wallet = new MyWallet();

wallet.setOnConnect((message: IConnectMessage) => {
  if (message.connected) {
    console.log('Connected to DApp:', message.dApp.name);
  } else {
    console.warn('Connection rejected:', message.errorMessage);
  }
});

wallet.setOnDisconnect((message: IConnectMessage) => {
  console.log('Disconnected from DApp');
});

// dappPeerId comes from scanning the DApp's QR code or copy-pasting the peer ID
wallet.connect(dappPeerId);
```

### CardanoPeerConnect methods

| Method | Description |
|--------|-------------|
| `connect(dappPeerId)` | Connect to a DApp peer ID. Returns the wallet's own peer ID. |
| `disconnect(address)` | Gracefully disconnect from the current DApp. |
| `injectApi(overwrite?)` | Push the CIP-30 API to the DApp. Called automatically after a successful connect. |
| `getDiscoveryAddress()` | Returns the wallet's discovery peer ID used for auto-connect. |
| `setOnConnect(callback)` | Register a callback for connection events. |
| `setOnDisconnect(callback)` | Register a callback for disconnect events. |
| `setOnServerShutdown(callback)` | Register a callback for when the DApp shuts down. |
| `setOnApiInject(callback)` | Register a callback for when the API injection completes. |
| `setExperimentalApi(container)` | Attach an `ExperimentalContainer` exposed via `api.experimental`. |
| `setEnableExperimentalApi(container)` | Attach an `ExperimentalContainer` exposed via `enable().experimental`. |
| `generateIdenticon()` | Generate a connection identicon from the wallet + DApp peer IDs. |
| `getIdenticon()` | Returns the base64 identicon string, or `null` if not yet generated. |

## Using a self-hosted signaling server

By default both sides connect to the public PeerJS server at `0.peerjs.com`. For production you should run your own. The `peer` npm package provides one:

```sh
npx peerjs --port 9000
```

Then pass `peerJsConfig` to both sides:

```typescript
const peerJsConfig = {
  host: 'your-signaling-server.example.com',
  port: 443,
  path: '/',
  secure: true,
};

// DApp
const dAppConnect = new DAppPeerConnect({ dAppInfo, peerJsConfig, ... });

// Wallet
class MyWallet extends CardanoPeerConnect {
  constructor() {
    super(walletInfo, { peerJsConfig });
  }
}
```

## Local development

Start a local signaling server and a static file server, then open the test pages in separate browser tabs:

```sh
npx peerjs --port 9000   # signaling server
npx serve . --listen 3000 # static files
```

Open `http://localhost:3000/test/e2e/test_dApp.html` in one tab and `http://localhost:3000/test/e2e/test_wallet.html` in another, paste the DApp peer ID into the wallet page and click **Connect**.

## Running tests

```sh
npm test
```

The Playwright test suite starts both servers automatically and runs three end-to-end tests:

1. DApp initialises, shows a valid peer ID, and renders a QR code.
2. DApp and wallet exchange a `getNetworkId` call over a live WebRTC connection.
3. DApp and wallet complete a full `signData` roundtrip and the decoded signature is verified.

---
_Source: https://npm.io/package/@fabianbormann/cardano-peer-connect · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._