@atumlabs/payment-gateway-client 2.2.0 → 3.0.1

package/docs/idempotency.md

@@ -1,8 +1,14 @@
-# Payment idempotency
+# Idempotency
 
-Submit the same payment twice — a retry, a timeout, a network blip — and you
-should end up with **one** payment, not two, and receive the **same** answer both
-times. The key to both properties is the `request_id` you send with each payment.
+Send the same request twice — a retry, a timeout, a network blip — and it should
+count once, not twice, and give you the **same** answer both times. On a payment
+that means you are charged once. The key to both properties is the `request_id`
+you send.
+
+One contract covers every write endpoint. Today that is `submitPayment` and
+`createQuoteRequest`; they use the same key, reject the same misuse the same way,
+and report a replay the same way, so what you learn on one applies to the other.
+Where an endpoint genuinely differs it is called out inline.
 
 ## Using the SDK
 
@@ -12,25 +18,46 @@ With `@atumlabs/payment-gateway-client` this is automatic. Pass a stable
 deterministically from it, so both guarantees below line up on their own. You
 never manage nonces — `request_id` is the only value you control.
 
-Reuse the same `request_id` across attempts of the same logical payment. Use a
-fresh `request_id` only for a genuinely new payment.
+Reuse the same `request_id` across attempts of the same logical request. Use a
+fresh `request_id` only when you genuinely mean a new one.
+
+Both builders require it: `preparePaymentRequest` and `prepareQuoteRequest` each
+take `requestId` explicitly, and neither invents one. That is deliberate — an id
+the library chose for you is an id you cannot reuse on a retry, so the retry would
+create a second payment or open a second batch rather than recovering the first.
+
+The CLIs are the exception, because a command invocation is a one-shot request:
+`send-payment` and `request-quote` generate an id when `--request-id` is omitted
+and print it back, so you can re-run with `--request-id <id>` to retry the same
+one. A bare re-run, with no `--request-id`, is a **separate** payment or batch.
 
 ## The two guarantees
 
