feat: add Orchestra USDT deposit addresses and recovery

bindings/ios/bitkitcoreFFI.h

@@ -660,6 +660,46 @@ RustBuffer uniffi_bitkitcore_fn_method_urdecoder_receive(void*_Nonnull ptr, Rust
 void uniffi_bitkitcore_fn_method_urdecoder_reset(void*_Nonnull ptr, RustCallStatus *_Nonnull out_status
 );
 #endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_CLONE_USDTDEPOSITCLIENT
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_CLONE_USDTDEPOSITCLIENT
+void*_Nonnull uniffi_bitkitcore_fn_clone_usdtdepositclient(void*_Nonnull ptr, RustCallStatus *_Nonnull out_status
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_FREE_USDTDEPOSITCLIENT
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_FREE_USDTDEPOSITCLIENT
+void uniffi_bitkitcore_fn_free_usdtdepositclient(void*_Nonnull ptr, RustCallStatus *_Nonnull out_status
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_CONSTRUCTOR_USDTDEPOSITCLIENT_NEW
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_CONSTRUCTOR_USDTDEPOSITCLIENT_NEW
+void*_Nonnull uniffi_bitkitcore_fn_constructor_usdtdepositclient_new(RustBuffer address, RustBuffer service_url, RustCallStatus *_Nonnull out_status
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_METHOD_USDTDEPOSITCLIENT_DETAIL
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_METHOD_USDTDEPOSITCLIENT_DETAIL
+uint64_t uniffi_bitkitcore_fn_method_usdtdepositclient_detail(void*_Nonnull ptr, RustBuffer deposit_id, uint32_t offset, RustBuffer mnemonic, RustBuffer passphrase
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_METHOD_USDTDEPOSITCLIENT_HISTORY
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_METHOD_USDTDEPOSITCLIENT_HISTORY
+uint64_t uniffi_bitkitcore_fn_method_usdtdepositclient_history(void*_Nonnull ptr, uint32_t offset, RustBuffer mnemonic, RustBuffer passphrase
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_METHOD_USDTDEPOSITCLIENT_NETWORKS
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_METHOD_USDTDEPOSITCLIENT_NETWORKS
+uint64_t uniffi_bitkitcore_fn_method_usdtdepositclient_networks(void*_Nonnull ptr
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_METHOD_USDTDEPOSITCLIENT_RECEIVE
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_METHOD_USDTDEPOSITCLIENT_RECEIVE
+uint64_t uniffi_bitkitcore_fn_method_usdtdepositclient_receive(void*_Nonnull ptr, RustBuffer network, uint64_t amount, RustBuffer mnemonic, RustBuffer passphrase
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_METHOD_USDTDEPOSITCLIENT_REQUEST_REFUND
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_METHOD_USDTDEPOSITCLIENT_REQUEST_REFUND
+uint64_t uniffi_bitkitcore_fn_method_usdtdepositclient_request_refund(void*_Nonnull ptr, RustBuffer deposit_id, uint32_t offset, RustBuffer refund_address, RustBuffer network, RustBuffer mnemonic, RustBuffer passphrase
+);
+#endif
 #ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_CLONE_USDTWALLET
 #define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_FN_CLONE_USDTWALLET
 void*_Nonnull uniffi_bitkitcore_fn_clone_usdtwallet(void*_Nonnull ptr, RustCallStatus *_Nonnull out_status
@@ -3466,6 +3506,36 @@ uint16_t uniffi_bitkitcore_checksum_method_urdecoder_receive(void
 #define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_METHOD_URDECODER_RESET
 uint16_t uniffi_bitkitcore_checksum_method_urdecoder_reset(void
 
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_METHOD_USDTDEPOSITCLIENT_DETAIL
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_METHOD_USDTDEPOSITCLIENT_DETAIL
+uint16_t uniffi_bitkitcore_checksum_method_usdtdepositclient_detail(void
+
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_METHOD_USDTDEPOSITCLIENT_HISTORY
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_METHOD_USDTDEPOSITCLIENT_HISTORY
+uint16_t uniffi_bitkitcore_checksum_method_usdtdepositclient_history(void
+
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_METHOD_USDTDEPOSITCLIENT_NETWORKS
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_METHOD_USDTDEPOSITCLIENT_NETWORKS
+uint16_t uniffi_bitkitcore_checksum_method_usdtdepositclient_networks(void
+
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_METHOD_USDTDEPOSITCLIENT_RECEIVE
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_METHOD_USDTDEPOSITCLIENT_RECEIVE
+uint16_t uniffi_bitkitcore_checksum_method_usdtdepositclient_receive(void
+
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_METHOD_USDTDEPOSITCLIENT_REQUEST_REFUND
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_METHOD_USDTDEPOSITCLIENT_REQUEST_REFUND
+uint16_t uniffi_bitkitcore_checksum_method_usdtdepositclient_request_refund(void
+
 );
 #endif
 #ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_METHOD_USDTWALLET_BALANCE
@@ -3526,6 +3596,12 @@ uint16_t uniffi_bitkitcore_checksum_method_usdtwallet_sync_history(void
 #define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_CONSTRUCTOR_URDECODER_NEW
 uint16_t uniffi_bitkitcore_checksum_constructor_urdecoder_new(void
 
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_CONSTRUCTOR_USDTDEPOSITCLIENT_NEW
+#define UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_CONSTRUCTOR_USDTDEPOSITCLIENT_NEW
+uint16_t uniffi_bitkitcore_checksum_constructor_usdtdepositclient_new(void
+
 );
 #endif
 #ifndef UNIFFI_FFIDEF_UNIFFI_BITKITCORE_CHECKSUM_CONSTRUCTOR_USDTWALLET_NEW

src/lib.rs

@@ -91,9 +91,10 @@ pub use modules::onchain;
 pub use modules::scanner::{DecodingError, LnurlPayData, Scanner};
 pub use modules::seedqr::{decode_compact_seed_qr, decode_standard_seed_qr, SeedQrError};
 pub use modules::usdt::{
-    usdt_address, usdt_format_amount, usdt_parse_amount, usdt_parse_payment_request,
-    UsdtDestination, UsdtError, UsdtPaymentRequest, UsdtQuote, UsdtTransfer, UsdtTransferStatus,
-    UsdtWallet,
+    usdt_address, usdt_format_amount, usdt_parse_amount, usdt_parse_payment_request, UsdtDeposit,
+    UsdtDepositAddress, UsdtDepositClient, UsdtDepositDetail, UsdtDepositNetwork, UsdtDepositOrder,
+    UsdtDepositPage, UsdtDestination, UsdtError, UsdtPaymentRequest, UsdtQuote, UsdtTransfer,
+    UsdtTransferStatus, UsdtWallet,
 };
 
 use bip39::Mnemonic;

src/modules/usdt/README.md

@@ -85,3 +85,19 @@ Build iOS and Android sequentially with the repository scripts; Android temporar
 - [LayerZero message statuses](https://docs.layerzero.network/v2/tools/layerzeroscan/mainnet/messages/get-messagesstatus)
 
 Destination token addresses follow the official USDT0 ecosystem listings for [Polygon](https://usdt0.to/ecosystem/polygon), [Plasma](https://usdt0.to/ecosystem/plasma) and [Stable](https://usdt0.to/ecosystem/stable).
+
+## Incoming deposits
+
+`UsdtDepositClient` authenticates reusable deposit-address registration, indicative quotes, history, detail and refund requests with the wallet account. Its credential-free service URL is separate from the chain and bundler URLs. The companion service holds the Orchestra server key and fixes the destination to this wallet's Arbitrum One USDT0 account.
+
+Supported source networks are Ethereum, Tron, Solana, Polygon, Base and BNB Smart Chain (`bsc`). Arbitrum receives directly through the wallet. The service advertises only explicitly enabled, currently supported routes. The sender transfers USDT to the returned address and pays the source-network fee. Orchestra prices each deposit when processing it; receiving estimates are not guarantees or spendable balance. The wallet credits funds only through its Arbitrum history.
+
+Orchestra's general swap catalog is broader than its standing-address coverage. Optimism, TON, Plasma and HyperEVM are not offered because the approved account does not currently return standing addresses for them. Do not reuse an EVM deposit address on an unlisted network. Additional source networks require provider address support and funded acceptance.
+
+All client amounts use millionths of USDT. The service scales BSC USDT's 18-decimal source units when quoting and normalizes observed BSC deposit/batch amounts to six decimals, rounding only sub-millionth source dust down. Arbitrum output amounts are exact. EVM receive QR payloads pin the token contract and chain; Tron and Solana use the validated address.
+
+History returns at most 50 rows per page. Start with `offset = 0`, then use `next_offset` until it is absent. Retain each row's page offset for detail and refund requests; if new arrivals move it out of the inspected pages, refresh history. Deduplicate deposits by ID. Linked order amounts can include multiple deposits batched together and must be labelled as batch totals.
+
+Refunds require a user-approved address on the source network and provider eligibility; an acknowledgment means queued, not paid. Never infer a refund address from the original sender, which may be an exchange hot wallet. Unconverted Tron refunds require provider assistance. Missing optional metadata must not hide pending deposits. Address recovery depends on the same Orchestra partner account and immutable account-derived reference; provider availability and address control remain trust dependencies.
+
+Use a matching [bitkit-usdt-service](https://github.com/synonymdev/bitkit-usdt-service) deployment with `ORCHESTRA_API_KEY` and `ORCHESTRA_DEPOSIT_NETWORKS`. Enable each source only after funded delivery and provider recovery acceptance. See [Orchestra deposit addresses](https://docs.flashnet.xyz/orchestra/deposit-addresses).