184 lines
6.5 KiB
ReStructuredText
184 lines
6.5 KiB
ReStructuredText
Addresses and payment IDs
|
|
=========================
|
|
|
|
The first, original address of the wallet is usually known as the *master
|
|
address*. All others are just *subaddresses*, even if they represent a separate
|
|
account within the wallet.
|
|
|
|
Monero addresses are base58-encoded strings. You may disassemble each of them
|
|
using the excellent `address analysis tool`_ from *luigi1111*.
|
|
|
|
While the ordinary string representation is perfectly valid to use, you may
|
|
want to use validation and other features provided by the ``monero.address``
|
|
package.
|
|
|
|
.. _`address analysis tool`: https://xmr.llcoins.net/addresstests.html
|
|
|
|
Address validation and instatination
|
|
------------------------------------
|
|
|
|
The function ``monero.address.address()`` will recognize and validate Monero
|
|
address, returning an instance that provides additional functionality.
|
|
|
|
The following example uses addresses from the wallet :doc:`we have generated in
|
|
the previous chapter <wallet>`.
|
|
|
|
Let's start with the master address:
|
|
|
|
.. code-block:: python
|
|
|
|
In [1]: from monero.address import address
|
|
|
|
In [2]: a = address('A2GmyHHJ9jtUhPiwoAbR2tXU9LJu2U6fJjcsv3rxgkVRWU6tEYcn6C1NBc7wqCv5V7NW3zeYuzKf6RGGgZTFTpVC4QxAiAX')
|
|
|
|
In [3]: a.net
|
|
Out[3]: 'test'
|
|
|
|
In [4]: a.spend_key()
|
|
Out[4]: 'f0481b63cb937fa5960529247ebf6db627ff1b0bb88de9feccc3c504c16aa4b0'
|
|
|
|
In [5]: a.view_key()
|
|
Out[5]: '2c5ba76d22e48a7ea4ddabea3cce66808ba0cc91265371910f893962e977af1e'
|
|
|
|
In [6]: type(a)
|
|
Out[6]: monero.address.Address
|
|
|
|
We may use a subaddress too:
|
|
|
|
.. code-block:: python
|
|
|
|
In [7]: b = address('BenuGf8eyVhjZwdcxEJY1MHrUfqHjPvE3d7Pi4XY5vQz53VnVpB38bCBsf8AS5rJuZhuYrqdG9URc2eFoCNPwLXtLENT4R7')
|
|
|
|
In [8]: b.net
|
|
Out[8]: 'test'
|
|
|
|
In [9]: b.spend_key()
|
|
Out[9]: 'ae7e136f46f618fe7f4a6b323ed60864c20070bf110978d7e3868686d5677318'
|
|
|
|
In [10]: b.view_key()
|
|
Out[10]: '2bf801cdaf3a8b41020098a6d5e194f48fa62129fe9d8f09d19fee9260665baa'
|
|
|
|
In [11]: type(b)
|
|
Out[11]: monero.address.SubAddress
|
|
|
|
These two classes, ``Address`` and ``SubAddress`` have similar functionality
|
|
but one significant difference. Only the former may form *integrated address*.
|
|
|
|
Generating subaddresses
|
|
-----------------------
|
|
|
|
It is possible to get subaddresses in two ways:
|
|
|
|
1. Creating them in the wallet file by calling ``.new_address()`` on ``Account`` or ``Wallet``
|
|
instance. In properly synced wallet this will return an address that is guaranteed to be fresh
|
|
and unused. It is the right way if you plan to use one-time addresses to identify payments or
|
|
to improve your privacy by avoiding address reuse.
|
|
2. Requesting arbitrary subaddress by calling ``Wallet.get_address(major, minor)`` where ``major``
|
|
is the account index and ``minor`` is the index of the address within an account. Addresses
|
|
obtained this way are not guaranteed to be fresh and **will not be saved as already generated
|
|
within the wallet file**. (Watch out for unintentional address reuse!)
|
|
|
|
Payment IDs and integrated addresses
|
|
------------------------------------
|
|
|
|
Each Monero transaction may carry a **payment ID**. It is a 64 or 256-bit long
|
|
number that carries additional information between parties. For example, a
|
|
merchant can generate a payment ID for each order, or an exchange can assign
|
|
one to each user. The customer/user would then attach the ID to the transaction,
|
|
so the site operator would know what is the purpose of incoming payment.
|
|
|
|
A short, 64-bit payment ID can be integrated into an address, creating, well...
|
|
an **integrated address**.
|
|
|
|
.. code-block:: python
|
|
|
|
In [12]: ia = a.with_payment_id(0xfeedbadbeef)
|
|
|
|
In [13]: ia
|
|
Out[13]: ABySz66nm1QUhPiwoAbR2tXU9LJu2U6fJjcsv3rxgkVRWU6tEYcn6C1NBc7wqCv5V7NW3zeYuzKf6RGGgZTFTpVC623BT1ptXvVU2GjR1B
|
|
|
|
In [14]: ia.base_address()
|
|
Out[14]: A2GmyHHJ9jtUhPiwoAbR2tXU9LJu2U6fJjcsv3rxgkVRWU6tEYcn6C1NBc7wqCv5V7NW3zeYuzKf6RGGgZTFTpVC4QxAiAX
|
|
|
|
In [15]: ia.base_address() == a
|
|
Out[15]: True
|
|
|
|
In [16]: ia.payment_id()
|
|
Out[16]: 00000feedbadbeef
|
|
|
|
|
|
Since subaddresses have been introduced, merchants may generate a separate
|
|
address for each order, user or any other object they expect the payments
|
|
coming to. Therefore, it has been decided that `subaddresses cannot generate
|
|
integrated addresses`_.
|
|
|
|
.. _`subaddresses cannot generate integrated addresses`: https://monero.stackexchange.com/questions/6606/how-to-make-an-integrated-address-based-on-a-subaddress
|
|
|
|
.. code-block:: python
|
|
|
|
In [17]: b.with_payment_id(0xfeedbadbeef)
|
|
---------------------------------------------------------------------------
|
|
TypeError Traceback (most recent call last)
|
|
<ipython-input-23-5a5811a6962a> in <module>()
|
|
----> 1 b.with_payment_id(0xfeedbadbeef)
|
|
|
|
~/devel/monero-python/monero/address.py in with_payment_id(self, _)
|
|
99
|
|
100 def with_payment_id(self, _):
|
|
--> 101 raise TypeError("SubAddress cannot be integrated with payment ID")
|
|
102
|
|
103
|
|
|
|
TypeError: SubAddress cannot be integrated with payment ID
|
|
|
|
The ``monero.numbers.PaymentID`` class validates payment IDs. It accepts both
|
|
integer and hexadecimal string representations.
|
|
|
|
.. code-block:: python
|
|
|
|
In [18]: from monero.numbers import PaymentID
|
|
|
|
In [19]: p1 = PaymentID(0xfeedbadbeef)
|
|
|
|
In [20]: p2 = PaymentID('feedbadbeef')
|
|
|
|
In [21]: p1 == p2
|
|
Out[21]: True
|
|
|
|
In [22]: p1.is_short()
|
|
Out[22]: True
|
|
|
|
In [23]: p3 = PaymentID('1234567890abcdef0')
|
|
|
|
In [24]: p3
|
|
Out[24]: 000000000000000000000000000000000000000000000001234567890abcdef0
|
|
|
|
In [25]: p3.is_short()
|
|
Out[25]: False
|
|
|
|
Long payment IDs cannot be integrated:
|
|
|
|
.. code-block:: python
|
|
|
|
In [26]: a.with_payment_id(p3)
|
|
---------------------------------------------------------------------------
|
|
TypeError Traceback (most recent call last)
|
|
<ipython-input-8-7098746f0b69> in <module>
|
|
----> 1 a.with_payment_id(p3)
|
|
|
|
~/devel/monero-python/monero/address.py in with_payment_id(self, payment_id)
|
|
138 payment_id = numbers.PaymentID(payment_id)
|
|
139 if not payment_id.is_short():
|
|
--> 140 raise TypeError("Payment ID {0} has more than 64 bits and cannot be integrated".format(payment_id))
|
|
141 prefix = const.INTADDRR_NETBYTES[const.NETS.index(self.net)]
|
|
142 data = bytearray([prefix]) + self._decoded[1:65] + struct.pack('>Q', int(payment_id))
|
|
|
|
TypeError: Payment ID 000000000000000000000000000000000000000000000001234567890abcdef0 has more than 64 bits and cannot be integrated
|
|
|
|
|
|
API reference
|
|
-------------
|
|
|
|
.. automodule:: monero.address
|
|
:members:
|