@atumlabs/payment-gateway-client 2.2.0 → 3.0.1

package/CHANGELOG.md

@@ -5,6 +5,114 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+- **Breaking: `PaymentStatus` is one type across all three payment responses**, with the values `pending`, `finalizing`, `completed` and `failed`. Submitting a payment, polling its status and reading its timeline previously returned three unrelated status types, so a caller could not write one function that handled "a payment status". `settling` is gone — it described how far our own bookkeeping had got, not the payment. `cancelled` is gone too: nothing could produce it, and a payment that ends without being delivered is reported as `failed`. `isTerminalStatus('cancelled')` therefore returns `false` now. A caller with an exhaustive `switch` on status gets a compile error and has to add a `finalizing` branch; a caller testing only for `completed` or `failed` is unaffected.
+- **`finalizing` is new, and is NOT terminal.** It means the transaction paying the recipient is on chain and accruing the confirmations its chain requires — made, but not yet irreversible, much as a card authorization is not a settlement. It normally becomes `completed` and can still become `failed`. Nothing emits it yet; it is declared here so clients are ready before the gateway starts sending it.
+- **Breaking: one failure shape.** `PaymentError` and `TimelineError` are replaced by a single `PaymentFailure` used by all three responses, so a failure reads identically however you ask about the payment. On the timeline that is a real change of shape: `chain_id`, `tx_hash` and `revert_reason` were flat on the error and are now nested under `blockchain_context`, which also carries the four fields that endpoint previously discarded — the block number among them.
+- **Breaking: `tx_hash` is now `transaction_hash`**, on `error.blockchain_context` (all three responses) and on `steps[]` (timeline). This is the name the shared error shape and the rest of our published specs already used; the payment API was the outlier. **A caller reading `error.blockchain_context.tx_hash` gets `undefined` after upgrading** — there is no deprecation period because the field moved to the shared definition rather than being duplicated under both names.
+- `PaymentFailure` now carries `docs_url` and `retry_classification`. Both were already computed for every error code but only ever reached failed *requests*, never failed *payments*.
+- The `payment-outcome` CLI no longer maps `cancelled` to exit code 3 (terminal failure), because the gateway no longer reports it. A status this build does not recognise exits 2 (still pending), which is the safe direction: a script that waits one more round costs a poll, a script that gives up on a live payment can cost a second charge.
+- **New `transactions` object** (`deposit`, `fulfillment`) on all three responses, for looking a payment's on-chain transactions up yourself. Declared but not yet populated.
+
+### Security
+- The HTTP client is now axios 1.20.0. 1.13.2 had a run of advisories (prototype-pollution gadgets that could tamper with requests or responses, proxy-authorization leaks, NO_PROXY SSRF, ReDoS). A caller that pins axios independently should take 1.18.0 or newer. A timeout that fires after headers have arrived still surfaces as `GatewayTimeoutError`: axios 1.20 attaches the partial response, and the client drops it so a stalled error body is not reported as a completed HTTP status.
+
+## [3.0.1] - 2026-09-18
+
+### Changed
+- Published under Apache-2.0 with `publishConfig.access: public`. npm will not overwrite 3.0.0, so this version exists to ship the LICENSE, NOTICE, and public visibility that 3.0.0 cannot take.
+
+## [3.0.0] - 2026-09-16
+
+> **Read this before upgrading if the gateway has been accepting your asset identifiers.**
+> They are now validated locally, on both entry points and on both legs of the payment. One rule
+> is stricter than the gateway's, the EIP-55 checksum on a mixed-case EVM token address, so a
+> value the gateway resolves fine can be refused before the request is even built. See Breaking.
+>
+> A second break sits there too. A blank `pinnedAddress` is now rejected rather than skipping the
+> sender check, so a caller that defaults that field to an empty string has to pass the sender
+> address instead, or omit the field to skip the check on purpose.
+
+Quote-requests now carry the same idempotency contract as payments: one `request_id`
+identifies one batch, re-sending it recovers that batch, and reusing it for a different
+corridor is refused rather than silently served.
+
+### Breaking
+- Asset identifiers are validated on every entry point. `prepareQuoteRequest` built no deposit and so applied no address rules at all, and `preparePaymentRequest` applied them only to the source, since only the source reached a chain library. Both legs of both entry points are now checked, so a value that used to be forwarded can now be refused locally, with the messages under Fixed: a malformed or wrongly-checksummed EVM token address, a placeholder such as `erc20:0x6`, a native `slip44` asset, a malformed Tron or Solana token reference, or a hex `eip155` chain id. Every segment is also checked against the character set the PaymentRequest schema publishes, so a stray space is refused here rather than remotely.
+- **A mixed-case EVM token address whose EIP-55 checksum does not hold is refused on the destination leg too, and that is deliberate.** The gateway tolerates such a destination on purpose: `blockchain.AssetIdentifier.Equal` folds the case of an eip155 token address with `EqualFold`, the token registry lowercases before it looks a token up, and `payment-gw/internal/canonical` folds a destination it could not parse rather than refusing it, precisely so two spellings of one destination cannot refuse a legitimate retry. The settler lowercases before it checksums, so a wrong checksum settles fine. This rule therefore buys no settlement safety. It is typo protection while the request is still being built, kept fatal because a mistyped token address is cheap to catch here and expensive to discover once a payout has landed on it. It is narrow on purpose: the destination account is not checked, so this is not a claim that the client validates the receive side. A caller that can rewrite the value should send the all-lowercase form of the destination, which makes no checksum claim, is accepted, and is the same twenty bytes. A caller whose corridor is composed inside a library that builds the request for it, as in `mppx-atum-escrow`, has nothing to rewrite, and the lowercasing belongs there.
+- **Behaviour change.** An empty `pinnedAddress` is now rejected before anything is signed or submitted, on both signing providers. It previously counted as omitting the field, so the check that the sender is the signer's own address was skipped: the Turnkey path forwarded the pin only when truthy, and the private-key path gated its key-derivation check the same way. What that produced depended on the caller. `send-payment` derives the depositor from the same `<sender>` argument, so the payment went out with an empty source account for the gateway to reject. An SDK caller that supplies `depositor` and `pinnedAddress` separately got a valid, settleable payment whose sender was never checked against the wallet or the key, which is the case this closes. A call that previously proceeded now throws, so a caller defaulting the field to `''` needs to fall back to the sender address instead. Omitting `pinnedAddress` still skips the check as before.
+- `prepareQuoteRequest` now **requires** `requestId`, and `requestIdPrefix` is gone. It
+  previously generated an id when you omitted one, on the grounds that the id was only a
+  correlation handle there — which is no longer true, because it is now the idempotency key.
+  Generating one for you meant a rebuilt retry quietly opened a **second** batch and left the
+  first unreachable. `preparePaymentRequest` has always required it; the two now match. The requirement is
+  enforced at runtime as well as in the type, so an untyped JavaScript caller or an empty
+  string throws rather than sending a request with no idempotency key. Pass
+  your own stable id, and reuse it to retry. The `request-quote` CLI is unaffected: it
+  generates an id when `--request-id` is omitted and prints it back, exactly as `send-payment`
+  does.
+- `QuoteRequestResponse.idempotent_replay` and `QuoteRequestAccepted.idempotent_replay` are new
+  **required** fields. Reading a response is simpler, not harder — the flag is always present,
+  so `false` means `false` rather than "maybe an older gateway".
+- **The error `domain` value `SOLVER_GATEWAY` is now `SETTLER_GATEWAY`.** It names the service that runs the settler auction, which is a settler gateway; the old name was left over from earlier terminology and was the only place the word "solver" still reached callers. Code that switches on `AtumError.domain` and has a `'SOLVER_GATEWAY'` case must rename it — nothing else about the error changes, and `domain` is diagnostic metadata rather than something the payment flow branches on, so most callers are unaffected. The public `code` and `message` on an error are unchanged: the internal codes behind this domain already mapped to the public `SERVICE_BUSY` and `INTERNAL_ERROR`, and still do.
+
+### Added
+- **`ensureSourceApproval` and `needsSourceApproval`**, so the Permit2 prerequisite this package has always stated can now be satisfied from it. Paying from EVM or Tron needs a one-off approval of the source token for Permit2; without it a payment is built correctly, signed correctly, accepted by the gateway, and then reverts on-chain at settlement — the most expensive way to learn about a missing allowance. Until now the README and `send-payment --help` named the requirement and offered no way to meet it. `ensureSourceApproval` reads the current allowance and sends an approval only if it falls short; `needsSourceApproval` answers the same question read-only, spending no gas, so a payer can be warned before being asked to sign. Solana reports that no approval is needed rather than doing nothing, since its deposit authorizes the transfer itself. **This is the first part of this package that broadcasts a transaction and spends gas.** Everything else builds and signs offline, and that has not changed: you pass a connected ethers signer (or a TronWeb instance for Tron), so the package still never chooses an RPC endpoint or holds a key. An approval is unlimited by default, so later payments need no further transaction; `approvalAmount` bounds it instead, at the cost of having to renew it as Permit2 consumes it — pair a bound with `requiredAllowance` across repeated payments, or the bound stops covering itself as soon as the first charge is decremented from it. Waiting for the approval to confirm is bounded by `confirmation.timeoutMs` (one minute by default) rather than indefinite, and `onSubmitted` hands you the transaction hash the moment it is broadcast. Tokens that refuse to overwrite a non-zero allowance — mainnet USDT most notably — are reset to zero first, but only where the token actually demands it. An approval is refused outright when the signer you pass does not hold the `owner` account whose allowance was read: an approval only ever applies to the account that sends it, so a mismatched signer would approve that account, hand back a transaction hash that reads as success, and leave the owner exactly as unable to pay as before. The read-only `needsSourceApproval` is unaffected, since asking whether a payer is ready without holding their keys is a legitimate preflight. `isUnconfirmed` ships alongside them for telling a broadcast-but-unseen approval apart from one that failed: the wait for a confirmation is bounded, and reaching that bound is not a failure, so the two need opposite responses. `approve-permit2` reports an unconfirmed run as `{"unconfirmed": true, "txHash": ...}` on stdout rather than as a bare non-zero exit indistinguishable from a revert. These helpers raise an allowance and never lower one, so `--amount` below an allowance the wallet already holds leaves it alone and says so.
+- **`approve-permit2`**, a command that performs that approval. `approve-permit2 <sender> <sourceAsset> --rpc-url <url>` takes the same CAIP-19 asset string as `send-payment`, and `--check` reports whether an approval is needed without sending anything or needing a key. It is a separate command rather than a flag on `send-payment` because it is a different kind of act: it spends gas, once per wallet and token, and is worth doing deliberately and ahead of time rather than as a side effect of paying. The private key comes from `PRIVATE_KEY` or an interactive prompt and is never accepted as a flag, which would put it in shell history and in the process list. EVM and Tron; Tron additionally needs `tronweb`, an optional peer dependency, so that EVM-only installs do not carry it. The result JSON goes to stdout, like the other commands. The allowance is read before a key is ever requested, so an already-approved wallet — which is every wallet after the first run — never has to produce a secret to learn there was nothing to do, and the key is checked against `<sender>` before anything is sent, so a mismatched key cannot approve the wrong account and report success.
+- **Signing helpers for all three PaymentRequest signatures**, available from the `@atum-labs/payment-gateway-client/signing` subpath. A PaymentRequest carries three unrelated signatures and choosing the wrong one is the mistake this surface exists to prevent, so they are named for what they authorize rather than for how they are built. `signPaymentRequest` fills `sender_auth.signed_messages[]` and authorizes the **on-chain transfer**. `signDeclaration` attests that the **document** came from its signer, as a W3C Data Integrity proof over the URDNA2015-canonicalized request — it is exported under that name, rather than the upstream library's `signPaymentRequest`, precisely so the two cannot be confused. `buildEnvelope` and `buildEnvelopeForAccount` carry the **originator's identity** as a holder-signed PaymentRequestEnvelope. Signing one does not stand in for another: a request with a valid `sender_auth` and no envelope authorizes a transfer by an unidentified originator, and the reverse identifies an originator who has authorized nothing. Every one of them takes a **signer, never a private key** — a hex key would force raw key material into a JavaScript string that cannot be zeroized, is copied on assignment, and lands in heap snapshots and any log line that stringifies the surrounding object, and it would exclude every custodian whose key sits in a KMS or an HSM. `signerFromEthersWallet` covers a local key; a custodial signer implements `signDigest` over its own call. The signature contract is 65 bytes of `r || s || v` with **v ∈ {0, 1}**: a signature whose v is already 27 or 28 is refused, because applying the alignment twice recovers a *different* address, which is a well-formed signature that verifies as somebody else. Also exported: `computeRequestHash`, `verifyDeclaration` (which **throws** rather than returning a flag, and refuses a document whose signature recovers a signer other than the one it claims), `verifyPaymentRequest` for checking what a `sender_auth` signature actually commits to before submitting, `didForAccount`, `verificationMethodForAccount`, and their types. See `docs/signing.md`.
+- **`jsonld` is a new dependency**, and it is pinned exactly rather than floating. It runs URDNA2015, the canonicalization that determines exactly what a signature covers, so a minor release that changed its output would change what customers sign, on their machines, with nothing in our CI to notice.
+- **`send-payment --prepare-only` and `send-payment --submit <file>`** split the single-shot command in two. `--prepare-only` builds and signs a payment request, prints it to stdout, and stops without submitting; `--submit` sends one that was prepared earlier (`-` reads stdin, so the two pipe together). Together they turn the single-shot command into an inspect-then-approve flow: the printed document is byte-for-byte what that run would have POSTed, so it can be read and reviewed before any money moves. Treat it like a signed cheque: it is a signed authorization rather than a draft and `--submit` needs no key, so delete the file once the payment is sent or abandoned. Re-preparing under the same `request_id` targets the same payment and cannot pay twice, but does not reproduce the same bytes: the deadlines are stamped from the clock on each run and the signature covers them. Two things to know. `--prepare-only` still calls the gateway, which is where the corridor addresses come from, so it is not an offline signing mode. And the exit-code table describes a *submitted* payment, so it does not apply under `--prepare-only`, where `0` means the request was built and signed and no payment exists — do not chain a payment-conditional step off such a run. If you intend to submit later, widen the quote window with `--quote-deadline-seconds` — but by tens of seconds, not minutes. A prepared document is submittable only while its window is open (the default is 10 seconds), and that same window is the settler auction: the gateway waits it out before selecting, and settler quotes expire on their own, so an over-long window ends in a terminal `QUOTES_EXPIRED`. `--submit` signs nothing and needs no private key, takes no corridor arguments, refuses the options that only shape a request being built rather than ignoring them, and reports with the same exit codes and streams as an ordinary run; it supports `--wait` the same way. The two flags are mutually exclusive, and a short invocation now names both forms rather than reporting a missing argument.
+- The Permit2 approval prerequisite now appears at the top of `send-payment --help`, above the arguments and options, instead of in the last paragraph. It is the most common cause of a payment that is built and signed correctly and still fails to settle, and it was previously about a hundred lines below the usage line. The contract addresses stay at the end of the help, where the prerequisite points.
+- **`waitForTerminalStatus` and `isTerminalStatus` are exported**, so following a submitted payment to its end is one call rather than a hand-written loop. A submission usually comes back `pending`, so waiting is the ordinary path, and the previous answer — write your own poll — put the burden of getting it right on every caller. A failed status check does not end the wait: a blip while a payment is settling is the worst moment to stop looking, so failures are counted in `errorCount`, reported through `onError`, and polling continues to the budget. The outcome reports `timedOut` so a caller can tell "still in flight" from "finished", which a bare loop cannot. This is the same helper behind the `send-payment --wait` flag, so the command-line tools and the SDK now agree by construction. `isTerminalStatus` is the single definition of which states are final, so a caller no longer keeps its own copy of that list in step with the contract. `budgetMs` is optional and in milliseconds, defaulting to `DEFAULT_WAIT_BUDGET_MS` (one minute); the seconds-based constant behind the command line's `--wait-seconds` stays internal, so there is one unit on the public surface and no way to pass 60 where 60000 was meant. An optional `signal` ends the wait early for a caller that must stop on shutdown or when its request is cancelled, and the outcome reports `aborted` — which always implies `timedOut`, so an interrupted wait can never be read as a settled payment. Also exported: `DEFAULT_WAIT_BUDGET_MS`, `DEFAULT_POLL_INTERVAL_MS`, `StatusSnapshot`, `WaitOutcome`, `WaitParams`.
+- **`ErrorResponse.payment_id`**, alongside the existing `request_id`. The two ids are independent and either can be absent: `request_id` correlates the HTTP call, and `payment_id` names the payment the error was raised against. It closes a real mislabel. A settlement failure on `POST /v1/payments` was returning the payment id in `request_id`, because that was the only id field the shape had, so a caller who trusted the field name and looked the value up as a request id found nothing. Read `getErrorResponse(err)?.payment_id` and reconcile with `GET /v1/payments/{paymentId}/status` before retrying, because a failed settlement leaves the on-chain outcome unguaranteed. The field is absent whenever the error is not about a specific payment, which is every validation or authentication failure raised before a payment exists.
+- `parseAssetIdentifier` and `assetChainId` are exported, so a caller can apply the same parsing and canonicalization the CLIs do.
+- `timeoutMs` and `syncWaitTimeoutMs` on the client config, for callers whose gateway is slower than the defaults (30s for a promptly-answered request, 120s for one the gateway holds open). The two are separate because some endpoints are held open on purpose, bounded by the gateway's own `quote_sync_wait_seconds` and `payment_sync_wait_seconds`, so one budget cannot serve both: too short aborts a settling payment, too long leaves an unresponsive gateway hanging. An interceptor that sets `timeout` still takes precedence, for a per-request override. New exports: `GatewayTimeoutError`, `isGatewayTimeoutError`, `PaymentGatewayClientConfig`, `RequestTimeouts`, `DEFAULT_REQUEST_TIMEOUT_MS`, `DEFAULT_SYNC_WAIT_TIMEOUT_MS`.
+- `createQuoteRequest` returns **`409` `IDEMPOTENCY_TERMS_MISMATCH`** when a `request_id` is
+  reused with different economics (accounts, assets, or amounts), instead of returning the
+  first batch. Without it you could receive quotes priced for the corridor you asked for
+  earlier, and awarding one of those settles a payment on that corridor.
+- `idempotent_replay` on both quote-request responses tells you whether you were handed an
+  existing batch or a newly opened one.
+
+### Changed
+- `resolveTurnkeyAddresses` takes its Turnkey config without `pinnedAddress`. That call lists the wallet's accounts and verifies nothing, so a pin handed to it was ignored. Passing one inline is now a compile error instead of a check that never ran. A caller reusing one whole `TurnkeyConfig` for both this call and signing is unaffected.
+- The CLIs no longer print the full gateway defaults listing when a chain-defaults lookup fails. The failure itself names the chain and carries the gateway's error, and the client no longer makes the second `/defaults` request that fetched the listing.
+- Re-sending a quote-request whose `quote_deadline` has already passed now returns the original
+  batch instead of `400 QUOTE_DEADLINE_NOT_FUTURE`. The collection window is short, so a retry
+  after a lost response almost always carries an expired deadline — previously that made the
+  `quote_request_id` unrecoverable even though the batch existed and held quotes. Deadlines are
+  exempt from the idempotency comparison, on this endpoint as on payments.
+- Note the window itself is not extended: it belongs to the batch, so asking again with a later
+  `quote_deadline` returns the batch's own window.
+- `docs/idempotency.md` is reorganised around the shared contract rather than the payment
+  endpoint, with the endpoint-specific parts (the on-chain settlement guarantee, payment status)
+  labelled as such.
+- The `409 IDEMPOTENCY_TERMS_MISMATCH` message no longer says a *payment* exists. It previously
+  read "already used for a payment with different terms", which is wrong on quote-requests —
+  nothing is charged there and no payment exists for the caller to go looking for. It now says
+  "already used for a different request". This affects the payments path too: the wording is
+  slightly less specific there, in exchange for being correct on both. The `code` and the docs
+  link are unchanged, so nothing a client branches on has moved.
+- The asynchronous (202) quote-request response now says plainly that its `status` field is a
+  constant rather than a report of the batch's state: on an idempotent replay the window may
+  already have closed and it will still read `collecting`. Points at
+  `GET /v1/payments/quote-requests/{quoteRequestId}` instead. Documentation only.
+
+### Fixed
+- A malformed asset identifier is reported with the offending value and what to correct, instead of surfacing as a chain-library error. A missing `/` between the chain and the token says `Invalid asset identifier "<value>": expected CAIP-19 "<chain>/<type>:<address>", e.g. eip155:421614/erc20:0x...` where it previously threw `TypeError: Cannot read properties of undefined (reading 'split')`. An empty token or a stray slash says `Invalid token address in asset "<value>".`, and a mixed-case address whose EIP-55 checksum does not hold says `Token address "<addr>" has an invalid checksum. Fix the capitalization or use the all-lowercase form.` Those were `invalid address` and `bad address checksum` respectively, from `ethers`. Two cases name their real cause rather than the address they were also reported as: a hex `eip155` chain id says `Invalid eip155 chain id "0x66eee" in asset "<value>": use the decimal chain id (421614), not hex.` and any other non-decimal reference says `Invalid eip155 chain id "<reference>" in asset "<value>": an eip155 chain id is decimal, e.g. 421614.`, while a native asset says `Asset "<value>" is a native asset (slip44) and has no contract to deposit. Use the wrapped token's erc20 identifier.`
+- An identifier whose CAIP-2 namespace is not lowercase (`EIP155:42161/...`) is routed rather than refused as an unsupported chain. Both namespaces are canonicalized to lowercase in the request the client builds and in the deposit it signs, which is what the PaymentRequest schema requires, so such a request is no longer rejected by the gateway either.
+- A Tron chain reference is folded with the namespaces, mirroring the protocol's own `manifest.CanonicalizeCAIP2`, so `TRON:MAINNET/trc20:...` routes instead of failing inside the sender_auth SDK with `no Permit2 address known for Tron network`. A Solana reference is still left alone: it is base58, and its cluster name is UTF-8 encoded into the escrow's on-chain `cluster_id`, so folding it would change the signing domain.
+- A failed chain-defaults lookup reports the gateway's own `code`, `message` and `request_id` instead of the HTTP status text, which reduced every cause to `Bad Request`.
+- A non-integer value for `--quote-deadline-seconds`, `--fulfillment-deadline-seconds` or `--wait-seconds` (for example `1.5`, `1e3`, `0x10`, or plain text) now prints the one-line reason and exits `1`, instead of a full Node stack trace. The CLIs already refused to run with such a value and the exit code is unchanged; only the output is. The option parser runs before the command's error handling, so what it threw had been escaping uncaught.
+- A whitespace-only `pinnedAddress` was not skipped but reported as an address mismatch, so the error named a padded value rather than the actual problem. It now gets the same up-front rejection as an empty one.
+- `send-payment` validates `<sender>` before prompting for a private key, so a blank argument no longer costs the user an entered secret first.
+- Gateway requests now time out instead of hanging. The client had no network timeout: the chain-defaults call used a bare `fetch` with no abort signal and the HTTP client set none, so a gateway that accepted the connection and never replied left the CLI waiting indefinitely with nothing on stdout or stderr. Requests now abort and raise a `GatewayTimeoutError` reading `Gateway at <url> did not respond within <n>s`. The abort covers the response body as well as the headers, so a gateway that returns `200` and then stalls is caught too, as is one that answers a chain-defaults failure and then stalls the error body the message is read from.
+- **The Solana signing format in the published types was wrong.** `SignedMessage.message` was documented as a base64-encoded message on Solana, where the value the network verifies is the hex-encoded message hash with a `0x` prefix, as it is on EVM and Tron. A caller following the type's own documentation produced a signature that could not be recovered, and the request was refused with nothing in the message pointing at the encoding. The description now matches the format that is signed and verified. Types and runtime behaviour are unchanged; only what the types say about them.
+- `SenderAuthMessageScheme` documents `EVM_PERMIT2_ESCROW`. The value has always been accepted and appeared in the type's union, but the accompanying description listed only the other three, so the one scheme that pairs a gasless approval with escrow support read as undocumented.
+- `SenderAuth.verifiable_credential` is marked deprecated in the published type, which it already was in the format that is signed. Credentials belong in the holder-signed `PaymentRequestEnvelope`; the inner request carries none, and its Data Integrity signature excludes this field. A caller still populating it can see that from the type now rather than only from the signing schema.
+
 ## [2.2.0] - 2026-08-04
 
 > **Read this before upgrading if you script `send-payment`.** Its exit codes now

