WalletConnect Client for the XRP Ledger

walletconnect | joey-wallet | xrp | xrpl

wc-client: Simplified XRP Ledger Integration with WalletConnect

wc-client is a developer-friendly client designed to streamline interaction with the XRP Ledger (XRPL) via WalletConnect. It abstracts away WalletConnect complexities—such as redirects, deep links, and modal handling—while leveraging the latest package dependencies to ensure a seamless experience with the XRP Ledger and Joey Wallet.

Tailored for developers building decentralized applications (DApps), wc-client accelerates integration, enabling you to focus on creating robust DApps.

Target Audience: Developers seeking a fast, reliable way to integrate their DApps with the XRP Ledger and Joey Wallet.

Features

wc-client offers two versions to provide flexibility based on your project's needs and desired feature set:

Advanced and Standalone.

1. Advanced (Recommended)

A feature-rich, multi-framework version optimized for complex DApps.

• Persisted Historical Data: Stores pending activities, previous requests, and wallet metadata for enhanced user experiences.
• Robust Session Management: Supports multiple, concurrent WalletConnect sessions, ideal for DApps requiring advanced connection handling.
• Framework-Agnostic: Compatible with various JavaScript frameworks, ensuring flexibility across different tech stacks.

2. Standalone

A lightweight, React-specific version delivered in a single file for minimal setup.

• Target Use Case: Perfect for developers who need a simple, React-only solution and don't require advanced features like multi-session support or historical data persistence.
• Minimal Footprint: Streamlined for quick integration with basic WalletConnect functionality.

Getting Started

Prerequisites

Before using wc-client, ensure you have the following:

• Node.js: Version 16 or higher (LTS recommended).
• A WalletConnect-compatible wallet (e.g., Joey Wallet) that supports XRPL interactions.
• A WalletConnect Project ID from Reown Cloud (formerly WalletConnect Cloud) for initializing the Universal Provider.
• Basic familiarity with the XRP Ledger and WalletConnect for seamless integration.

Installation

To integrate wc-client into your decentralized application (DApp), install it using your preferred package manager: pnpm, npm, or yarn. Run one of the following commands in your project directory:

pnpm add @joey-wallet/wc-client

Note: Ensure your project includes @walletconnect/universal-provider as a dependency, as wc-client builds on it for WalletConnect functionality. If not already included, you can install it alongside wc-client:

Next Steps:

After installation, you can initialize wc-client in your DApp to connect to the XRP Ledger via WalletConnect.

• Refer to the Quick Start section for a basic example of setting up the client, or explore the Playground directory for advanced use cases, including session management and transaction handling with Joey Wallet.
• For a more thorough explanation, view here.

Quick Start

After installation, you can import and start using wc-client:

// File located at ./src/context/advanced
'use client';

import { advance } from '@joey-wallet/wc-client/react';
import config from '~/common/wc-config'

export const Provider = (props: React.PropsWithChildren) => <wcc.Provider config={config}>{props.children}</wc.provider.Provider>;

export const useProvider = wcc.useProvider;

Usage Example:

// File: ./src/app/page.jsx
import { Provider, useProvider } from '~/context/advanced';

export default function Home() {
  return (
    <Provider>
      <App />
    </Provider>
  );
}

function App() {
  const { provider, uri, activeSession, actions} = useProvider();

	const handleConnection = async () => {
		await actions.connect()
	}

  return (
    <div>
      {!uri && <button onClick={handleConnection}>Connect</button> }
      { uri && <div>{uri}</button> }
    </div>
  );
}

Next Steps:

• Configure the WalletConnect client by setting up the wc-config file (see Configuration Options (#configuration-options)).
• Explore some examples in the Playground directory for advanced use cases, such as transaction signing or multi-session management.
• For a more thorough explanation, view here.

Configuration Options

The wc-client Provider requires a configuration object to initialize WalletConnect and connect to the XRP Ledger. Below is an example configuration file and a detailed explanation of available options, including the metadata field for WalletConnect project details.

// File: ./src/common/wc-config.ts
import type { Config } from '@joey-wallet/wc-client';

export default {
  // Required
  projectId: process.env['NEXT_PUBLIC_PROJECT_ID'],
  // Optional - Add your projects details
  metadata: {
    name: 'Joey Example Project',
    description: 'A sample project using walletconnect and Joey Wallet.',
    url: 'http://localhost:3000',
    icons: ['/assets/favicon.ico'],
    redirect: {
      universal: 'http://localhost:3000',
    },
  },
} as Config;

• For a full configuration explanation, view here.

Examples

For more in-depth examples on how to use wc-client, check out our Playground directory. Here you'll find various scenarios from basic usage to complex usage:

• Basic Connection: Demonstrates how to connect to the XRP Ledger.
• Transaction Handling: Examples on how to manage transactions.
• Explore our live demo site here: https://wc-toolkit.joeywallet.xyz

Contributors

The wc-client project is developed and maintained by the core development team at Joey Wallet, dedicated to building seamless tools for interacting with the XRP Ledger (XRPL).

Note: We welcome contributions from the community! Check out our contribution guidelines for details on how to get involved.

Contributing

We welcome contributions to wc-client! See our CONTRIBUTING.md for guidelines on how to get started.

For bug reports, feature requests, or questions, please open an issue on the GitHub repository. We appreciate your feedback and collaboration in making wc-client better!

Disclaimer

wc-client is provided as-is, with no warranties or guarantees of performance, reliability, or suitability for any particular purpose. While we strive to ensure it works seamlessly with the XRP Ledger, users should test and validate its functionality in their specific environments. The developers are not liable for any damages, losses, or issues arising from its use. Always ensure compliance with XRPL infrastructure providers' terms of service and rate limits when using this client.

License

wc-client is licensed under the MIT License (LICENSE). You are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software, provided that the copyright notice and permission notice are included in all copies or substantial portions of the software. See the LICENSE file in the repository for full details.