@ldgr/client 0.3.0 → 0.4.0

package/README.md

@@ -35,6 +35,38 @@ console.log(serviceWallet.address); // safe to identify the service wallet
 This is for backend/Bun service wallets only. Websites should use
 `@ldgr/wallet-sdk` and an extension-confirmed customer wallet instead.
 
+## Send a native or user-issued asset
+
+`transfers.send()` resolves the asset metadata, fetches the current nonce,
+builds and signs the transfer, submits it to the selected network, and retries
+once if another process consumed the nonce first. Use
+`LEDRA_TESTNET_ASSET_ID` / `LEDRA_MAINNET_ASSET_ID` from `@ldgr/protocol` for
+the native asset or pass a user-token code.
+
+```ts
+import { createLdgrClient } from "@ldgr/client";
+import { LEDRA_MAINNET_ASSET_ID } from "@ldgr/protocol";
+
+const client = createLdgrClient({ network: "mainnet" });
+const result = await client.transfers.send({
+  wallet: serviceWallet,
+  asset: LEDRA_MAINNET_ASSET_ID,
+  amount: "2.50",
+  to: recipientAddress,
+  memo: "Order 1234",
+});
+
+if (result.status === "settled") {
+  console.log(result.transactionHash, result.fee, result.feeAsset);
+} else {
+  console.error(result.code, result.error);
+}
+```
+
+Settlement failures return `status: "failed"`; they do not have a transaction
+hash or fee because the ledger rejected them before appending a transaction.
+Transport and unexpected response errors still throw.
+
 ```ts
 import { createLdgrClient } from "@ldgr/client";
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { type LdgrTransferResult, type SendTransferInput } from "./transfer";
 import { type Ldgr402Requirement, type LedgerId } from "@ldgr/protocol";
 import { type LdgrAccountTransactionPage, type LdgrClientOptions, type LdgrAsset, type Ldgr402Verification, type LdgrTransaction, type PaymentExpectation, type PaymentVerification, type SignedSubmission } from "./types";
 export declare function createLdgrClient(options: LdgrClientOptions): {
@@ -93,6 +94,9 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
             readonly nowMs?: number;
         }) => Promise<Ldgr402Verification>;
     };
+    transfers: {
+        send: (input: SendTransferInput) => Promise<LdgrTransferResult>;
+    };
     submitSigned: <T extends {
         readonly transactionHash?: string;
     }>(path: string, signed: SignedSubmission) => Promise<T>;
@@ -102,3 +106,5 @@ export { decodeMerchantLdgr402Payment, parseMerchantLdgr402Requirement } from ".
 export type { LdgrAccountTransaction, LdgrAccountTransactionPage, Ldgr402Requirement, Ldgr402Verification, LdgrAsset, LdgrClientOptions, LdgrNetwork, LdgrTransaction, PaymentExpectation, PaymentVerification, SignedSubmission } from "./types";
 export { createWebCryptoSigner, generateLocalWallet, loadLocalWallet } from "./signer";
 export type { LdgrSigner, LocalLdgrWallet } from "./signer";
+export { buildTransferSubmission } from "./transfer";
+export type { BuildTransferSubmissionInput, LdgrTransferResult, SendTransferInput } from "./transfer";

package/dist/index.js

@@ -77,9 +77,57 @@ function queryPath(path, query) {
   return encoded ? `${path}?${encoded}` : path;
 }
 
+// src/transfer.ts
+import {
+  canonicalizeLedgerAddress,
+  assertEncryptedMessageEnvelope,
+  formatAtomicAmount,
+  parseDecimalAmount
+} from "@ldgr/protocol";
+async function buildTransferSubmission(input) {
+  const recipient = canonicalizeLedgerAddress(input.to, input.wallet.ledgerId);
+  const amount = parseDecimalAmount(input.amount.trim(), input.assetDefinition);
+  if (amount < 0n || amount === 0n && (input.asset !== "dng" || input.encryptedMessage === undefined)) {
+    throw new RangeError("Amount must be greater than zero unless sending an encrypted Ledra message");
+  }
+  if (input.encryptedMessage !== undefined)
+    assertEncryptedMessageEnvelope(input.encryptedMessage);
+  if (!/^(0|[1-9][0-9]*)$/.test(input.nextNonce)) {
+    throw new TypeError("Ledger returned an invalid next nonce");
+  }
+  const memo = input.memo?.trim();
+  const payload = {
+    version: 1,
+    action: "transfer",
+    chain: "ldgr-v1",
+    ledgerId: input.wallet.ledgerId,
+    asset: input.asset,
+    from: input.wallet.address,
+    to: recipient,
+    amount,
+    nonce: BigInt(input.nextNonce),
+    timestamp: BigInt((input.now ?? Date.now)()),
+    publicKey: input.wallet.publicKey,
+    ...memo ? { memo } : {},
+    ...input.metadata === undefined ? {} : { metadata: input.metadata },
+    ...input.encryptedMessage === undefined ? {} : { encryptedMessage: input.encryptedMessage }
+  };
+  const signature = await input.wallet.sign(payload);
+  return {
+    payload: {
+      ...payload,
+      amount: formatAtomicAmount(amount, input.assetDefinition),
+      nonce: payload.nonce.toString(),
+      timestamp: payload.timestamp.toString()
+    },
+    signature
+  };
+}
+
 // src/index.ts
 import {
   decodeLdgr402Payment as decodeLdgr402Payment3,
+  nativeAssetDefinitionForLedger,
   parseLdgr402Requirement as parseLdgr402Requirement3,
   resolveLdgrNetwork as resolveLdgrNetwork2,
   resolvePublicAssetCode
@@ -174,6 +222,18 @@ function paymentReference(metadata) {
 function transactionFields(transaction) {
   return typeof transaction.from === "string" && typeof transaction.to === "string" && typeof transaction.asset === "string" && typeof transaction.amount === "string" ? { from: transaction.from, to: transaction.to, asset: transaction.asset, amount: transaction.amount } : null;
 }
+function isNonceMismatch(error) {
+  return error instanceof LdgrClientError && error.code === "NONCE_MISMATCH";
+}
+function transferFailure(error) {
+  if (!(error instanceof LdgrClientError) || error.status !== 400 && error.status !== 409)
+    return;
+  return {
+    status: "failed",
+    error: error.message,
+    ...error.code === undefined ? {} : { code: error.code }
+  };
+}
 function createLdgrClient(options) {
   const transport = createTransport(options);
   const ledgerId = options.network === undefined ? undefined : resolveLdgrNetwork2(options.network);
@@ -224,6 +284,57 @@ function createLdgrClient(options) {
       reference: requirement.challenge
     });
   };
+  const sendTransfer = async (input) => {
+    if (ledgerId !== undefined && ledgerId !== input.wallet.ledgerId) {
+      throw new TypeError("signer ledgerId does not match client network");
+    }
+    const requestedAsset = input.asset.trim();
+    if (!requestedAsset)
+      throw new TypeError("asset is required");
+    const asset = resolvePublicAssetCode(requestedAsset, input.wallet.ledgerId);
+    const assetDefinition = asset === "dng" ? nativeAssetDefinitionForLedger(input.wallet.ledgerId) : await transport.get(`/api/v1/assets/${encodePathSegment(asset)}`);
+    const submit = async () => {
+      const nonce = await transport.get(`/api/v1/nonces/${encodePathSegment(input.wallet.address)}/${encodePathSegment(asset)}`);
+      const submission = await buildTransferSubmission({
+        ...input,
+        asset,
+        assetDefinition,
+        nextNonce: nonce.nextNonce
+      });
+      const transaction = await transport.post("/api/v1/transfers", {
+        ...submission,
+        submittedAtMs: Date.now()
+      });
+      if (typeof transaction.transactionHash !== "string" || typeof transaction.fee !== "string" || typeof transaction.feeAsset !== "string") {
+        throw new TypeError("LDGR transfer response is missing transaction hash or fee");
+      }
+      return {
+        status: "settled",
+        transactionHash: transaction.transactionHash,
+        fee: transaction.fee,
+        feeAsset: transaction.feeAsset,
+        transaction
+      };
+    };
+    try {
+      return await submit();
+    } catch (error) {
+      if (isNonceMismatch(error)) {
+        try {
+          return await submit();
+        } catch (retryError) {
+          const failure2 = transferFailure(retryError);
+          if (failure2 !== undefined)
+            return failure2;
+          throw retryError;
+        }
+      }
+      const failure = transferFailure(error);
+      if (failure !== undefined)
+        return failure;
+      throw error;
+    }
+  };
   return {
     ledger: {
       get: () => transport.get("/api/v1/ledger"),
@@ -293,11 +404,13 @@ function createLdgrClient(options) {
       listOwned: (address, options2) => transport.get(queryPath(`/api/v1/usernames/owned-by/${encodePathSegment(address)}`, options2 ?? {}))
     },
     payments: { verifyTransfer, verifyLdgr402 },
+    transfers: { send: sendTransfer },
     submitSigned: (path, signed) => transport.post(path, { ...signed, submittedAtMs: Date.now() })
   };
 }
 export {
   LdgrClientError,
+  buildTransferSubmission,
   createLdgrClient,
   createWebCryptoSigner,
   decodeMerchantLdgr402Payment,

package/dist/transfer.d.ts

@@ -0,0 +1,42 @@
+import { type AssetDefinition, type JsonValue } from "@ldgr/protocol";
+import type { LdgrSigner } from "./signer";
+import type { LdgrTransaction } from "./types";
+export type BuildTransferSubmissionInput = {
+    readonly wallet: LdgrSigner;
+    readonly asset: string;
+    readonly assetDefinition: AssetDefinition;
+    readonly amount: string;
+    readonly to: string;
+    readonly nextNonce: string;
+    readonly memo?: string;
+    readonly metadata?: JsonValue;
+    readonly encryptedMessage?: string;
+    readonly now?: () => number;
+};
+export type SendTransferInput = {
+    readonly wallet: LdgrSigner;
+    /** Public native id (`t0`/`t1`) or wire asset code. */
+    readonly asset: string;
+    readonly amount: string;
+    readonly to: string;
+    readonly memo?: string;
+    readonly metadata?: JsonValue;
+    readonly encryptedMessage?: string;
+    readonly now?: () => number;
+};
+export type LdgrTransferResult = {
+    readonly status: "settled";
+    readonly transactionHash: string;
+    readonly fee: string;
+    readonly feeAsset: string;
+    readonly transaction: LdgrTransaction;
+} | {
+    readonly status: "failed";
+    /** Settlement failures happen before append, so there is no hash or fee. */
+    readonly error: string;
+    readonly code?: string;
+};
+export declare function buildTransferSubmission(input: BuildTransferSubmissionInput): Promise<{
+    readonly payload: Record<string, unknown>;
+    readonly signature: string;
+}>;

package/dist/types.d.ts

@@ -7,6 +7,8 @@ export type LdgrTransaction = {
     readonly to?: string;
     readonly asset?: string;
     readonly amount?: string;
+    readonly fee?: string;
+    readonly feeAsset?: string;
     readonly metadata?: unknown;
     readonly sequence?: string;
     readonly transactionHash: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldgr/client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -12,7 +12,7 @@
   "files": ["dist", "README.md"],
   "publishConfig": { "access": "public" },
   "engines": { "node": ">=20.19.0" },
-  "dependencies": { "@ldgr/protocol": "^0.3.0" },
+  "dependencies": { "@ldgr/protocol": "^0.4.0" },
   "scripts": {
     "build": "rm -rf dist && bun build src/index.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.build.json",
     "prepack": "bun run build",