Stellar Wallets Kit

SoroPass ships a PasskeyModule for stellar-wallets-kit that implements the kit's ModuleInterface, so a passkey wallet appears in the kit's own picker next to Freighter, LOBSTR and xBull, and your existing StellarWalletsKit.getAddress() / signTransaction() calls work unchanged. The module is a thin adapter: every ceremony, the ES256 enforcement, the DER to compact low-S conversion, and the Soroban auth-entry assembly come from @soropass/core.

SoroPass is not a wallet. It is the layer your wallet integrates: you keep your brand, your UI, your users, and your fee policy, and gain passkey accounts by registering one module. The passkey option in the picker carries your wallet's own name and icon (see productName below), so it reads as part of your wallet, not a separate product.

Install

npm install @soropass/core "@stellar/stellar-sdk@>=17"

Install @stellar/stellar-sdk at version 17 or newer: @soropass/core@0.3.1 builds against the stellar-sdk 17 XDR API, matching the kit's own stellar-sdk 17 dependency. The kit package that carries the module is @creit.tech/stellar-wallets-kit (note the dot).

Integration walkthrough

Six steps take a wallet from install to a passkey account that signs through the kit modal. Every ceremony underneath is @soropass/core; the kit calls stay the ones you already use.

1. Build the adapters

Two seams connect the module to the chain, both from @soropass/core. The deployer creates a smart account and pays that one-time deploy fee; the indexer resolves a returning user's credential back to their account address.

import { factoryDeployer, eventsIndexer } from '@soropass/core';
import { Networks } from '@stellar/stellar-sdk';

const cfg = {
  rpcUrl: 'https://soroban-testnet.stellar.org',
  networkPassphrase: Networks.TESTNET,
  // Optional since @soropass/core 0.3.1: omit it and the deployed SoroPass
  // factory for `networkPassphrase` is used (testnet CADKKP4B..., mainnet
  // CCCNRWMI..., both permissionless). Set it to use your own factory.
  factoryContractId: 'C...',
};

const deployer = factoryDeployer({ ...cfg, sourceSecret: DEPLOYER_SECRET }); // funded G-account that pays the deploy
const indexer = eventsIndexer({ rpcUrl: cfg.rpcUrl, factoryContractId: cfg.factoryContractId });

DEPLOYER_SECRET is a funded classic account that pays deploy fees and holds no user value. In production, swap directSubmission for a relayer so users pay nothing (see Existing wallets).

2. Construct and brand the module

Give the picker entry your wallet's name and icon with productName / productIcon. The module needs an RP ID and a network; pass the deployer and indexer from step 1.

import { PasskeyModule } from '@creit.tech/stellar-wallets-kit/modules/passkey';
import { Networks } from '@creit.tech/stellar-wallets-kit/types';

const passkey = new PasskeyModule({
  rpId: location.hostname, // the registrable domain the passkey binds to
  rpName: 'Acme Wallet', // shown in the OS passkey sheet
  networkPassphrase: Networks.TESTNET,
  productName: 'Acme Wallet', // the picker label: your brand, not "Passkey"
  productIcon: 'data:image/svg+xml;base64,...', // your mark (inline data URI)
  factoryContractId: cfg.factoryContractId, // enables instant offline reconnect
  deployer, // required to create an account on first connect
  indexer, // resolves a returning user's account
});

3. Register it next to your other wallets

The kit's API is static: pass every module to StellarWalletsKit.init once. The passkey wallet then appears in authModal() and createButton() like Freighter or LOBSTR.

import { StellarWalletsKit } from '@creit.tech/stellar-wallets-kit/sdk';
import { defaultModules } from '@creit.tech/stellar-wallets-kit/modules/utils';

StellarWalletsKit.init({
  network: Networks.TESTNET,
  modules: [...defaultModules(), passkey],
});

PasskeyModule needs configuration, so it is not part of defaultModules(); you always construct it yourself and add it to the list.

4. Connect (first-time and returning users)

Select the wallet, then call getAddress(). A first-time user with a deployer configured gets a fresh passkey and a deployed account in one step (create-on-connect). A returning user resolves instantly: offline from the remembered credential id and public key, using factoryContractId or, when it is omitted, the SoroPass factory for the network; a device that remembers only its credential id resolves through the indexer.

