npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@rayos/wallet-sdk

v0.2.0

Published

TypeScript SDK for Guardian Wallet — passkey-secured smart wallets on Stellar

Readme

@rayos/wallet-sdk

The official TypeScript SDK for interacting with Guardian Wallet — a passkey-secured, policy-governed smart wallet on the Stellar network.

CI Release Sync Bindings License: MIT npm version

📦 View @rayos/wallet-sdk on NPM


What Is This?

@rayos/wallet-sdk is the single source of truth for how client applications (web dashboards, mobile apps, demo apps) interact with the Guardian Wallet ecosystem. It wraps:

  • WebAuthn / Passkey registration and assertion (browser via @simplewebauthn/browser, or a custom PasskeyProvider for React Native)
  • On-chain reads over Soroban RPC (wallet existence, signers, native balance, transfer history from events)
  • Passkey-signed transfers: builds the Soroban transfer, has the passkey sign the wallet's authorization entry, and hands the result to the relay
  • Relay backend communication (wallet deployment, fee-sponsored submission, testnet faucet)

Apps should never call contract bindings or WebAuthn APIs directly — everything goes through this SDK.


Repository Ecosystem

This SDK is part of a multi-repo ecosystem. Here is how the repos relate:

wallet-contracts  ──generates──►  wallet-sdk  ──used by──►  web-dashboard
                                                        ──►  mobile-app
                                                        ──►  demo-app
                  relay-backend  ◄──── wallet-sdk (HTTP)

| Repo | Role | |---|---| | wallet-contracts | Soroban smart contracts — source of truth for on-chain logic | | wallet-sdk (this repo) | TypeScript SDK — wraps contracts + passkeys + relay | | relay-backend | Fee-sponsorship relay service | | web-dashboard | Consumer web app using this SDK | | mobile-app | Consumer mobile app using this SDK |


Quick Start

Installation

The package is officially published on npm as @rayos/wallet-sdk.

npm install @rayos/wallet-sdk
# or
pnpm add @rayos/wallet-sdk

Basic Usage

import { WalletSdk } from '@rayos/wallet-sdk';

const sdk = new WalletSdk({
  networkPassphrase: 'Test SDF Network ; September 2015',
  rpcUrl: 'https://soroban-testnet.stellar.org',
  relayUrl: 'https://relay.your-org.dev/api',
  factoryContractId: 'CCCAMWJOF7IYTVCU7SR6HFTNH5XRMDMWPYN464NY5BCKUPMUM64RZ5CH',
  rpId: 'your-app.com',
});

// 1. Register a passkey (options come from relay POST /webauthn/register/options)
const credential = await sdk.registerPasskey(options);
// credential.publicKeyBytes is the 65-byte P-256 key extracted from the attestation

// 2. Deploy the wallet contract — the relay's sponsor account pays
const salt = crypto.getRandomValues(new Uint8Array(32));
const { address, txHash } = await sdk.deployWallet({ salt, credential });

// 3. Read on-chain state (Soroban RPC, no relay involved)
const state = await sdk.getWalletState(address); // { address, exists, signers, balance }
await sdk.requestFaucet(address);                 // testnet only

// 4. Send XLM: passkey signs the wallet's Soroban auth entry, relay pays the fee
const res = await sdk.transfer({
  walletAddress: address,
  to: 'G...',
  amount: 10_000_000n, // stroops
  credentialId: credential.id,
});
console.log(res.txHash, res.status); // real testnet hash

// 5. History from contract events
const transfers = await sdk.getRecentTransfers(address, 25);

createWallet(options, salt) does steps 1–2 in one call. On React Native, pass a passkeyProvider (see mobile-app/native/passkey-adapter.ts) instead of relying on the browser default.


Documentation

| Guide | Description | |---|---| | Setup Guide (SETUP.md) | Complete environment configuration, local development & bindings setup | | Architecture | System design, module map, key decisions | | Getting Started | Full setup guide, prerequisites, env config | | API Reference | Complete public API documentation | | Testing Guide | How to run tests, write new tests | | Integration Guide | How this SDK connects to other repos | | Security Policy | Reporting vulnerabilities | | Contributing | How to contribute to this project | | Changelog | Release history |


Prerequisites

Before using or developing the SDK, ensure you have:

  • Node.js ≥ 20 LTS (or 24.x LTS)
  • pnpm ≥ 9 — npm install -g pnpm
  • Stellar CLI — for regenerating contract bindings
  • A browser supporting WebAuthn / Passkeys

Development Setup

💡 For a detailed walkthrough on setting up contract bindings, environment variables, local package linking, and troubleshooting, see the SETUP.md guide.

# Clone the repo
git clone https://github.com/Rayos-Org/wallet-sdk.git
cd wallet-sdk

# Install dependencies
pnpm install

# Copy env file and fill in contract addresses
cp .env.example .env

# Regenerate contract bindings (after wallet-contracts releases)
bash scripts/regenerate-bindings.sh

# Run tests
pnpm test

# Build
pnpm build

Project Structure

wallet-sdk/
├── src/
│   ├── passkey/            # WebAuthn registration/assertion, CBOR + DER + base64url encoding
│   ├── contracts/
│   │   ├── generated/      # Auto-generated Soroban bindings (do not edit)
│   │   ├── wallet-client.ts# RPC reads, auth-entry signing, transfer building
│   │   └── errors.ts
│   ├── relay/              # HTTP client for relay-backend
│   └── index.ts            # Public API surface (WalletSdk)
├── tests/                  # Vitest: unit, testnet integration, testnet e2e (software authenticator)
├── scripts/
│   └── regenerate-bindings.sh
├── docs/                   # Extended documentation
└── .github/                # CI/CD workflows, issue templates

Contributing

We welcome contributions of all kinds! Please read CONTRIBUTING.md before opening a PR.


License

MIT © Rayos Org