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

@offerhub-orchestrator/stellar-escrow-signing

v1.0.3

Published

Stellar Wallets Kit client-side signing hook for Soroban escrow operations (create, fund, release, refund, dispute)

Readme

@offerhub-orchestrator/stellar-escrow-signing

A React hook for client-side Stellar/Soroban escrow signing operations using Stellar Wallets Kit. Provides a reusable, MIT-licensed signing layer for escrow operations: create, fund, release, refund, and dispute.

Features

  • Client-side signing: All cryptographic operations happen in the user's wallet via Stellar Wallets Kit
  • Multi-operation support: Handles all 5 escrow operations (create, fund, release, refund, dispute)
  • Step-wise operations: Properly handles multi-step flows like release (complete_milestone → approve_milestone → release)
  • Error handling: Typed error codes for user-reject, XDR expiry, wrong signer, stale transactions, and API errors
  • Safety guards: Double-submit prevention, XDR expiry validation, signer role checking
  • Framework-agnostic API: Integrates with any API client through simple prepare/submit function injection

Installation

npm install @offerhub-orchestrator/stellar-escrow-signing @creit.tech/stellar-wallets-kit
# or
yarn add @offerhub-orchestrator/stellar-escrow-signing @creit.tech/stellar-wallets-kit
# or
pnpm add @offerhub-orchestrator/stellar-escrow-signing @creit.tech/stellar-wallets-kit

Peer Dependencies

  • @creit.tech/stellar-wallets-kit: ^2.5.0
  • react: ^18.0.0 || ^19.0.0

Usage

Basic Example

import { useStellarEscrowSigning } from "@offerhub-orchestrator/stellar-escrow-signing";