import { PASSKEY_ID } from '@creit.tech/stellar-wallets-kit/modules/passkey';

StellarWalletsKit.setWallet(PASSKEY_ID); // PASSKEY_ID === 'passkey'
const { address } = await StellarWalletsKit.getAddress(); // C-address of the smart account

For an explicit "create account" button instead of create-on-connect, call the module's own createAccount(userName?) (see What each kit call does).

5. Sign a transaction

A passkey account is a contract, so it is never the transaction's source. Build the transaction with a funded source account and put the passkey account's authorization in a Soroban auth entry, then sign that through the kit. Pass the connected address so the module signs only this account's entries.

const { signedTxXdr } = await StellarWalletsKit.signTransaction(unsignedTxXdr, {
  address, // the connected C-address
  networkPassphrase: Networks.TESTNET,
});
// add the fee source's own signature, then submit with your RPC or a relayer

6. Add a backup device

One passkey on one device is a single point of failure. Enroll a second passkey as an additional signer so either device can approve on its own. Register the new device (no deploy), build the account's add_signer call, and authorize it with an existing device through the kit.

import { registerPasskey } from '@soropass/core/create';
import { Contract, nativeToScVal } from '@stellar/stellar-sdk';

const backup = await registerPasskey({
  rpId: location.hostname,
  rpName: 'Acme Wallet',
  userName: 'alice backup',
});
const addSignerOp = new Contract(address).call(
  'add_signer',
  nativeToScVal(backup.publicKey, { type: 'bytes' }),
);
// build + simulate a tx around addSignerOp, then authorize it with the current device:
const { signedTxXdr } = await StellarWalletsKit.signTransaction(assembledTxXdr, { address });

The account enrolls up to 20 signers and never lets you remove the last one, so a lost device is retired with remove_signer from any remaining device. See Native multi-device recovery.

Sign out

StellarWalletsKit.disconnect() drops the session; the passkey stays in the authenticator, so the next connect resolves the same account.

Configuration

new PasskeyModule(params) accepts:

The adapters (indexer, deployer) and the derivation helpers come from @soropass/core: eventsIndexer, factoryDeployer, smartWalletV1Deployer / smartWalletV1Indexer.

What each kit call does

Beyond ModuleInterface, the module adds one method:

Why a classic transaction is rejected

A passkey account is a contract (a C-address), so it can never be a transaction's source account, and its authorization travels in an InvokeHostFunction operation's auth entries rather than in the envelope's signature list. When you pass signTransaction an envelope with no Soroban address-credential auth entry, the module throws immediately with ext: "NO_SOROBAN_AUTH_ENTRY" and a message explaining how to build a signable transaction. Failing loudly at the call site beats returning the envelope untouched and failing at submission.

Build the transaction with a separate funded source account and put the passkey account's authorization in the auth entry; Existing wallets covers the fee-source pattern.

Errors

The kit's IKitError carries a numeric code. @soropass/core throws typed KitErrors with string codes from a frozen 10-code taxonomy. The module maps between the two:

• A user-driven abort (USER_CANCELLED) maps to kit code -1.
• Every other failure maps to kit code -3.
• The original string code is preserved in ext, so you keep the precise cause: if (e.ext === 'CHALLENGE_MISMATCH') ....

Two ext values are the module's own, not part of core's taxonomy:

Requirements

• Buffer polyfill. @soropass/core and the module's signing path run without a Buffer polyfill on @stellar/stellar-sdk 17. The kit's hardware-wallet modules (Ledger, Trezor) still carry one as a requirement; an existing polyfill does no harm.
• Secure context. WebAuthn is unavailable over plain http, so serve over https or localhost.
• A platform authenticator, or your own webauthn client. Without either, isAvailable resolves false and the kit renders the wallet as unavailable.

Integrate today with @soropass/core

Until the module ships in a kit release, you get the identical flows from the published core SDK; the module wraps exactly these calls:

Quickstart Path A is the runnable end-to-end version, and @soropass/core/testing gives you the same flows in CI with no browser and no network.