package/LICENSE

@@ -1,83 +1,202 @@
-# ATUM LABS, INC. – PAYMENT GATEWAY CLIENT PRIVATE REPOSITORY LICENSE AGREEMENT
-**Last Updated: January 28, 2026**
-
-This Private Repository License Agreement (“Agreement”) governs your (“Licensee”) access to the Atum Labs, Inc. (“Atum”) private GitHub repository containing Atum’s proprietary source code, SDK components, documentation, and implementation examples relating to the Atum Payment Gateway Client (“Payment Gateway Client Code”).
-By accessing or using the Repository, Licensee agrees to be bound by this Agreement.
-## 1. Purpose of Access
-Atum is granting limited access to the Payment Gateway Client Code solely for the following permitted purpose (the “Authorized Purpose”):
-- Integrating, installing, operating, and testing the Payment Gateway Client in connection with Licensee's use of the Atum settlement network, Goji-facing transaction flows, and any other Atum-authorized payment operations.
-- Conducting internal audits, security review, and compliance assessments necessary to support the above operations.
-
-No other use is permitted.
-## 2. License Grant
-Subject to Licensee’s full compliance with this Agreement, Atum grants Licensee a limited, revocable, non-exclusive, non-transferable, non-sublicensable license to:
-1. Access the private GitHub repository containing the Payment Gateway Client Code (“Repository”);
-2. Download and internally use the Payment Gateway Client Code solely for the Authorized Purpose;
-3. Deploy and run compiled or interpreted versions of the Payment Gateway Client Code only within Licensee’s secure infrastructure and only for the Authorized Purpose;
-4. Create internal configuration changes or implementation wrappers necessary for integration, provided that all such modifications remain Atum Confidential Information and are disclosed to Atum upon request.
-
-No other rights are granted.
-## 3. Restrictions
-Licensee must not, and must not permit any third party to:
-1. Use the Payment Gateway Client Code for any purpose outside the Authorized Purpose;
-2. Make the Repository or any portion of the Payment Gateway Client Code available to any third party, including affiliates, without Atum’s written consent;
-3. Publicly disclose, publish, or commit any portion of the Payment Gateway Client Code to any public forum or repository;
-4. Use the Payment Gateway Client Code to build or support any competing products or networks;
-5. Reverse engineer, decompile, or otherwise attempt to derive the underlying trade secrets in the Payment Gateway Client Code (except to the limited extent permitted by applicable law);
-6. Remove or alter any proprietary notices;
-7. Use Atum’s code, data, or architecture to train or fine-tune any AI, LLM, or ML models;
-8. Use the Payment Gateway Client Code in violation of applicable law or Atum instructions.
-## 4. Ownership
-Atum retains all rights, title, and interest in and to:
-- the Payment Gateway Client Code,
-- the Repository contents,
-- the underlying architecture, algorithms, settlement workflows, and SDK components, and
-- all modifications, derivative works, feedback, or improvements.
-No ownership rights are transferred to Licensee.
-## 5. Confidentiality
-The Payment Gateway Client Code and all related documentation constitute Atum Confidential Information. Licensee must:
-1. Protect the code using industry-standard security practices;
-2. Disclose it only to employees or contractors with a legitimate need to know and who are bound by written confidentiality obligations at least as protective as this Agreement;
-3. Use it only for the Authorized Purpose;
-4. Not disclose it to any third party without Atum’s written consent;
-5. Upon termination, immediately cease use, destroy all copies (including cached or compiled forms), and certify destruction to Atum.
-
-## 6. Compliance and Security Requirements
-Licensee must comply with:
-- Atum’s security and technical standards for Payment Gateway integrations,
-- Atum’s operational procedures for network participants,
-- Key rotation, signing authority, and release-only settlement authority rules, and
-- Any written security or technical notices issued by Atum.
-
-Atum may audit Licensee’s technical implementation upon reasonable notice.
-## 7. No Warranty
-The Payment Gateway Client Code is provided “AS IS”, without any express or implied warranties. Atum does not warrant that the code will be error-free or suitable for any particular purpose.
-## 8. Limitation of Liability
-To the fullest extent permitted by law:
-- Atum will not be liable for any indirect, incidental, special, or consequential damages;
-- Atum’s total cumulative liability under this Agreement will not exceed $100.
-## 9. Term and Termination
-This Agreement is effective upon Licensee’s first access to the Repository and continues until:
-1. Terminated by either party with 10 days’ written notice;
-2. Automatically terminated if Licensee ceases to be an authorized Credit Coop participant on Atum’s network; or
-3. Automatically terminated upon any breach of Sections 2–6.
-Upon termination:
-- All rights granted hereunder immediately cease;
-- Licensee must stop using the Payment Gateway Client Code;
-- Licensee must destroy all copies and derivatives and certify destruction upon request.
-The following provisions survive termination:
-- Confidentiality (Section 5)
-- Security & Compliance Obligations (Section 6)
-- Ownership (Section 4)
-- Restrictions (Section 3)
-- No Warranty (Section 7)
-- Limitation of Liability (Section 8)
-- Governing Law (Section 10)
-- Any provisions intended by their nature to survive
-## 10. Governing Law
-Delaware law governs this Agreement.
-## 11. Entire Agreement
-This Agreement constitutes the entire agreement between the parties relating to the Payment Gateway Client Code and supersedes all prior or contemporaneous agreements specific to such access.
-
-ATUM LABS, INC.
-All rights reserved.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+Atum Protocol
+Copyright 2026 Atum Labs, Inc.