-### 1. Gateway dedup — enforced for every caller
+### 1. Gateway dedup — every write endpoint, every caller
 
 The gateway records your `request_id` (scoped to your source account and signing
-identity). If the same `request_id` arrives again for the same payment, the
-gateway returns the original payment — same `payment_id`, same status and receipt
-— and never creates a second payment or broadcasts a second deposit. This holds
-whether you use the SDK or call the API directly, as long as you send a stable
-`request_id` and reuse it on retry.
-
-"For the same payment" is the one condition: an id re-used for *different*
-economics is rejected rather than replayed. See
+identity). If the same `request_id` arrives again, the gateway returns what it
+created the first time and creates nothing new:
+
+| Endpoint | A repeat returns | And does not |
+| -- | -- | -- |
+| `submitPayment` | the original payment — same `payment_id`, status and receipt | create a second payment or broadcast a second deposit |
+| `createQuoteRequest` | the original batch — same `quote_request_id` and its quotes | open a second batch or re-broadcast to settlement agents |
+
+This holds whether you use the SDK or call the API directly, as long as you send a
+stable `request_id` and reuse it on retry.
+
+"The same request" is the one condition: an id re-used for *different* economics
+is rejected rather than replayed. See
 [Reusing an id for different terms is rejected](#reusing-an-id-for-different-terms-is-rejected).
 
-### 2. On-chain single-settlement — enforced by the blockchain
+### 2. On-chain single-settlement — payments only, enforced by the blockchain
+
+This second guarantee applies where funds move, which today means `submitPayment`.
+A quote-request authorizes no spend — it carries no `sender_auth` and no deposit
+nonce — so guarantee 1 is the whole mechanism there. Nothing is charged either
+way; what a retry protects on that endpoint is your ability to find the batch
+again.
 
 Each deposit authorization carries a nonce, and the chain guarantees a given
 nonce can settle at most once. This ties your retries together on-chain **only
@@ -39,60 +66,78 @@ if** each retry carries the **same** nonce. The SDK derives that nonce from your
 themselves in the signed permit.
 
 A changing `request_id` defeats both guarantees, because each attempt is then
-treated as a different payment — keep it stable and reuse it on retry.
+treated as a different request — keep it stable and reuse it on retry.
 
 ## Reusing an id for different terms is rejected
 
-One `request_id` identifies one payment, so it cannot be pointed at different
-economics. Re-submit an id you have already used with a changed amount, token,
-account or destination and the gateway answers **`409`** with
-`IDEMPOTENCY_TERMS_MISMATCH` rather than paying, and rather than quietly serving
-you the original payment.
+One `request_id` identifies one payment, or one quote-request batch, so it cannot
+be pointed at different economics. Re-submit an id you have already used with a
+changed amount, token, account or destination and the gateway answers **`409`**
+with `IDEMPOTENCY_TERMS_MISMATCH` rather than acting on it, and rather than
+quietly serving you the original.
 
 What counts as "different economics" is who pays, who receives, in which assets,
 and for how much — the terms that decide where the money goes. Change any of them
 and you get the `409`; the error's `message` names the category that differed. A
-genuinely different payment needs a new `request_id`, which is what the error is
+genuinely different request needs a new `request_id`, which is what the error is
 telling you.
 
-Anything outside that list is taken from the payment that already exists, and the
-value you sent is not applied. So a re-submission is not a way to amend a payment
-in flight; it is a way to ask for the one you already made.
+On a quote-request the `409` is doing the same job one step earlier: without it
+you would silently receive the batch you opened *earlier*, whose quotes price the
+corridor you asked for then — and awarding one of those settles a payment on that
+corridor, not the one you meant.
+
+Anything outside that list is taken from what already exists, and the value you
+sent is not applied. So a re-submission is not a way to amend something in flight;
+it is a way to ask for the one you already made.
 
 ### Deadlines and the signature are exempt
 
 Two things you may freely change on a re-submission, because neither identifies
-the payment:
+the request:
 
 - **Deadlines.** Re-send the original bytes unchanged and the deadlines will
-  usually have expired by then: `quote_deadline` bounds the auction and is short,
-  and `POST /v1/payments` can hold a submission for longer than that. An expired
-  deadline on a re-submission is **not** an error — the request resolves onto the
-  payment that already exists, so nothing is scheduled against it.
+  usually have expired by then: `quote_deadline` is short — it bounds the auction
+  on a payment and the collection window on a quote-request — and either endpoint
+  can take longer than that to answer. An expired deadline on a re-submission is
+  **not** an error; the request resolves onto what already exists, so nothing is
+  scheduled against it.
 - **The signature.** Re-signing is fine. So is re-sending the original signature.
 
 Which means both retry styles work: keep the exact bytes from the first attempt,
-or rebuild and re-sign the same payment. What must not change is the
-`request_id`.
+or rebuild and re-sign. What must not change is the `request_id`.
+
+One consequence is specific to quote-requests: **the collection window belongs to
+the batch, not to your request.** Asking again with a later `quote_deadline` does
+not extend a window already open. The `quote_deadline` you get back is the
+batch's own, and `status` tells you whether collection is still running. This is
+the one place where a re-submission returns something that may not match what you
+just sent — by design, because the response has to describe the batch you
+actually received.
 
 ## Telling a retry from a first attempt
 
-`PaymentResponse.idempotent_replay` is `true` when you have been handed a payment
-that already existed, and `false` when this request created one. Read it if you
-need to distinguish "the payment went through just now" from "the payment was
-already there" — for logging, for reconciliation, or to avoid double-counting a
+`idempotent_replay` is `true` when you have been handed something that already
+existed, and `false` when this request created it. Every write response carries
+it — `PaymentResponse`, `QuoteRequestResponse` and `QuoteRequestAccepted`. Read it
+if you need to distinguish "this went through just now" from "this was already
+there" — for logging, for reconciliation, or to avoid double-counting a
 conversion.
 
-## Reading the outcome
+It is always present, so `false` means `false`. A response missing the field
+altogether is from a gateway predating it.
+
+## Reading the outcome (payments)
 
-`status` is on every response, and the three endings mean different things for a
+`status` is on every payment response, and the three endings mean different things for a
 retry:
 
 | `status`               | What it means                     | What to do                                             |
 | ---------------------- | --------------------------------- | ------------------------------------------------------ |
 | `completed`            | Settled.                          | Nothing. `fulfillment_confirmation` carries the proof. |
 | `pending`              | Accepted, still settling.         | Re-submit the **same** `request_id`, or read the status endpoint. Do not start a new payment. |
-| `failed` / `cancelled` | Terminal — it can never complete. | A fresh attempt needs a **new** `request_id`.          |
+| `finalizing`           | Paid on chain, collecting confirmations. Not final. | As `pending`. Do not treat it as delivered. |
+| `failed`               | Terminal — it can never complete. | A fresh attempt needs a **new** `request_id`.          |
 
 `pending` is not success. Cross-chain settlement can outrun the gateway's
 synchronous window, so a payment that has been accepted may still have no result
@@ -121,6 +166,18 @@ holds the connection open for the whole settlement window. That constraint is
 specific to sitting in the middle of someone else's request, and does not apply
 to a backend calling this SDK directly.
 
+## Recovering a lost quote-request response
+
+The rules above are all you need for payments. On `createQuoteRequest` they add up
+to one workflow worth spelling out, because it is the reason the endpoint behaves
+this way.
+
+If you lose the create response, re-send the request. You get your
+`quote_request_id` back and can read the batch's quotes — rather than being told
+your `quote_deadline` has expired while holding no id to look the batch up with.
+The collection window is short, so by the time you retry it usually *has* expired;
+that is exactly the case the deadline exemption exists to cover.
+
 ## Chain-specific behavior
 
 The SDK gives you the same guarantee on every chain; the on-chain half works

package/docs/signing.md

@@ -0,0 +1,218 @@
+# Signing a PaymentRequest
+
+A PaymentRequest carries **three unrelated signatures**. They are produced by different calls,
+cover different things, and none substitutes for another. Choosing the wrong one is the mistake
+this page exists to prevent.
+
+| What you are signing | Call | What it authorizes |
+|---|---|---|
+| `sender_auth.signed_messages[]` | `signPaymentRequest` | the on-chain **transfer** |
+| the document's `proof` | `signDeclaration` | that the **document** came from its signer |
+| `presentation` | `buildEnvelope` | the **originator's identity** |
+
+A request with a valid `sender_auth` and no identity envelope authorizes a transfer by an
+unidentified originator. The reverse identifies an originator who has authorized nothing. Most
+integrations need the first two; the third applies once the originator holds credentials about
+itself.
+
+> The two names are confusingly close, and that is not an accident of this client: the upstream
+> library calls its document signer `signPaymentRequest` too. This package exports it as
+> `signDeclaration` so the two cannot be confused for one another, matching `SignDeclaration`
+> in the Go client.
+
+## Keys never reach this package
+
+Every signing surface takes a **signer**, not a private key:
+
+```ts
+export interface DeclarationSigner {
+  getAddress(): Promise<string> | string;
+  signDigest(digest: Uint8Array): Promise<Uint8Array> | Uint8Array;
+}
+```
+
+That is deliberate. A hex key forces raw key material into a JavaScript string, which cannot be
+zeroized, is copied on assignment, and lands in heap snapshots and any log line that stringifies
+the surrounding object. It also excludes every custodian: a holder whose key sits in a KMS, an
+HSM, or a provider like Turnkey has no key to hand over.
+
+For a local key, use ethers — a library built to hold keys:
+
+```ts
+import { Wallet } from 'ethers';
+import { signerFromEthersWallet } from '@atum-labs/payment-gateway-client/signing';
+
+const signer = signerFromEthersWallet(new Wallet(process.env.PRIVATE_KEY!));
+```
+
+For a custodian, implement the interface over its own digest-signing call — `buildEnvelope`
+needs only `signDigest`. Two details the implementation must get right:
+
+- **Sign the raw digest.** Not `signMessage` — that applies the EIP-191 prefix, and the
+  resulting signature will not verify as a Data Integrity proof.
+- **Return `v ∈ {0, 1}`.** The `+27` alignment is applied once downstream. A signature whose `v`
+  is already 27 or 28 is **refused**, because applying it twice recovers a *different* address:
+  a well-formed signature that verifies as somebody else.
+
+## Signing both surfaces
+
+```ts
+import { Wallet } from 'ethers';
+import {
+  PaymentGatewayClient,
+  signPaymentRequest,     // transfer authorization — lives at the package root
+  createSenderSigner,
+} from '@atum-labs/payment-gateway-client';
+import {
+  signDeclaration,        // document proof — the signing surface is its own subpath
+  signerFromEthersWallet,
+} from '@atum-labs/payment-gateway-client/signing';
+
+const wallet = new Wallet(process.env.PRIVATE_KEY!);
+
+// 1. Authorize the transfer. Fills every sender_auth.signed_messages[] entry, and attaches
+//    payload.delegate_signer on chains whose signatures are not recoverable (Solana).
+const authorized = await signPaymentRequest(request, createSenderSigner(/* ... */));
+
+// 2. Attest the document.
+const signed = await signDeclaration(authorized, signerFromEthersWallet(wallet), { chainId: 1 });
+
+// 3. Submit.
+await new PaymentGatewayClient({ BASE: gateway }).payments.submitPayment({ requestBody: signed });
+```
+
+## Check what you are signing
+
+`signPaymentRequest` signs **every** entry in `sender_auth.signed_messages[]` as given. It does
+not check that the terms inside those messages are the ones you agreed to, and neither does the
+Go client — the same is true of building the request in the first place, because the permit's
+spender, escrow and amounts come from the gateway's chain defaults.
+
+That is a deliberate division of labour, not an oversight: the SDK holds no notion of what you
+intended. But it means a gateway that returned hostile defaults would have your wallet sign a
+permit naming an address you never chose, and nothing in the signing path would object.
+
+If you are signing on behalf of someone else's funds, bind the signed permit to the terms **you**
+agreed before the request leaves your process. `verifyPaymentRequest` recovers every
+`signed_messages[]` entry and checks the terms it actually commits to:
+
+```ts
+import { verifyPaymentRequest } from '@atum-labs/payment-gateway-client/signing';
+
+// Sign locally, then bind the result to your own terms before submitting.
+const { recoveredAccount } = verifyPaymentRequest(signed, {
+  sourceAsset: agreedTokenAddress,
+  network: 'eip155:1',
+  maxSourceAmount: agreedMaxAmount,
+});
+```
+
+`sourceAsset` is the **bare token address**, not a CAIP-19 identifier — it differs in shape from
+the request's own `source.asset_identifier`, which is full CAIP-19. Passing the CAIP form here
+fails to match and rejects a request that was in fact correct.
+
+**Pass those three fields.** Called bare, `verifyPaymentRequest` takes the token, network and
+amount *from the request itself*, so it proves only that the signatures are self-consistent with
+the request's own stated fields — which a hostile gateway controls. It is the `sourceAsset` /
+`network` / `maxSourceAmount` arguments that turn it into a check against your terms, and
+omitting them is the difference between a real check and a reassuring one.
+
+It is strict by design: every entry must be a bindable permit, and a malformed one throws rather
+than being skipped. A caller with deliberately mixed messages — say an EVM setup approval
+alongside the permit — must compose the per-entry adapter calls itself and own the skip policy.
+
+In Go, `senderauth.GetChainAdapter(caip2).RecoverAndVerify(signed, source, expected)` returns the
+same signed terms for the same comparison.
+
+A custodial signer is the natural place to enforce this: it is the component that can refuse.
+
+## Verifying
+
+`verifyDeclaration` **throws** on an invalid proof rather than returning a flag — a boolean can
+be ignored by accident, an exception cannot. It also refuses a document whose signature recovers
+a signer other than the one the document claims, which is what makes a tampered document fail
+rather than verify as its original signer.
+
+It returns a **discriminated** signer:
+
+```ts
+const { signer } = await verifyDeclaration(signed);
+
+if (signer.kind === 'recovered-secp256k1') {
+  // The address was recovered FROM the signature: self-evident proof of which key signed.
+  console.log(signer.address);
+} else {
+  // Self-asserted: the ed25519 key came from the document itself. A successful verify proves
+  // the signature matches that key — NOT that the key belongs to anyone in particular. Bind it
+  // to a trusted source before relying on it.
+}
+```
+
+## What the proof does and does not cover
+
+The proof is computed over the **URDNA2015-canonicalized** document, so it is stable across key
+reordering and whitespace, and it excludes signing artifacts and the deprecated credential
+carriers.
+
+One consequence worth knowing: **canonicalization drops terms the declaration `@context` does not
+define.** A field this client's types do not model travels inside the signed document without
+being covered by the proof, and can be altered without invalidating it. Making a new field
+tamper-evident means adding it to the declaration context, not just to the payload.
+
+Any `@context` on the input is **replaced** before hashing, so a caller-supplied one cannot
+influence what gets signed.
+
+## Contexts are local, always
+
+JSON-LD contexts are compiled into the bundle. **Nothing is fetched over the network** — there is
+no HTTP client in the signing libraries, and the JSON-LD processor is always handed the local
+loader in place of its built-in fetcher. A document whose `@context` names an unregistered URL is
+refused rather than resolved, since an attacker-served context could otherwise change what each
+term means, and therefore what the signature covers.
+
+One precision, because this page is about what your signatures cover: the embedded copies can be
+overridden by an environment variable intended for development against a modified snapshot. It
+reads from local disk, never the network, and nothing in normal operation sets it — but if it is
+set, the library now says so on first use rather than substituting the contexts silently.
+
+This is structural: there is no HTTP client in the signing libraries, and the JSON-LD processor
+is always handed the local loader in place of its built-in fetcher.
+
+## The identity envelope
+
+**Read this before the example: you need an issuer-signed credential about yourself, and
+originators do not hold one yet.** The schema requires at least one credential and rejects an
+empty bag, so until issuance exists this surface cannot be exercised end to end. It
+is documented because the shape is stable and the signing half is done, not because it is
+callable today.
+
+`buildEnvelope` wraps the originator's issuer-signed credentials in a holder-signed
+PaymentRequestEnvelope. It takes the same kind of signer as the other surfaces, so a custodial
+key works here too.
+
+```ts
+import { buildEnvelopeForAccount, computeRequestHash, signerFromEthersWallet } from '@atum-labs/payment-gateway-client/signing';
+
+const envelope = await buildEnvelopeForAccount('eip155:1', wallet.address.toLowerCase(), {
+  holderVCs: [knownToAtumCredential],
+  signer: signerFromEthersWallet(wallet),
+  // The challenge is the request's content hash, which the gateway recomputes.
+  challenge: await computeRequestHash(request),
+  // The domain the gateway you are calling expects. It is compared exactly, so an envelope built
+  // for one environment is rejected by another, and it is NOT derived from the gateway URL —
+  // take it from that environment's configuration rather than assuming it.
+  domain: envelopeDomainForYourEnvironment,
+});
+```
+
+Three things the verifier enforces, so they are not optional:
+
+- **At least one credential.** The schema requires it and an empty bag is rejected — see the
+  prerequisite above.
+- **The challenge binds one request** and **the domain binds one environment**. Both are checked
+  against the values the gateway expects, so an envelope cannot be replayed across either.
+- **The declaration type is bound into the signature**, not merely present in the document —
+  editing the `type` array does not make a PaymentRequestEnvelope pass where a FulfillmentQuoteEnvelope is expected.
+
+Sign the inner document with the **same key**: the gateway asserts the document's signer is
+the envelope's holder, and rejects the pair otherwise.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atumlabs/payment-gateway-client",
-  "version": "2.2.0",
+  "version": "3.0.1",
   "description": "TypeScript client for Atum Payment Gateway API",
   "author": "Atum Labs, Inc.",
   "homepage": "https://github.com/Atum-Labs/protocol/tree/main/payment-gateway-client#readme",
@@ -31,39 +31,59 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./signing": {
+      "types": "./dist/signing.d.ts",
+      "default": "./dist/signing.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "send-payment": "./dist/cli/send-payment.js",
     "request-quote": "./dist/cli/request-quote.js",
     "quote-status": "./dist/cli/quote-status.js",
-    "payment-status": "./dist/cli/payment-status.js"
+    "payment-status": "./dist/cli/payment-status.js",
+    "approve-permit2": "./dist/cli/approve-permit2.js"
   },
   "scripts": {
-    "generate": "openapi-ts --input ../schemas/apis/payment-gateway/v1/openapi.yaml --output ./src/generated --client axios --name PaymentGatewayClient --useOptions",
-    "prebuild:deps": "node -e \"if(!require('fs').existsSync('../key-management/common/typescript/tsconfig.json')){console.error('protocol key-management packages not found at ../key-management. Is this checked out inside the protocol monorepo?');process.exit(1)}\"",
-    "build:deps": "tsc -p ../key-management/common/typescript/tsconfig.json && tsc -p ../key-management/providers/turnkey/typescript/tsconfig.json && tsc -p ../contracts/svm/escrow-encoding/typescript/tsconfig.json && tsc -p ../contracts/evm/escrow-encoding/typescript/tsconfig.json && tsc -p ../contracts/tvm/escrow-encoding/typescript/tsconfig.json && tsc -p ../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/tsconfig.json",
-    "build": "pnpm run build:deps && tsup && chmod +x dist/cli/*.js && node scripts/stamp-entry-headers.mjs",
-    "pretest": "pnpm run build:deps",
-    "test": "jest",
-    "clean": "rm -rf dist ../key-management/common/typescript/dist ../key-management/providers/turnkey/typescript/dist ../contracts/svm/escrow-encoding/typescript/dist ../contracts/evm/escrow-encoding/typescript/dist ../contracts/tvm/escrow-encoding/typescript/dist ../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/dist",
+    "generate": "openapi-ts --input ../schemas/apis/payment-gateway/v1/openapi.yaml --output \"${PGC_GEN_OUT:-./src/generated}\" --client axios --name PaymentGatewayClient --useOptions",
+    "lint": "eslint . --max-warnings 0",
+    "prebuild:deps": "node -e \"if(!require('fs').existsSync('../pnpm-workspace.yaml')){console.error('protocol workspace not found at ../pnpm-workspace.yaml. Is this checked out inside the protocol monorepo?');process.exit(1)}\"",
+    "build:deps": "pnpm --filter \"@atum-labs/payment-gateway-client^...\" run build",
+    "build": "tsup && chmod +x dist/cli/*.js && node scripts/stamp-entry-headers.mjs",
+    "typecheck:tests": "tsc -p tsconfig.test.json",
+    "test": "pnpm run typecheck:tests && jest",
+    "clean": "rm -rf dist && pnpm --filter \"@atum-labs/payment-gateway-client^...\" run clean",
     "check:publishable": "node scripts/check-publishable.mjs",
     "gen:notices": "node scripts/gen-third-party-notices.mjs",
     "prepare": "pnpm run build",
-    "prepublishOnly": "pnpm run build && pnpm run check:publishable"
+    "prepublishOnly": "pnpm run build && pnpm run check:publishable",
+    "prebuild": "node scripts/gen-pre-context.mjs",
+    "check:pre-context": "node scripts/gen-pre-context.mjs --check"
   },
   "dependencies": {
     "@solana/web3.js": "^1.91.0",
-    "axios": "1.13.2",
+    "axios": "1.20.0",
     "bs58": "^6.0.0",
     "commander": "^12.0.0",
     "dotenv": "^16.6.1",
     "ethers": "^6.11.0",
+    "jsonld": "8.3.3",
     "tweetnacl": "^1.0.3",
     "zod": "^3.25.0"
   },
   "devDependencies": {
+    "@atum-labs/chain-address": "workspace:*",
     "@atum-labs/evm-escrow-encoding": "workspace:*",
     "@atum-labs/km-core": "workspace:*",
+    "@atum-labs/ld-signing": "workspace:*",
+    "@atum-labs/payment-request-ld-signing": "workspace:*",
     "@atum-labs/payment-request-sender-auth": "workspace:*",
+    "@atum-labs/payment-request-token-approval": "workspace:*",
     "@atum-labs/publish-guard": "workspace:*",
     "@atum-labs/solana-escrow-encoding": "workspace:*",
     "@atum-labs/turnkey-signer": "workspace:*",
@@ -71,7 +91,10 @@
     "@hey-api/openapi-ts": "^0.45.1",
     "@types/jest": "^29.5.5",
     "@types/node": "^20.0.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "jest": "^29.7.0",
+    "tronweb": "^6.0.0",
     "ts-jest": "^29.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.0.0",
@@ -83,10 +106,21 @@
     "CHANGELOG.md",
     "docs/**",
     "LICENSE",
-    "THIRD-PARTY-NOTICES.txt"
+    "NOTICE",
+    "THIRD-PARTY-NOTICES.txt",
+    "signing.js",
+    "signing.d.ts"
   ],
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "Apache-2.0",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
+  },
+  "peerDependencies": {
+    "tronweb": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "tronweb": {
+      "optional": true
+    }
   }
 }

package/signing.d.ts

@@ -0,0 +1,2 @@
+// Types for the subpath shim. See signing.js for why both exist.
+export * from './dist/signing';

package/signing.js

@@ -0,0 +1,11 @@
+// Subpath shim for the classic Node resolution algorithm.
+//
+// package.json's "exports" map already declares "./signing", but `moduleResolution: "node"` —
+// still the default for plenty of consumers — does not read "exports" at all. It resolves
+// `@atum-labs/payment-gateway-client/signing` by looking for this file on disk. Without it the
+// subpath works under "node16"/"bundler" and fails everywhere else, which is a failure a
+// consumer meets at install rather than one we meet in CI.
+//
+// The publish guard caught exactly that: it type-checks against the packed tarball on the default
+// settings, and the import did not resolve until this existed.
+module.exports = require('./dist/signing.js');