diff --git a/docs/commands.rst b/docs/commands.rst
index a860a44..a3a5771 100644
--- a/docs/commands.rst
+++ b/docs/commands.rst
@@ -10,15 +10,15 @@ Advanced: PyOTA Commands
However, if you are a curious mind or happen to do development on the
library, the following information might be useful.
-PyOTA provides the API interface (:ref:`Core API Methods` and
-:ref:`Extended API Methods`) for users of the library. These handle
+PyOTA provides the API interface (:ref:`core_api:Core API Methods` and
+:ref:`extended_api:Extended API Methods`) for users of the library. These handle
constructing and sending HTTP requests to the specified node through adapters,
furthermore creating, transforming and translating between PyOTA-specific types
and (JSON-encoded) raw data. They also filter outgoing requests and incoming
responses to ensure that only appropriate data is communicated with the node.
PyOTA implements the `Command Design Pattern`_. High level API interface
-methods (:ref:`Core API Methods` and :ref:`Extended API Methods`)
+methods (:ref:`core_api:Core API Methods` and :ref:`extended_api:Extended API Methods`)
internally call PyOTA commands to get the job done.
Most PyOTA commands are sub-classed from :py:class:`FilterCommand` class, which
@@ -142,7 +142,7 @@ Extended Commands
Core commands, like :py:meth:`~Iota.find_transactions` in the example above,
are for direct communication with the node for simple tasks such
as finding a transaction on the Tangle or getting info about the node.
-Extended commands (that serve :ref:`Extended API Methods`) on the other hand
+Extended commands (that serve :ref:`extended_api:Extended API Methods`) on the other hand
carry out more complex operations such as combining core commands, building
objects, etc...
diff --git a/docs/conf.py b/docs/conf.py
index 75e7ef2..be5b331 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -36,6 +36,9 @@
'sphinx.ext.autosectionlabel',
]
+# Add a document prefix to the created section lables
+autosectionlabel_prefix_document = True
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
diff --git a/docs/images/create_transfer.svg b/docs/images/create_transfer.svg
new file mode 100644
index 0000000..f88ba79
--- /dev/null
+++ b/docs/images/create_transfer.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/docs/images/transfer_api.svg b/docs/images/transfer_api.svg
new file mode 100644
index 0000000..9b2d2f7
--- /dev/null
+++ b/docs/images/transfer_api.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 2a6a0da..bf8652e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,6 +10,7 @@
core_api
extended_api
addresses
+ transfers
multisig
commands
tutorials
diff --git a/docs/transfers.rst b/docs/transfers.rst
new file mode 100644
index 0000000..26d6361
--- /dev/null
+++ b/docs/transfers.rst
@@ -0,0 +1,322 @@
+Creating transfers
+==================
+
+IOTA is a permissionless DLT solution, therefore anyone can send transactions
+to the network and initiate transfers. The IOTA client libraries help you to
+abstract away low-level operations required to construct and send a transfer
+to the Tangle.
+
+In this section, we will explore in depth how to create transactions and
+bundles with IOTA, furthermore what tools you can use in PyOTA to ease your
+development process.
+
+.. note::
+
+ Before proceeding, make sure you read and understood the
+ :ref:`basic_concepts:Basic Concepts` and :ref:`types:PyOTA Types` sections!
+
+Anatomy of a Transfer
+---------------------
+
+We already know that the Tangle consists of :ref:`transactions `
+referencing each other, each of them two others to be more precise.
+Transactions can be grouped together in :ref:`bundles `.
+`Zero-value bundles`_ contain only zero value transactions, while
+`transfer bundles`_ may also contain input and output transactions.
+
+But how to construct these bundles and send them to the network?
+
+The process can be boiled down to 5 steps:
+
+ 1. Create individual transaction(s).
+ 2. Construct a bundle from the transaction(s).
+ 3. Obtain references to two unconfirmed transactions ("tips") from the Tangle.
+ 4. Do proof-of-work for each transaction in the bundle.
+ 5. Send the bundle to the network.
+
+
+.. figure:: images/create_transfer.svg
+ :scale: 100 %
+ :alt: Process of sending a transfer in IOTA.
+
+ Process of creating and sending a transfer to the Tangle.
+
+.. py:currentmodule:: iota
+
+1. Create Transactions
+~~~~~~~~~~~~~~~~~~~~~~
+The first step is to create the individual transaction objects. You have to
+specify ``address`` and ``value`` for each transaction. Furthermore, you can
+define a ``tag``, and for zero-value transactions, a ``message``. A
+``timestamp`` is also required, though this value is usually auto-generated
+by the IOTA libraries.
+
+.. note::
+ Unlike on other decentralised ledgers, IOTA transactions can have positive
+ *or* negative ``value`` amounts. In order to send iotas from one address to
+ another, at least two transactions are required:
+
+ * one with *positive* ``value`` (to increment the balance of the receiver), and
+ * one with *negative* ``value`` (to decrement the balance of the sender).
+
+In PyOTA, use :py:class:`ProposedTransaction` to declare transactions.
+
+2. Create Bundle from Transactions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A bundle is a collection of transactions, treated as an atomic unit
+when sent to the network. A bundle makes a value (iota token) transfer possible by
+grouping together input and output transactions.
+
+A bundle always has to be balanced: the sum of ``value`` attributes of the
+transactions in the bundle should always be zero. Transactions in the bundle
+are also indexed individually and contain information on how many other
+transactions there are in the bundle.
+
+Once complete, a bundle has to be finalized to generate the bundle hash based
+on the `bundle essence`_. The bundle hash is the unique identifier of the
+bundle.
+
+After finalization, input transactions in the bundle need to be signed to prove
+ownership of iotas being transferred.
+
+.. tip::
+ :py:class:`ProposedBundle` helps you in PyOTA to create bundles, add transactions,
+ finalize the bundle and sign the inputs. We'll see how to use
+ :py:class:`ProposedBundle` in :ref:`transfers:Use the Library` below.
+
+3. Select two tips
+~~~~~~~~~~~~~~~~~~
+
+Tips are transactions that are yet to be confirmed by the network. We can
+obtain two tips by requesting them from a node. In PyOTA, :py:meth:`~Iota.get_transactions_to_approve`
+does the job: it returns a ``trunk`` and a ``branch`` :py:class:`TransactionHash`.
+
+Because our bundle references these two transactions, it will validate them once
+it is added to the Tangle.
+
+4. Do Proof-of-Work
+~~~~~~~~~~~~~~~~~~~
+
+The bundle has been finalized, inputs have been signed, and we have two tips;
+now it's time to prepare the bundle to be attached to the Tangle. As noted in
+the previous section, every transaction references two other transactions in
+the Tangle; therefore we need to select these references for each transaction
+in our bundle.
+
+We also know that transactions `within the bundle are linked together`_ through
+their trunk references. So how do we construct the correct bundle structure
+and also reference two tips from the network?
+
+.. figure:: images/bundle-structure.png
+ :scale: 100 %
+ :alt: Bundle structure with four transactions.
+
+ Structure of a bundle with four transactions. Numbers in brackets denote
+ (``currentIndex``, ``lastIndex``) fields. Head of the bundle has index 3,
+ while tail has index 0.
+
+For all non-head transactions in the bundle, the trunk reference is the next
+transaction in the bundle, while the branch reference is the trunk transaction
+hash, one of the tips.
+
+The head transaction is different: the trunk reference is the trunk tip, while
+the branch reference is the branch tip.
+
+The proof-of-work calculation has to be done for each transaction individually,
+therefore the more transactions you have in the bundle, the more time it will
+take. The difficulty of the calculation also depends on the `minimum weight magnitude`_
+set by the network.
+
+The output of the proof-of-work algorithm is a ``nonce`` value that is appended
+to the the transaction, resulting in the attached transaction trytes.
+Nodes validate the proof-of-work of a transaction by calculating the transaction's
+hash from the attached transaction trytes. If the resulting hash has at least
+``minimum weight magnitude`` number of trailing zero trits, the transaction is valid.
+
+In PyOTA, use :py:meth:`~Iota.attach_to_tangle` to carry out this step.
+
+5. Broadcast and Store
+~~~~~~~~~~~~~~~~~~~~~~
+
+The final step is to send the bundle to the network. Nodes will broadcast
+the transactions in the network, and store them in their local database.
+
+In PyOTA, use :py:meth:`~Iota.broadcast_and_store` to achieve this.
+
+Observe the bird's-eye view of the Tangle depicted at the last step of the
+process. Our transactions are part of the Tangle, referencing each other and
+the two tips. Newer transactions may reference our transactions as branch or
+trunk.
+
+.. note::
+ As more transactions are added to the Tangle that reference our transactions
+ – and then more are added that reference those transactions, and so on – this
+ increases the `cumulative weight`_ of our transactions. The higher the
+ cumulative weight of our transactions, the higher the chance for them to
+ get confirmed.
+
+Use the Library
+---------------
+
+The IOTA libraries help you to abstract away the low-level operations needed
+to create transfers. The figure below illustrates the different ways you can
+build and send a transfer.
+
+.. figure:: images/transfer_api.svg
+ :scale: 100 %
+ :alt: Different ways of sending a transfer in IOTA.
+
+ API commands for sending transfers.
+
+Let's look at some code snippets on how to perform the above with an imaginary
+bundle that has 3 fictional transactions.
+
+1. Level Padawan
+~~~~~~~~~~~~~~~~
+The easiest and most convenient way is to use :py:meth:`~Iota.send_transfer`
+extended API method. You still need to create the transactions yourself
+with :py:class:`ProposedTransaction`.
+
+.. code-block::
+
+ from iota import Iota, ProposedTransaction, Address
+
+ api = Iota('https://nodes.devnet.iota.org:443')
+
+ fictional_transactions = [
+ ProposedTransaction(
+ address=Address(b'FIRSTRANDOMADDRESS'),
+ value=0,
+ # You could add a tag or message here too!
+ ),
+ ProposedTransaction(
+ address=Address(b'SECONDRANDOMADDRESS'),
+ value=0,
+ ),
+ ProposedTransaction(
+ address=Address(b'THIRDRANDOMADDRESS'),
+ value=0,
+ )
+ ]
+
+ imaginary_bundle = api.send_transfer(
+ transfers=transactions
+ )['bundle']
+
+As all API methods in PyOTA, :py:meth:`~Iota.send_transfer` also returns
+a ``dict``. The ``bundle`` key holds the value of :py:class:`Bundle`.
+
+It's important to note, that for value transfers, you will need your seed as well.
+:py:meth:`~Iota.send_transfer` will look for ``input addresses`` to fund outgoing
+transactions in the bundle, and auto-generate an unused ``change address`` if
+there is a remainder amount of tokens. It will also take care of finalizing the
+bundle and signing the necessary input transactions.
+
+2. Level Obi-Wan
+~~~~~~~~~~~~~~~~
+Instead of :py:meth:`~Iota.send_transfer`, you can use the combination of
+:py:meth:`~Iota.prepare_transfer` and :py:meth:`~Iota.send_trytes` to achieve
+the same result.
+
+.. tip::
+ This can be useful if you want to prepare the transactions (including signing inputs) on one device, but you want to then transfer the data to another device for transmission to the Tangle. For example, you might :py:meth:`~Iota.prepare_transfer` on an air-gapped computer that has your seed stored on it, but then transfer the resulting trytes to a networked computer (that does not have your seed) to :py:meth:`~Iota.send_trytes`.
+
+.. code-block::
+
+ from iota import Iota, ProposedTransaction, Address
+
+ api = Iota('https://nodes.devnet.iota.org:443')
+
+ transactions = [
+ ProposedTransaction(
+ address=Address(b'FIRSTRANDOMADDRESS'),
+ value=0,
+ ),
+ ProposedTransaction(
+ address=Address(b'SECONDRANDOMADDRESS'),
+ value=0,
+ ),
+ ProposedTransaction(
+ address=Address(b'THIRDRANDOMADDRESS'),
+ value=0,
+ )
+ ]
+
+ prepared_trytes = api.prepare_transfer(
+ transfers=transactions
+ )['trytes']
+
+ imaginary_bundle_trytes = api.send_trytes(
+ trytes=prepared_trytes
+ )['trytes']
+
+A difference here is that the end result, ``imaginary_bundle_trytes`` is a list
+of :py:class:`TransactionTrytes`, and not a :py:class:`Bundle` object.
+
+3. Level Yoda
+~~~~~~~~~~~~~
+Being the master Jedi of the PyOTA universe means that you know the most about
+the force of low-level API methods. Use it wisely!
+
+.. tip::
+ You generally won't need to split out the process explicitly like this in your application code, but it is useful to understand what :py:meth:`~Iota.send_transfer` does under-the-hood, so that you are better-equipped to troubleshoot any issues that may occur during the process.
+
+.. code-block::
+
+ from iota import Iota, ProposedTransaction, Address, ProposedBundle
+
+ api = Iota('https://nodes.devnet.iota.org:443')
+
+ transactions = [
+ ProposedTransaction(
+ address=Address(b'FIRSTRANDOMADDRESS'),
+ value=0,
+ ),
+ ProposedTransaction(
+ address=Address(b'SECONDRANDOMADDRESS'),
+ value=0,
+ ),
+ ProposedTransaction(
+ address=Address(b'THIRDRANDOMADDRESS'),
+ value=0,
+ )
+ ]
+
+ bundle = ProposedBundle()
+
+ for tx in transactions:
+ bundle.add_transaction(tx)
+
+ # If it was a value transfer, we would also need to:
+ # bundle.add_inputs()
+ # bundle.send_unspent_inputs_to()
+
+ bundle.finalize()
+
+ # Again, for value transfers, we would need to:
+ # bundle.sign_inputs(KeyGenerator(b'SEEDGOESHERE'))
+
+ gtta_response = api.get_transactions_to_approve(depth=3)
+
+ trunk = gtta_response['trunkTransaction']
+ branch = gtta_response['branchTransaction']
+
+ attached_trytes = api.attach_to_tangle(
+ trunk_transaction=trunk,
+ branch_transaction=branch,
+ trytes=bundle.as_tryte_strings()
+ )['trytes']
+
+ api.broadcast_transactions(attached_trytes)
+
+ api.store_transactions(attached_trytes)
+
+ imaginary_bundle = Bundle.from_tryte_strings(attached_trytes)
+
+
+.. _transfer bundles: https://docs.iota.org/docs/getting-started/0.1/transactions/bundles#transfer-bundles
+.. _zero-value bundles: https://docs.iota.org/docs/getting-started/0.1/transactions/bundles#zero-value-bundle
+.. _bundle essence: https://docs.iota.org/docs/getting-started/0.1/transactions/bundles#bundle-essence
+.. _within the bundle are linked together: https://docs.iota.org/docs/getting-started/0.1/transactions/bundles
+.. _minimum weight magnitude: https://docs.iota.org/docs/getting-started/0.1/network/minimum-weight-magnitude
+.. _cumulative weight: https://blog.iota.org/the-tangle-an-illustrated-introduction-f359b8b2ec80
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
index dcbbdc8..02c3799 100644
--- a/docs/tutorials.rst
+++ b/docs/tutorials.rst
@@ -8,7 +8,7 @@ to help you understand how to carry out specific tasks with PyOTA.
The example scripts displayed here can also be found under ``examples/tutorials/``
directory in the repository. Run them in a Python environment that has PyOTA
-installed. See :ref:`Install PyOTA` for more info.
+installed. See :ref:`README:Install PyOTA` for more info.
If you feel that something is missing or not clear, please post your questions
and suggestions in the `PyOTA Bug Tracker`_.
@@ -43,7 +43,7 @@ something from the library, you need to import it from there.
Notice, how we import the :py:class:`Iota` object, that defines a
so-called extended API object. We will use this to send and receive data from
-the network. Read more about API objects at :ref:`PyOTA API Classes`.
+the network. Read more about API objects at :ref:`api:PyOTA API Classes`.
We also import the ``pprint`` method that prettifies the output before printing
it to the console.
@@ -141,7 +141,7 @@ therefore we are restricted to the `tryte alphabet`_.
:lines: 16-22
:lineno-start: 16
-It's time to construct the transaction. According to :ref:`Transaction Types`,
+It's time to construct the transaction. According to :ref:`types:Transaction Types`,
PyOTA uses :py:class:`ProposedTransaction` to build transactions that are not
yet broadcast to the network. Oberve, that the ``value=0`` means this is
a zero-value transaction.
@@ -284,7 +284,7 @@ that has no transactions referencing it on the Tangle and was never spent from.
If we were to generate more addresses starting from a desired index,
we could specify the ``start`` and ``count`` parameters. Read more about how to
-generate addresses in PyOTA at :ref:`Generating Addresses`.
+generate addresses in PyOTA at :ref:`addresses:Generating Addresses`.
On line 20 we access the first element of the list of addresses in the response
dictionary.
@@ -588,7 +588,7 @@ An address is also needed, so we generate one with the help of
index of the generated address, and don't forget, that the method returns a
``dict`` with a list of addresses, even if it contains only one.
For more detailed explanation on how addresses are generated in PyOTA,
-refer to the :ref:`Generating Addresses` page.
+refer to the :ref:`adresses:Generating Addresses` page.
We also attach a custom :py:class:`Tag` to our :py:class:`ProposedTransaction`.
Note, that if our ``trytes_encrypted_data`` was longer than the maximum payload
diff --git a/docs/types.rst b/docs/types.rst
index 0b24971..e3b3044 100644
--- a/docs/types.rst
+++ b/docs/types.rst
@@ -249,9 +249,9 @@ See the class documentation below:
^^^^^^^^^^^^^^^^^^^^^
.. automethod:: Transaction.from_tryte_string
-**get_signature_validation_trytes**
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. automethod:: Transaction.get_signature_validation_trytes
+**get_bundle_essence_trytes**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automethod:: Transaction.get_bundle_essence_trytes
ProposedTransaction
~~~~~~~~~~~~~~~~~~~
diff --git a/iota/api.py b/iota/api.py
index 4976a30..2c1a3e6 100644
--- a/iota/api.py
+++ b/iota/api.py
@@ -67,7 +67,7 @@ class StrictIota(AsyncStrictIota):
to :py:meth:`attach_to_tangle` to
`ccurl pow interface `_.
- See :ref:`Optional Local Pow` for more info and
+ See :ref:`README:Optional Local Pow` for more info and
:ref:`find out` how to use it.
"""
@@ -88,7 +88,7 @@ def __init__(self, adapter, devnet=False, local_pow=False):
to :py:meth:`attach_to_tangle` to
`ccurl pow interface `_.
- See :ref:`Optional Local Pow` for more info and
+ See :ref:`README:Optional Local Pow` for more info and
:ref:`find out` how to use it.
"""
super().__init__(adapter, devnet, local_pow)
@@ -828,7 +828,7 @@ class Iota(StrictIota, AsyncIota):
to :py:meth:`attach_to_tangle` to
`ccurl pow interface `_.
- See :ref:`Optional Local Pow` for more info and
+ See :ref:`README:Optional Local Pow` for more info and
:ref:`find out` how to use it.
References:
diff --git a/iota/api_async.py b/iota/api_async.py
index 6004242..c013cde 100644
--- a/iota/api_async.py
+++ b/iota/api_async.py
@@ -38,7 +38,7 @@ class AsyncStrictIota:
to :py:meth:`attach_to_tangle` to
`ccurl pow interface `_.
- See :ref:`Optional Local Pow` for more info and
+ See :ref:`README:Optional Local Pow` for more info and
:ref:`find out` how to use it.
"""
@@ -59,7 +59,7 @@ def __init__(self, adapter, devnet=False, local_pow=False):
to :py:meth:`attach_to_tangle` to
`ccurl pow interface `_.
- See :ref:`Optional Local Pow` for more info and
+ See :ref:`README:Optional Local Pow` for more info and
:ref:`find out` how to use it.
"""
super().__init__()
@@ -769,7 +769,7 @@ class AsyncIota(AsyncStrictIota):
to :py:meth:`attach_to_tangle` to
`ccurl pow interface `_.
- See :ref:`Optional Local Pow` for more info and
+ See :ref:`README:Optional Local Pow` for more info and
:ref:`find out` how to use it.
References:
diff --git a/iota/transaction/base.py b/iota/transaction/base.py
index c904c70..2cf3ecd 100644
--- a/iota/transaction/base.py
+++ b/iota/transaction/base.py
@@ -570,11 +570,23 @@ def as_tryte_string(self):
+ self.nonce
)
- def get_signature_validation_trytes(self):
+ def get_bundle_essence_trytes(self):
# type: () -> TryteString
"""
- Returns the values needed to validate the transaction's
- ``signature_message_fragment`` value.
+ Returns the values needed for calculating bundle hash.
+ The bundle hash is the hash of the bundle essence, which is itself
+ the hash of the following fields of transactions in the bundle:
+
+ - ``address``,
+ - ``value``,
+ - ``legacy_tag``,
+ - ``current_index``,
+ - ``last_index``,
+ - and ``timestamp``.
+
+ The transaction's ``signature_message_fragment`` field contains
+ the signature generated by signing the bundle hash with the address's
+ private key.
:return:
:py:class:`TryteString` object.
diff --git a/iota/transaction/creation.py b/iota/transaction/creation.py
index 302e5f8..3d5bc5a 100644
--- a/iota/transaction/creation.py
+++ b/iota/transaction/creation.py
@@ -476,7 +476,7 @@ def finalize(self):
txn.current_index = i
txn.last_index = last_index
- sponge.absorb(txn.get_signature_validation_trytes().as_trits())
+ sponge.absorb(txn.get_bundle_essence_trytes().as_trits())
bundle_hash_trits = [0] * HASH_LENGTH
sponge.squeeze(bundle_hash_trits)