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

sword-sdk

v0.1.3

Published

Sword SDK: merchant registration, orders, payments, refunds and subscriptions on Whitechain.

Readme

Sword SDK

TypeScript SDK for the Sword contracts on Whitechain (chain 1874). It covers merchant registration, the merchant's permission, orders, refunds, subscriptions, and smart accounts. A subscription works like an order: the merchant creates it, it has its own deposit address, and exactly one customer takes it (subscriptions.create, subscriptions.subscribe, subscriptions.refund, subscriptions.withdraw). Customers act through their smart account, either directly as owner or through the relayer under a grant.

The API and the widget are built on top of this SDK.

Install and build

npm install
npm run typecheck
npm run build        # writes dist/

Node 22.10 or later is required.

Two modes

Each SDK instance is created in one mode. Create one instance per mode.

Merchant mode. The merchant's own wallet sends every action. The UI passes in the wallet client. The SDK builds each action; the wallet confirms it.

Relayer mode. The relayer key is read from the environment on the backend. The relayer sends actions only within the permission the merchant has granted. The merchant doesn't sign each action.

| | Merchant mode | Relayer mode | |---|---|---| | Register merchant, sign, revoke permission | Yes | No | | Approve spender for refunds from the merchant wallet | Yes | No | | Record a manual refund | Yes | No | | Create orders, confirm transfers, fail orders, set refund window | Yes | Yes, within permission | | Approve or deny refunds, refund from balance or extra funds | Yes | Yes, within permission | | Pay refunds from the merchant wallet | Yes | Yes, with permission and the merchant's approval | | Create subscriptions, charge due periods, withdraw, cancel, refund any amount | Yes | Yes (create and refund within permission) | | Expire, refund failed order, withdraw, close | Yes | Yes, no permission needed | | Submit a signed permission | Yes | Yes |

Chains

The SDK starts on Whitechain testnet (chain 1874), unless the UI chooses another chain at creation.

  • The UI can change the chain at any time with the chain setting. Every action after that goes to the new chain, using its contract addresses and RPC endpoint.
  • Each chain's addresses and RPC variable are kept in src/config/chains.ts. Chains without an entry are rejected with UNSUPPORTED_CHAIN.
  • To add a chain, deploy the contracts there and add one entry. Nothing else changes.
  • Permissions are signed per chain. A permission signed for one chain is not valid on another.
  • In merchant mode the merchant's wallet must also be on the chosen chain. Every action checks this first and fails with WRONG_NETWORK otherwise. The UI asks the wallet to switch network.
  • In relayer mode the relayer wallet is rebuilt for the new chain. The relayer needs gas on every chain it works on.

Creating an instance

  • Merchant mode takes a wallet client, and optionally a chain and an RPC URL.
  • Relayer mode reads RELAYER_PRIVATE_KEY from the environment. The RPC comes from the chain's variable (WHITECHAIN_RPC_URL for Whitechain) unless one is given. The key is never passed in code and is never logged.

Permission

The permission is the merchant's one-time signature on the relayer's limits. It sets:

  • the relayer address,
  • how many days it lasts (at most 31),
  • the maximum orders and actions,
  • the maximum value (at most 1,000 USDT).

The flow:

  1. Prepare the permission. The UI shows the values to the merchant. Either mode can prepare it.
  2. Sign it. Merchant mode only, with the merchant's wallet.
  3. Submit it. Either mode.

Check the permission at any time. It reports the state, the days left, and whether renewal is due (5 days or fewer left, or no active permission). In relayer mode, any action the permission covers checks it first and fails with PERMISSION_REQUIRED if it is missing, expired, or names another relayer.

Smart accounts

Customers and merchants can each hold a smart account. One factory creates both kinds. Each kind has its own blueprint, so each account is a lightweight copy.

Two ways to run an account:

  • Custodial. The owner is the relayer's key. The relayer has full control. The customer or merchant signs nothing per action.
  • Self-custody. The owner is the customer's or merchant's own key. The owner signs one grant for the relayer, with an amount limit and an expiry. The relayer then acts within it.

Shared actions (both kinds, under accounts):

  • Create an account for an identity (relayer mode only). Each identity gets at most one account of each kind. The address can be predicted before creation.
  • Read the account's status: owner, relayer, frozen, balance, grant, and usage.
  • Prepare, sign, and submit the owner's grant, and revoke it (owner only).
  • Send USDT (owner, or the relayer within the grant).
  • Freeze and unfreeze (owner only). While frozen, no action is taken, though funds can still arrive.
  • Run an arbitrary call (owner only).

Customer actions (under accounts.customer):

  • Pay an order.
  • Take a subscription and pay its first period. The full subscription total counts against the grant.
  • Cancel a subscription.
  • Ask for a refund on an order or a subscription. These move no money.

Merchant actions (under accounts.merchant):

  • Register as a merchant (owner only, once).
  • Create an order, reuse a closed collector, confirm a plain transfer, fail an order, set the refund window.
  • Approve or deny a refund; pay an approved refund from the order balance or from the account's wallet; record a manual refund; send extra funds.
  • Create a subscription, charge a due period, withdraw what it holds, cancel it, and refund any amount at any time.

Merchant actions that move money out of the account count against the grant. Creating orders and confirming payments count nothing, so the grant does not limit the number of orders yet.

The factory is not deployed yet. Until it is, creating or predicting an account fails with FACTORY_NOT_DEPLOYED.

The identity is hashed before it goes on chain. Use a stable id, such as the Google account id, not an email address.

Layout

| Folder | Contents | |---|---| | src/client.ts | SwordSDK, the single entry point. Picks the wallet for the mode. | | src/modules/ | merchant, permission, orders, refunds, subscriptions, and accounts (customer and merchant actions). | | src/signing/ | EIP-712 data for the permission. | | src/core/ | Shared plumbing: transactions, lookups, mode checks, errors, units, ids, status names. | | src/config/ | Chain, production addresses, limits, environment names. | | src/abi/ | Contract ABIs. Generated, except erc20.ts. | | scripts/sync-abis.mjs | Copies ABIs from the Hardhat artifacts. |

Keeping ABIs in step with the contracts

After changing any contract, run npx hardhat compile in the project root, then npm run sync-abis in this folder. Do not edit the generated files by hand, except erc20.ts.

Errors

Every failure throws SwordError with a stable code. Contract errors use their name in capitals, for example NOT_AUTHORIZED. Checks the SDK makes before sending, such as PERMISSION_REQUIRED, ACTION_NOT_ALLOWED, or SLOT_NOT_DUE, cost no gas.

Amounts and ids

  • Amounts are decimal USDT strings such as "25.50".
  • Orders are identified by the merchant's own reference, hashed to the on-chain order id. Using the same reference twice is rejected.