phala-pay 0.2.0__tar.gz

phala_pay-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/

phala_pay-0.2.0/.python-version

@@ -0,0 +1 @@
+3.14

phala_pay-0.2.0/CHANGELOG.md

@@ -0,0 +1,315 @@
+# Changelog
+
+All notable changes to `phala-pay` (formerly `crypto-topup-sdk`) are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the rules in `docs/integration.md`
+(section 5.9); versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-29
+
+The first release on PyPI.
+
+### Added
+
+- `list_forwarders` / `pay.forwarders.list` take the API's `quote` and `deposit_address` filters.
+- `Deposit.final_at`; `Config.max_open_quotes` and `max_open_amount_per_customer`
+  (`max_open_amount_per_account` is now the account's cap in the mode).
+
+### Fixed
+
+- Error responses are read leniently: a body without `doc_url` (or any field but `code`), with an
+  unknown `type`, or not JSON at all (a proxy's `502` page) raises `ApiError` (`unexpected_response`
+  when there is no error object), never `KeyError` or `JSONDecodeError`, and a retryable status
+  is retried whatever its body.
+
+### Changed (breaking)
+
+- Address checks derive every address from your pins, never from the response's `treasury`: a
+  quote or deposit address network naming another treasury than your pinned one of its chain
+  raises `AddressMismatchError`. With a live key (`ppay_sk_live_`, `ppay_rk_live_`) the check is
+  mandatory and fails closed unless `account`, `forwarder`, and `treasuries` are all given; in test
+  mode an unpinned treasury falls back to the response's with an `UnpinnedTreasuryWarning`.
+- `roll_webhook_key` / `pay.account.roll_webhook_key` default to `expires_in=172800`, the shortest
+  overlap a live roll accepts (was `0`).
+
+- `Deposit` has `amount_refunded` and `amount_reversed`, the service-computed cumulative
+  claw-backs; `Refund.receipt_log_index` replaces `log_index`, and `mark_paid(…,
+  receipt_log_index=…)` / `mark_refund_paid(…, receipt_log_index=…)` replace `log_index=`. A refund
+  marked paid can no longer be canceled. The FastAPI example applies every `deposit.*` event by
+  the balance rule (docs/integration.md §2.3).
+
+- API conformance with Stripe (docs/design/multi-tenant.md, "API conformance"): business-state
+  failures such as `deposit_not_final`, `quote_unexpected_state`, `paused`, `treasury_not_set`,
+  and `*_cap_exceeded` are `400` (only `idempotency_key_in_use` is `409`); per-customer limits are
+  `429 customer_rate_limit`; every `429` carries `Retry-After`, which the client waits.
+- `ApiError.request_id` reads only `Request-Id`; `X-Request-Id` is no longer sent. `ApiError`
+  gains `doc_url` and `retry_after`.
+- A response the service saved for an `Idempotency-Key` (now every executed request, even a
+  `500`) arrives `Idempotent-Replayed` and is raised, not retried.
+- A quote's address salt is `keccak256(abi.encode(account, client_reference_id, "quote",
+  quote_id))` (design D3; it was tagged `"lock"`): `topup_sdk.quote_salt` replaces `lock_salt`.
+- Treasury events are `treasury.created`, `treasury.updated`, and `treasury.canceled` (were
+  `account.treasury.pending|updated|canceled`).
+- The generated client has no admin API (the operator's is `openapi.admin.json`); every object's
+  `object` is a `Literal` (`literal_enums`), and so is `ErrorDetail.type_`.
+
+- The API's name for your customer is `client_reference_id` everywhere: `pay.quotes.create(
+  client_reference_id=…)`, `pay.deposits.list(client_reference_id=…)`, `Quote`/`Deposit`
+  `.client_reference_id`, `CreditedDeposit.client_reference_id`, and `topup-sdk send-test-event
+  --client-reference-id`.
+- `PhalaPay(…, forwarder=(factory, implementation))` is required and a pair, and
+  `treasuries={chain_id: treasury}` pins the treasury each address is derived from (required in
+  live mode, above). `TopupClient(forwarder=)` takes the same pair.
+- A deposit's `status` is `pending`, `credited`, `rejected`, or `reversed`, with booleans `final`
+  and `swept`; `CreditedDeposit` accepts only `credited`.
+- `Quote.payment` is the shared `Payment` model (`status` `seen` or `recorded`, with `chain_id` and
+  `asset`); `QuotePayment` is gone. `DepositAddress.payments` uses the same model.
+- `AttestationResponse.tdx_quote` replaces `.quote`.
+- Every object's `livemode` and `metadata` are required in the generated models.
+
+### Added
+
+- Restricted keys: `TopupClient`/`PhalaPay` accept `ppay_rk_…` keys, and
+  `create_api_key(name=, permissions=[...])` / `pay.api_keys.create(permissions=)` create one.
+- `pause_treasury` / `resume_treasury` (`pay.treasuries.pause`, `.resume`): the merchant's
+  crediting pause of a treasury. `topup_sdk.UnpinnedTreasuryWarning`.
+
+- Events are snapshots with their cause: `Event.request` (`EventRequest`: the `Request-Id` and
+  `Idempotency-Key` of the request that caused it, `None` for the service's workers) and
+  `EventData.previous_attributes` on `*.updated` events; new events `refund.created`,
+  `refund.updated`, and `quote.canceled`.
+- `pay.events.list(types=, delivery_success=, created_gt=, created_gte=, created_lt=,
+  created_lte=)`, `pay.deposits.list(created_gt=, created_lt=)`, and every page of
+  `pay.api_keys.list()` and `pay.treasuries.list()`. Webhook endpoints carry
+  `pending_deliveries`, `oldest_pending_at`, and `last_attempt`.
+- `Literal` hints: `phala_pay.QuoteStatus`, `DepositStatus`, `DepositAddressStatus`,
+  `RefundStatus`, `TreasuryStatus`, `ApiKeyStatus`, `WebhookEndpointStatus`, `PaymentStatus`, and
+  `EventType`.
+- `pay.account` (`retrieve`, `update(confirmation_policies=)`, `pause_quotes`, `resume_quotes`,
+  `roll_webhook_key`), `pay.api_keys`, `pay.webhook_endpoints`, `pay.events` (`list`, `retrieve`,
+  `resend`), `pay.treasuries` (`challenge`, `create`, `set_eoa`, `list`, `retrieve`, `cancel`),
+  `pay.balance`, `pay.sweeps`, `pay.forwarders`, `pay.quotes.list`, `pay.refunds.list`, and
+  `pay.export_account(directory)`, with the matching `TopupClient` methods.
+- `ApiError.request_id`, read from the response's `Request-Id`.
+- Offline sweeping: `topup_sdk.flush_transaction(factory, treasury, salts, token)`,
+  `flush_transactions(forwarders, token)`, `safe_batch(chain_id, safe, calls)` writing the Safe
+  Transaction Builder's `BatchFile` JSON with the app's checksum, `write_safe_batch`, and
+  `batch_checksum`.
+- `topup_sdk.sign_treasury_challenge(message, private_key, address=)`, the EIP-191 proof of an EOA
+  treasury (extra `phala-pay[eoa]`), and `topup_sdk.quote_address(...)`.
+- `DepositAddress.client_secret` and `.payments`; the generated client reads a deposit address's
+  public `ClientDepositAddress`.
+
+- The generated client covers treasuries (design D10): `topup_client.api.treasuries`
+  (`create_treasury_challenge`, `create_treasury`, `list_treasuries`, `get_treasury`,
+  `cancel_treasury`) and the `Treasury`, `TreasuryChallenge`, and `TreasuryList` models; `Quote`
+  gains the optional `treasury`; `Treasury` carries `cancellation_reason`, and the admin client
+  gains `pause_account` and `resume_account`. Challenge and submit helpers for EOAs and Safes come with the SDK
+  work of design PR 10. The generated `RouteDailyReport` drops the treasury balance fields.
+- `metadata`: `pay.quotes.create(…, metadata=)` and `pay.refunds.create(…, metadata=)`, and
+  `pay.quotes.update(id, metadata=)`, `pay.deposits.update(id, metadata=)`, and
+  `pay.refunds.update(id, metadata=)`, which merge (a key set to `""` is unset, `metadata=""`
+  unsets all); `TopupClient` gains the same `metadata=` and `update_quote`, `update_deposit`, and
+  `update_refund`. The regenerated `Quote`, `Deposit`, and `Refund` carry `metadata`, so a webhook
+  deposit carries its quote's.
+- Deposit addresses, one per customer for every supported token on every chain:
+  `PhalaPay.deposit_addresses.create(client_reference_id=, metadata=)`, `.retrieve(id)`,
+  `.list(client_reference_id=, status=)`, `.update(id, metadata=)`, and `.rotate(id)`, with the
+  matching `TopupClient` methods and the generated `DepositAddress`, `DepositAddressNetwork`, and
+  `DepositAddressAsset` models. With a pinned `forwarder`, every network of an active deposit
+  address must pay the pinned treasury at the recomputed address, or `AddressMismatchError` is
+  raised. `topup_sdk.deposit_address_salt(account, livemode=, client_reference_id=, version=)` and
+  `topup_sdk.deposit_address(factory, implementation, treasury, …)` recompute any version offline
+  from a network's treasury; `Deposits.list` and `TopupClient.list_deposits` take
+  `deposit_address`, and `Deposit.deposit_address` names the address a deposit reached.
+
+- Generated `topup_client.api.webhook_endpoints` (create, list, retrieve, update, delete, test)
+  and `topup_client.api.events` (list, retrieve, resend) with their models
+  (`WebhookEndpointObject`, `EventObjectResponse`, and the request and list types); the
+  hand-written `PhalaPay` helpers for them come with design PR 10.
+- Generated `CreateAccountRequest` and `UpdateAccountRequest` lose `webhook_url`, and
+  `topup_client.api.admin.replay_outbox_event` and `OutboxReplayResponse` are removed: the
+  operator no longer manages merchants' webhooks.
+
+- `TopupClient.roll_webhook_key(expires_in=)` rolls the mode's webhook key (one
+  `Idempotency-Key` across retries). `sign_webhook` accepts several keys, as a rotation signs.
+
+### Changed
+
+- **Breaking**: webhooks are signed with your account's key per mode (design D11).
+  `Webhook.construct_event(payload, headers, public_key, expected_account, *, expected_livemode)`
+  and `verify_webhook(headers, body, public_keys, *, expected_account, expected_livemode)` fail
+  closed unless a signature verifies with a pinned key (one key, or a list while a rotation
+  overlaps) and the event's `account` and `livemode` match; `Event` and `WebhookEvent` carry
+  `account` and `livemode`. Events in the envelope before `evt_` ids are refused.
+  `attestation_report_data(nonce, account, livemode, keys)` computes the new binding and
+  `verify_attestation_binding(response, nonce, *, expected_account=, expected_livemode=)` returns
+  the attested public keys; `AttestationResponse` has `account`, `livemode`, and `webhook_keys`
+  instead of `keyid` and `settlement_pubkey`, and `TopupClient.attestation` sends the API key.
+  `topup-sdk send-test-event` takes `--account` and also checks that another account's event is
+  refused. `Quote`, `Deposit`, `Refund`, `Config`, and `AccountObject` gain `livemode` or
+  `webhook_keys`.
+- **Breaking**: refunds are paid by the merchant from the refund's `treasury` and attached with
+  `TopupClient.mark_refund_paid(refund_id, transaction_hash, log_index=)` (`pay.refunds.mark_paid`);
+  `cancel_refund` (`pay.refunds.cancel`) cancels a pending one. `Refund` gains `treasury`,
+  `failure_reason`, and `log_index`, renames `tx_hash` to `transaction_hash`, and its `status` may
+  also be `failed` or `canceled`. A failed refund is announced by the `refund.failed` webhook,
+  whose `data.object` is the refund. The regenerated admin client drops `approve_refund`,
+  `record_refund`, `AdminRefundResponse`, and `RecordRefundRequest`.
+
+- **Breaking**: the service sends no transactions, so attestation binds no flusher operators.
+  `AttestationResponse` drops `operators` (and `OperatorIdentity` is gone), `report_data` is
+  `sha256(nonce ‖ settlement_pubkey)`, and `attestation_report_data(nonce, settlement_pubkey)`
+  takes no operators. The admin daily report drops `flush_planning` (`FlushPlanningReport`), and
+  its `unflushed_balance_atomic` is what forwarders still hold: deposits not reversed minus
+  finalized `Flushed` amounts, whoever flushed.
+- **Breaking**: merchant requests carry a secret key, `Authorization: Bearer ppay_sk_…`, instead
+  of an RFC 9421 signature (design D7, PR 5). `TopupClient(base_url, api_key, *, account=None,
+  forwarder=None, …)` and `PhalaPay(api_base, api_key, *, account=None, forwarder=None, …)`
+  replace the signer and key file arguments; the address check reads the account id once from
+  `GET /v1/account` unless `account=` is given. `TopupClient.get_account()` and `account_id()`
+  are new. The client retries `409 idempotency_key_in_use` instead of `signature_replayed`.
+  `RequestSigner` stays for the operator's admin requests.
+- The regenerated client adds `/v1/account`, `/v1/api_keys` (create, list, retrieve, roll,
+  revoke), and the admin `create_account` (contact, due diligence, `charges_enabled`, first keys),
+  `update_account` (now `POST`), and `issue_api_key`; customer pauses take `livemode`.
+
+- **Breaking**: products are gone; the service's tenant is an account, `acct_…`. Sign with the key
+  id the operator issued with your account, `{acct_…}/v1`: the client takes the account id from
+  it as the first input of every quote's address salt, as it took the product slug. The
+  regenerated admin client replaces `register_product`, `update_product`, `pause_account`, and
+  `resume_account` with `create_account`, `update_account`, `pause_customer`, and
+  `resume_customer`; the admin deposit view carries `account` and `livemode`.
+
+- **Breaking**: forwarders are clones of the new permissionless factory whose address commits to
+  the treasury. `forwarder_address(factory, implementation, treasury, salt)` takes the treasury,
+  and `forwarder=` is the `(factory, implementation, treasury)` triple.
+
+### Added
+
+- Fast credit: the regenerated client carries the config's `confirmations` and
+  `typical_credit_seconds`, and the admin deposit view's `receipt_log_index` and `final_at`.
+  `Event` documents `deposit.reversed`: claw its credit back as for `deposit.refunded`.
+
+### Changed
+
+- **Breaking**: `topup_sdk.deposit_id(chain_id, tx_hash, receipt_log_index)` hashes the
+  transfer's position in its transaction's receipt (0 for a plain token transfer), the service's
+  deposit identity since fast credit; the argument was the block-wide `log_index`.
+
+- `phala_pay`: the Stripe-style facade. `PhalaPay(api_base, key_id, key_file=… | seed=…,
+  forwarder=…)` with `quotes.create/retrieve/cancel`, `deposits.list` (auto-paginating) and
+  `retrieve`, `refunds.create/retrieve`, and `config.retrieve`; `webhooks.construct_event(payload,
+  headers, public_key)` verifies a delivery and returns a typed `Event` (`data.object` is a
+  `Deposit` or `Quote`), raising `SignatureVerificationError`.
+- `TopupClient.create_refund` (sends an `Idempotency-Key`) and `get_refund`; `topup_sdk.ids`
+  (`object_id`, `parse_id`, and the `qt_`/`dep_`/`re_`/`evt_` prefixes).
+- `TopupClient.get_config`, `create_quote` (sends an `Idempotency-Key`, generated unless given,
+  and reuses it on retries), `get_quote`, and `cancel_quote`; `topup_sdk.signing.sf_string`.
+- `Quote.client_secret`, returned by `create_quote` only, and the generated `ClientQuote` model:
+  the public view the payer's browser reads from `GET /v1/quotes/{id}?client_secret=…`.
+
+- `topup_sdk.fulfillment`: `CreditedDeposit.from_event` parses a verified `deposit.credited`
+  into a typed credit with its `fulfillment_key` (`deposit:<deposit_id>`), raising
+  `FulfillmentError` for any other shape; `credited_event_id` derives the event's
+  `webhook-id` from the deposit id; `CREDITED_EVENT`. The service emits this payload once
+  `deposit.credited` becomes the fulfillment event (docs/integration.md §2).
+- `topup_sdk.sign_webhook` (test senders) and `topup-sdk send-test-event`, which checks a webhook
+  receiver answers a signed event and its duplicate with `2xx` and a forged copy with `4xx`.
+- `DepositResponse.external_id` and `price_source` (also on `SupportDepositResponse`).
+- Generated `topup_client.api.admin.update_product` with `UpdateProductRequest` for
+  `PUT /v1/admin/products/{slug}`.
+- Generated `topup_client.api.admin.lift_reconciliation_block` and `replay_outbox_event` with
+  `AdminReasonRequest`, `ReconciliationBlockLiftResponse`, and `OutboxReplayResponse`.
+- `DailyReportResponse.reconciliation_blocks` (`ReconciliationBlockReport`) and
+  `SupportDepositResponse.events` (`DepositEventResponse`). Optional, so the models also parse
+  responses from servers that predate them.
+- `DailyReportResponse.reconciliation` (`ReconciliationRoundReport`, `FailedCheckReport`) and
+  `RouteDailyReport.flush_planning` (`FlushPlanningReport`): the latest reconciliation round and
+  scheduled flush planning run of the serving process. Optional, so the models also parse
+  reports from servers that predate them.
+- `AttestationResponse.operators` (`OperatorIdentity`): the flusher operator of each configured
+  chain, bound into `report_data`. Optional, so the model also parses responses from servers
+  that predate it.
+- Generated `topup_client.api.admin.register_product` with `RegisterProductRequest` and
+  `ProductResponse` for `POST /v1/admin/products`.
+- `topup_sdk.verify_attestation_binding` and `attestation_report_data`, which check that
+  `report_data` binds the nonce, the settlement key, and every listed operator, and
+  `AttestationError`.
+- `TopupClient.list_pending_deposits` and the generated `list_pending_deposits` operation with
+  `PendingDepositResponse` and `PendingDepositsResponse`: transfers to persistent addresses seen
+  before finality. Display only; they are not credited.
+- `RateLockResponse.payment` (`RateLockPayment`): the payment the checkout page should show (the
+  consuming deposit, else the first qualifying payment, else the first), `seen` before finality
+  or `finalized` once it is a deposit.
+- `DailyReportResponse.exposure_minor`, the global open rate-lock credit in destination minor
+  units (#94). Optional, so the model also parses reports from servers that predate it.
+
+### Changed
+
+- **Breaking**: the distribution is `phala-pay` (was `crypto-topup-sdk`), published to
+  PyPI from `sdk-py-v*` tags. The `topup_sdk` and `topup_client` imports are unchanged.
+- **Breaking**: `verify_webhook` parses Stripe-style events: `WebhookEvent(id, type, created, data)`
+  with `object` (the event's `data.object`), still accepting the old envelope of a replayed old
+  event. `CreditedDeposit` carries the deposit's fields (`deposit_id` `dep_…`, `account_id`,
+  `amount` in cents, `price_source` `quote` or `spot`, `quote`, …) and its `fulfillment_key` is
+  the `dep_` id; `deposit_id` returns `dep_…` and `credited_event_id` `evt_…`.
+  `topup-sdk send-test-event` takes `--account-id` and `--amount` and sends the new envelope.
+- **Breaking**: `TopupClient(base_url, signer, *, forwarder=None, …)`: the product is the signer's
+  key id, `{product}/v1`; there is no `product_slug` argument. With `forwarder=(factory,
+  implementation)` pinned, `create_quote` and `get_quote` recompute an open quote's address and
+  raise the new `AddressMismatchError`.
+- **Breaking**: `ApiError` carries the error object's `error_type` and `param`.
+- `TopupClient.attestation` raises `AttestationError` unless `report_data` binds the returned
+  keys. It does not verify the quote itself.
+- The service now rebuilds `@target-uri` from its configured public origin
+  (`TOPUP_PUBLIC_ORIGIN`) instead of the `Host` and `X-Forwarded-Proto` headers, so requests
+  signed for the public URL verify behind the dstack gateway (#77). The `http_message_signature`
+  security scheme in `openapi.json` documents this. No SDK code changed.
+
+### Removed
+
+- **Breaking**: `create_deposit_address`, `get_deposit_address`, `rotate_deposit_address`,
+  `list_pending_deposits`, and `topup_sdk.persistent_salt`, with their generated operations and
+  models: quotes are the only flow.
+- **Breaking**: `lookup_deposits` and `request_refund`; `list_deposits(external_id, state=…,
+  created_from=…, created_to=…)` becomes `list_deposits(account_id=…, quote=…, status=…,
+  tx_hash=…, created_gte=…, created_lte=…, expand=…)` over Stripe's cursors, and `get_deposit`
+  takes a `dep_` id. Use `create_refund` and `get_refund`.
+- **Breaking**: `register_account`, `create_rate_lock`, `get_rate_lock`, `cancel_rate_lock`, and
+  `get_limits`, with their generated `topup_client` operations and models. Use `create_quote`,
+  `get_quote`, `cancel_quote`, and `get_config`.
+- **Breaking:** the generated `RouteDailyReportSettlementsByStatus` and
+  `RouteDailyReport.settlements_by_status`, replaced by `credited_undelivered` and
+  `credited_undelivered_max_age_seconds`; the settlement-request test vectors, since the service
+  no longer sends settlement requests.
+
+- **Breaking:** the generated `ErrorDetail.work_package` field and the `501` response of
+  `/v1/attestation` (`get_attestation`) (#90). Both belonged only to the pre-C11 placeholder
+  attestor; the production service never returned them. There was no deprecation window because
+  neither was ever reachable in production.
+- **Breaking:** `RouteDailyReport.exposure_minor`, `exposure_minor_reason`, `pnl_minor`, and
+  `pnl_minor_reason` (#94). They were always null placeholders on the admin-only daily report;
+  PnL is not defined precisely enough in the design to compute. Allowed as a pre-GA exception:
+  no service has been deployed. Regenerated models only.
+
+## [0.1.0] - 2026-09-22
+
+Not published.
+
+Generated from OpenAPI `info.version` 0.1.0.
+
+### Added
+
+- Generated `topup_client` package for the product and administrative API.
+- RFC 9421 ed25519 request signing (`RequestSigner`, `SigningAuth`) with a random `nonce` per
+  signature, and inbound verification (`verify_request`) in the service's profile.
+- Standard Webhooks `v1a` verification (`verify_webhook`, `verify_webhook_signature`).
+- Deposit-id, salt, and CREATE2 forwarder-address recomputation.
+- `TopupClient` with idempotent, retrying helpers for accounts, deposit addresses, rotation,
+  rate locks, deposits, limits, refunds, and attestation.
+- `topup-sdk keygen` and `topup-sdk public-key` for credential issuance.
+
+[unreleased]: https://github.com/Phala-Network/phala-pay/compare/sdk-py-v0.2.0...HEAD
+[0.2.0]: https://github.com/Phala-Network/phala-pay/releases/tag/sdk-py-v0.2.0

phala_pay-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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.

phala_pay-0.2.0/Makefile

@@ -0,0 +1,38 @@
+# Python SDK tasks. Every target runs the tools pinned in uv.lock.
+UV ?= uv
+OPENAPI := ../../crates/topup/openapi.json
+GENERATED := src/topup_client
+
+.PHONY: sync generate check-generated lint test test-min-python check
+
+sync:
+	$(UV) sync --locked --all-groups
+
+generate:
+	$(UV) run --locked --group codegen openapi-python-client generate \
+		--path $(OPENAPI) \
+		--config openapi-python-client.yaml \
+		--meta none \
+		--output-path $(GENERATED) \
+		--overwrite \
+		--fail-on-warning
+
+# Regeneration must be a no-op: the committed client always matches the committed OpenAPI spec.
+check-generated: generate
+	git diff --exit-code -- $(GENERATED)
+	test -z "$$(git status --porcelain --untracked-files=all -- $(GENERATED))"
+
+lint:
+	$(UV) run --locked ruff check . ../examples ../../deploy/product ../../deploy/sandbox/scenarios ../../deploy/sandbox/smoke.py
+	$(UV) run --locked ruff format --check . ../examples ../../deploy/product ../../deploy/sandbox/scenarios ../../deploy/sandbox/smoke.py
+	$(UV) run --locked mypy src/phala_pay src/topup_sdk tests ../examples ../../deploy/product ../../deploy/sandbox/scenarios ../../deploy/sandbox/smoke.py
+
+test:
+	$(UV) run --locked pytest
+
+# The development interpreter is the newest (.python-version); this exercises the
+# requires-python floor in a throwaway environment so the project .venv is left alone.
+test-min-python:
+	$(UV) run --locked --isolated --python 3.12 pytest -q
+
+check: lint test test-min-python check-generated