CantonConnect Adapter Starter

A starter template for building wallet adapters for CantonConnect SDK.

Quick Start

1. Copy this package to your project:

   cp -r packages/adapter-starter packages/adapters/my-wallet

2. Rename and customize:

   • Rename adapter.ts to match your wallet (e.g., mywallet-adapter.ts)
   • Update walletId and name in the adapter class
   • Update package.json name and description

3. Implement required methods:

   • detectInstalled() - Check if wallet is available
   • connect() - Establish connection and return partyId
   • getCapabilities() - Return supported capabilities

4. Implement optional methods (if supported):

   • signMessage() - Sign messages
   • signTransaction() - Sign transactions
   • submitTransaction() - Submit transactions
   • restore() - Restore sessions

5. Run conformance tests:

   cantonconnect-conformance run --adapter ./dist

Adapter Contract

All adapters must implement the WalletAdapter interface from @cantonconnect/core:

interface WalletAdapter {
  readonly walletId: WalletId;
  readonly name: string;
  
  getCapabilities(): CapabilityKey[];
  detectInstalled(): Promise<AdapterDetectResult>;
  connect(ctx: AdapterContext, opts?): Promise<AdapterConnectResult>;
  disconnect(ctx: AdapterContext, session: Session): Promise<void>;
  
  // Optional methods:
  restore?(ctx: AdapterContext, persisted: PersistedSession): Promise<Session | null>;
  signMessage?(ctx: AdapterContext, session: Session, params: SignMessageParams): Promise<SignedMessage>;
  signTransaction?(ctx: AdapterContext, session: Session, params: SignTransactionParams): Promise<SignedTransaction>;
  submitTransaction?(ctx: AdapterContext, session: Session, params: SubmitTransactionParams): Promise<TxReceipt>;
}

Capability Mapping

Declare capabilities your wallet supports:

• connect - Required: wallet can connect
• disconnect - Required: wallet can disconnect
• restore - Optional: wallet supports session restoration
• signMessage - Optional: wallet can sign messages
• signTransaction - Optional: wallet can sign transactions
• submitTransaction - Optional: wallet can submit transactions
• events - Optional: wallet emits events
• injected - Optional: browser extension (injected script)
• popup - Optional: uses popup flow
• deeplink - Optional: uses deep link flow
• remoteSigner - Optional: enterprise remote signer

Error Mapping

Always use mapUnknownErrorToCantonConnectError() to normalize errors:

try {
  // Wallet SDK call
} catch (err) {
  throw mapUnknownErrorToCantonConnectError(err, {
    walletId: this.walletId,
    phase: 'connect', // or 'signMessage', 'signTransaction', etc.
    transport: 'injected', // or 'popup', 'deeplink', 'remote'
  });
}

Install Hints

For registry entry, provide installHints:

{
  "installHints": {
    "injectedKey": "myWallet", // window.myWallet
    "extensionId": "abc123...", // Chrome extension ID
    "deepLinkScheme": "mywallet", // mywallet://
    "universalLinkBase": "https://app.mywallet.com"
  }
}

Origin Allowlist

If your wallet supports origin allowlist, include it in registry entry:

{
  "originAllowlist": [
    "https://myapp.com",
    "https://*.myapp.com"
  ]
}

SDK will enforce this automatically.

Testing

Local Conformance Tests

# Build your adapter
pnpm build

# Run conformance tests
cantonconnect-conformance run --adapter ./dist

# View report
cantonconnect-conformance report --input conformance-report.json

Integration Testing

Test your adapter in a demo dApp:

import { createCantonConnect } from '@cantonconnect/sdk';
import { MyWalletAdapter } from '@mywallet/adapter';

const client = createCantonConnect({
  registryUrl: 'https://registry.cantonconnect.io',
  network: 'devnet',
  app: { name: 'My dApp' },
});

// Register adapter
client.registerAdapter(new MyWalletAdapter());

// Connect
const session = await client.connect({ walletId: 'mywallet' });

Security Checklist

• ✅ State parameter (nonce) for CSRF protection
• ✅ Origin validation
• ✅ Redirect URI validation
• ✅ Timeout enforcement
• ✅ Error mapping (never expose sensitive errors)
• ✅ No private keys stored (only session metadata)
• ✅ Signing payload display (user-friendly format)

See docs/security-checklist.md for complete checklist.

Registry Onboarding

1. Add to beta registry:

   cantonconnect-registry add-wallet \
     --channel beta \
     --walletId mywallet \
     --name "My Wallet" \
     --adapterPackage "@mywallet/adapter" \
     --adapterRange "^1.0.0" \
     --capabilities connect,disconnect,signMessage \
     --installHints '{"injectedKey":"myWallet"}' \
     --docs '["https://docs.mywallet.com"]'

2. Run conformance tests (must pass)

3. Promote to stable:

   cantonconnect-registry promote --from beta --to stable

See docs/registry-onboarding.md for detailed workflow.

Examples

See existing adapters for reference:

• packages/adapters/console - Browser extension adapter
• packages/adapters/loop - QR code/popup adapter
• packages/adapters/cantor8 - Deep link adapter with vendor module
• packages/adapters/bron - Enterprise remote signer adapter

Support

• Documentation: docs/wallet-provider-guide.md
• Issues: GitHub Issues
• Security: [email protected]