1	<?php
2	/**
3	* The functions expected by the core plugin when using a Bitcoin_Address.
4	*
5	* @package    brianhenryie/bh-wp-bitcoin-gateway
6	*/
7
8	namespace BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Wallet;
9
10	use BrianHenryIE\WP_Bitcoin_Gateway\Brick\Money\Money;
11	use BrianHenryIE\WP_Bitcoin_Gateway\Admin\Addresses_List_Table;
12	use BrianHenryIE\WP_Bitcoin_Gateway\Integrations\WooCommerce\Bitcoin_Gateway;
13
14	interface Bitcoin_Address_Interface {
15
16	/**
17	* Get the WordPress post ID for this saved Bitcoin payment address.
18	*
19	* @return int The post ID.
20	*/
21	public function get_post_id(): int;
22
23	/**
24	* The post ID for the xpub|ypub|zpub wallet this address was derived for.
25	*
26	* @return int
27	*/
28	public function get_wallet_parent_post_id(): int;
29
30	/**
31	* Get this Bitcoin address's derivation path.
32	*
33	* @readonly
34	*/
35	public function get_derivation_path_sequence_number(): ?int;
36
37	/**
38	* Return the raw Bitcoin address this object represents.
39	*
40	* @used-by API::check_new_addresses_for_transactions() When verifying newly generated addresses have no existing transactions.
41	* @used-by API::get_fresh_address_for_order() When adding the payment address to the order meta.
42	* @used-by Bitcoin_Gateway::process_payment() When adding a link in the order notes to view transactions on a 3rd party website.
43	* @used-by API::update_address_transactions() When checking has an order been paid.
44	*/
45	public function get_raw_address(): string;
46
47	/**
48	* Return the summed amount received that is saved in the post meta, or null if the address status is unknown.
49	*
50	* TODO: Might need a $confirmations parameter and calculate the total received from the transactions.
51	*
52	* @used-by Addresses_List_Table::print_columns()
53	*
54	* @return ?Money Null if unknown.
55	*/
56	public function get_amount_received(): ?Money;
57
58	/**
59	* Return the current status of the Bitcoin address object/post.
60	*/
61	public function get_status(): Bitcoin_Address_Status;
62
63	/**
64	* Get the order id associated with this address, or null if none has ever been assigned.
65	*/
66	public function get_order_id(): ?int;
67
68
69	/**
70	* The received amount needed to consider the order "paid".
71	*/
72	public function get_target_amount(): ?Money;
73
74	/**
75	* @return ?array<int, string> <post_id, tx_id>
76	*/
77	public function get_tx_ids(): ?array;
78	}