1	<?php
2	/**
3	* The core plugin settings that may preferably be set by supplying another instance conforming to this interface.
4	*
5	* @package    brianhenryie/bh-wp-bitcoin-gateway
6	*/
7
8	namespace BrianHenryIE\WP_Bitcoin_Gateway;
9
10	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Payments\Bitcoin_Transaction;
11	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Results\Addresses_Generation_Result;
12	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Results\Check_Address_For_Payment_Result;
13	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Results\Check_Assigned_Addresses_For_Transactions_Result;
14	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Results\Ensure_Unused_Addresses_Result;
15	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Payments\Transaction_Interface;
16	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Results\Wallet_Generation_Result;
17	use BrianHenryIE\WP_Bitcoin_Gateway\Brick\Money\Currency;
18	use BrianHenryIE\WP_Bitcoin_Gateway\Brick\Money\Money;
19	use BrianHenryIE\WP_Bitcoin_Gateway\Action_Scheduler\Background_Jobs_Actions_Handler;
20	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Wallet\Bitcoin_Address;
21	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Wallet\Bitcoin_Wallet;
22	use BrianHenryIE\WP_Bitcoin_Gateway\Integrations\WooCommerce\Bitcoin_Gateway;
23
24	/**
25	* Methods in API class that are used by other classes, primarily Bitcoin_Gateway, Background_Jobs and CLI.
26	*/
27	interface API_Interface {
28
29	/**
30	* Find what the value of 1 BTC is in the specified currency.
31	*
32	* @used-by Bitcoin_Gateway::process_payment()
33	*
34	* @param Currency $currency E.g. USD|EUR|GBP.
35	*
36	* @return ?Money `null` when unavailable, e.g. offline and requests fail.
37	*/
38	public function get_exchange_rate( Currency $currency ): ?Money;
39
40	/**
41	* Get the Bitcoin value of a local currency amount.
42	*
43	* @used-by Bitcoin_Gateway::process_payment()
44	*
45	* @param Money $fiat_amount The amount to convert.
46	*/
47	public function convert_fiat_to_btc( Money $fiat_amount ): Money;
48
49	/**
50	* When a new wallet address is saved in the gateway settings, generate a Wallet custom post for it, and prepare
51	* fresh addresses for use.
52	*
53	* @used-by Bitcoin_Gateway::process_admin_options()
54	*
55	* @param string                                              $xpub The wallet address to save as a wallet object cpt.
56	* @param ?array{integration:class-string, gateway_id:string} $gateway_details The Bitcoin gateway (it is presumably linked to one).
57	*/
58	public function get_or_save_wallet_for_master_public_key( string $xpub, ?array $gateway_details = null ): Wallet_Generation_Result;
59
60	/**
61	* For each Bitcoin gateway, calls `generate_new_addresses_for_wallet()`.
62	*
63	* @return Addresses_Generation_Result[]
64	*/
65	public function generate_new_addresses(): array;
66
67	/**
68	* Local-db-only check to see is there an unused address that has been recently checked to ensure it is available.
69	* Schedules an immediate background job if none are available.
70	*
71	* @param Bitcoin_Wallet $wallet The wallet we want a payment address for.
72	*/
73	public function is_unused_address_available_for_wallet( Bitcoin_Wallet $wallet ): bool;
74
75	/**
76	* Generate fresh addresses for a wallet.
77	*
78	* Gets the wallet object (CPT), get the last address index generated, derives the following 25 addresses for
79	* that wallet, checks the new addresses for transactions, queues a new background job to generate more if
80	* total is still below threshold.
81	*
82	* @param Bitcoin_Wallet $wallet The wallet to generate addresses for.
83	* @param int            $generate_count The number of sub-addresses to derive.
84	*/
85	public function generate_new_addresses_for_wallet( Bitcoin_Wallet $wallet, int $generate_count = 20 ): Addresses_Generation_Result;
86
87	/**
88	* Like {@see self::generate_new_addresses_for_wallet()} but stops when the number specified is reached, distinct
89	* from always adding that many more.
90	*
91	* @param int $required_count Ensure there are this many unused addresses for the wallet; default to one.
92	*
93	* @return array<string, Ensure_Unused_Addresses_Result>
94	*/
95	public function ensure_unused_addresses( int $required_count = 2 ): array;
96
97	/**
98	* Ensure a specific wallet has the requested number of unused addresses.
99	*
100	* @param Bitcoin_Wallet $wallet The wallet to ensure there are unused addresses for.
101	* @param int            $required_count Number of unused addresses required.
102	*/
103	public function ensure_unused_addresses_for_wallet_synchronously( Bitcoin_Wallet $wallet, int $required_count = 2 ): Ensure_Unused_Addresses_Result;
104
105	/**
106	* Validate addresses have not been used before by checking for transactions.
107	*
108	* @used-by Background_Jobs_Actions_Handler::check_new_addresses_for_transactions()
109	* @used-by API::generate_new_addresses()
110	* @used-by API::generate_new_addresses_for_wallet()
111	* @used-by API::generate_new_wallet()
112	* @used-by CLI::generate_new_addresses()
113	*/
114	public function check_new_addresses_for_transactions(): Check_Assigned_Addresses_For_Transactions_Result;
115
116	/**
117	* The main function for checking for payments received.
118	*/
119	public function check_assigned_addresses_for_payment(): Check_Assigned_Addresses_For_Transactions_Result;
120
121	/**
122	* Query the blockchain for transactions for an address and mark it paid when appropriate.
123	*
124	* @used-by CLI::check_transactions()
125	*
126	* @param Bitcoin_Address $payment_address Previously assigned address.
127	*/
128	public function check_address_for_payment( Bitcoin_Address $payment_address ): Check_Address_For_Payment_Result;
129
130	/**
131	* Return transactions for a Bitcoin address without any remote API calls.
132	*
133	* @param Bitcoin_Address $bitcoin_address The payment address to get transactions for.
134	*
135	* @return ?array<Bitcoin_Transaction&Transaction_Interface>
136	*/
137	public function get_saved_transactions( Bitcoin_Address $bitcoin_address ): ?array;
138	}