function EscrowSigningButton({ orderId, userToken, wallet }) {
  const { state, sign, reset, transactionHash, error, currentStep } = useStellarEscrowSigning({
    token: userToken,
    wallet: {
      address: wallet.address,
      networkPassphrase: wallet.networkPassphrase,
    },
    prepareCreate: async (token, orderId) => {
      const response = await fetch(`/api/orders/${orderId}/escrow/prepare`, {
        method: "POST",
        headers: { Authorization: `Bearer ${token}` },
      });
      return response.json();
    },
    prepareFund: async (token, orderId) => {
      const response = await fetch(`/api/orders/${orderId}/escrow/fund/prepare`, {
        method: "POST",
        headers: { Authorization: `Bearer ${token}` },
      });
      return response.json();
    },
    prepareRelease: async (token, orderId) => {
      const response = await fetch(`/api/orders/${orderId}/resolution/release/prepare`, {
        method: "POST",
        headers: { Authorization: `Bearer ${token}` },
      });
      return response.json();
    },
    prepareRefund: async (token, orderId) => {
      const response = await fetch(`/api/orders/${orderId}/resolution/refund/prepare`, {
        method: "POST",
        headers: { Authorization: `Bearer ${token}` },
      });
      return response.json();
    },
    prepareDispute: async (token, orderId) => {
      const response = await fetch(`/api/orders/${orderId}/resolution/dispute/prepare`, {
        method: "POST",
        headers: { Authorization: `Bearer ${token}` },
      });
      return response.json();
    },
    submit: async (token, orderId, signedXdr, operation, idempotencyKey) => {
      const response = await fetch(`/api/orders/${orderId}/escrow/submit`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${token}`,
          "Idempotency-Key": idempotencyKey,
        },
        body: JSON.stringify({ signedXdr, operation }),
      });
      return response.json();
    },
  });

  const handleSign = async () => {
    await sign(orderId, "create", "buyer");
  };

  return (
    <div>
      <button onClick={handleSign} disabled={state !== "idle"}>
        {state === "idle" ? "Sign Transaction" : state}
      </button>
      {error && <div>Error: {error.message}</div>}
      {transactionHash && <div>Transaction: {transactionHash}</div>}
    </div>
  );
}

API Reference

useStellarEscrowSigning(config)

Main hook that orchestrates the signing flow.

Config Parameters:

| Parameter | Type | Required | Description | | ---------------- | ------------------------------------ | -------- | ---------------------------------------------------- | | token | string \| null | Yes | Auth token for API calls | | wallet | WalletContext | Yes | Wallet context with address and network passphrase | | prepareCreate | PrepareFn<PrepareEscrowResult> | Yes | Function to fetch unsigned XDR for create operation | | prepareFund | PrepareFn<PrepareEscrowResult> | Yes | Function to fetch unsigned XDR for fund operation | | prepareRelease | PrepareFn<PrepareEscrowStepResult> | Yes | Function to fetch unsigned XDR for release operation | | prepareRefund | PrepareFn<PrepareEscrowStepResult> | Yes | Function to fetch unsigned XDR for refund operation | | prepareDispute | PrepareFn<PrepareEscrowStepResult> | Yes | Function to fetch unsigned XDR for dispute operation | | submit | SubmitFn | Yes | Function to submit signed XDR to backend |

Return Value:

| Property | Type | Description | | ----------------- | ---------------------------------------------------- | -------------------------------------------- | | state | EscrowSigningState | Current state of the signing flow | | sign | (orderId, operation, callerRole?) => Promise<void> | Function to initiate signing | | reset | () => void | Function to reset state to idle | | transactionHash | string \| null | Transaction hash after successful submission | | currentStep | EscrowStepName \| null | Current step for multi-step operations | | error | EscrowSigningError \| null | Error object if signing failed |

States

The hook progresses through these states:

  • idle: Ready to sign
  • building: Fetching unsigned XDR from API
  • awaiting_signature: Waiting for user to sign in wallet
  • submitting: Broadcasting signed transaction to network
  • confirmed: Transaction successfully submitted
  • error: Signing failed

Error Codes

| Code | Description | | --------------------- | ---------------------------------------------- | | USER_REJECTED | User cancelled the signature request in wallet | | XDR_EXPIRED | Unsigned XDR expired (4-minute Soroban window) | | NO_WALLET_CONNECTED | No wallet connected | | WRONG_SIGNER | Caller is not the correct signer for this step | | STALE_TRANSACTION | Transaction was already submitted (stale XDR) | | API_ERROR | Generic API or network error |

Types

type EscrowOperation = "create" | "fund" | "release" | "refund" | "dispute";
type EscrowStepName = "complete_milestone" | "approve_milestone" | "release" | "dispute";

interface PrepareEscrowResult {
  unsignedXdr: string;
  operation: "create" | "fund";
  expiresAt: number;
  orderId: string;
}

interface PrepareEscrowStepResult {
  orderId: string;
  operation: "release" | "refund" | "dispute";
  step: EscrowStepName | null;
  signer: "buyer" | "seller" | null;
  unsignedXdr: string | null;
  expiresAt: number | null;
}

interface SubmitEscrowXdrResult {
  transactionHash: string;
  order: unknown;
}

Integration with OfferHub

In the OFFER-HUB frontend, this package is consumed by src/hooks/useEscrowSigning.ts, which provides the app-specific prepare/submit functions and wallet context.

License

MIT © OFFER-HUB

Contributing

This package is part of the OFFER-HUB project. Contributions are welcome through the main repository.

Support

For issues and questions, please use the OFFER-HUB issue tracker.

Releasing

Published to npm by the Release signing package workflow when a tag is pushed. Bump version in package.json, merge, then:

git tag stellar-escrow-signing-v1.0.3 && git push origin stellar-escrow-signing-v1.0.3

The tag must match the version. The job runs the tests (wallet kit mocked, no network), builds, checks the tarball and publishes with npm provenance. It authenticates with npm Trusted Publishing (OIDC), so no npm token is stored: on npmjs.com the package trusts OFFER-HUB/OFFER-HUB-Frontend and release-signing-package.yml (account offer-hub-team, scope @offerhub-orchestrator). Running the workflow by hand is a dry run.