[JAVA] IOTA: [Technical explanation] The whole picture of the remittance bundle.

English here. Special thanks to Take san for translating it!

Past articles, * IOTA: [Technical explanation] Transactional anatomy! What is the wallet doing behind the scenes? * It was a maniac that I couldn't explain, but I made it so that itching could be reached. This is because the basis of this Bundle is the prerequisite knowledge for understanding IOTA's hot technology, MAM and multi-signature in the future. The source code in the article used Java. The reason is that Java is my favorite and it is easier to understand if you can see the type of the variable. Of course, IOTA can be developed in various environments, so if you are interested, take a look at IOTA official Github.

What is IOTA?

Since IOTA is not well known yet, a collection of links to help you understand the basics of IOTA.

** IOTA Japanese Fan Site ** Actual IOTA Japan official site. This is because the official IOTA information is translated into Japanese and posted. A lot of information for beginners is also posted. ** White Paper ** English [Japanese](https://www.dropbox.com /s/1w5vtu7s4idquc9/IOTA_Whitepaper%20v1.1%20in%20Japanese.pdf?dl=0) The outline of Tangle is up to the beginning, and after that, safety, expected attacks and their resistance are explained with advanced mathematics. ing. The second half is not suitable for beginners. ** Reddit beginner thread (English) ** I started here. ** IOTA Guide (English) ** If the white paper is the Faculty of Science, this is the Faculty of Engineering.

The IOTA community has grown on the basis of Slack. There is also a Japanese channel ** # japanese **, so feel free to join and ask questions.

Transaction structure

It may be easier to understand if you also look at the past articles. The source below is excerpted from Transaction.java. I've commented on the most important ones.

Transaction.java


public class Transaction {

    private static final transient Logger log = LoggerFactory.getLogger(Transaction.class);

    private transient ICurl customCurl;

    private String hash;                //Transaction hash (identity)
    private String signatureFragments;  //A field with a length of 2187 trites used for signatures, etc.
    private String address;             //Specify the address
    private long value;                 //Specify the amount
    private String obsoleteTag;
    private long timestamp;             //Became mandatory
    private long currentIndex;          //What number is this Tx in the Bundle? (Start from 0)
    private long lastIndex;             //What is the Tx index at the end of the Bundle?
    private String bundle;              //Specifies which Bundle this transaction belongs to
    private String trunkTransaction;    //Approve Tx Part 1
    private String branchTransaction;   //Approve Tx Part 2
    private String nonce;               //Search for PoW
    private Boolean persistence;        //True if approved. False if not approved
    private long attachmentTimestamp;
    private String tag;                 //Any 27 trite tags
    private long attachmentTimestampLowerBound;
    private long attachmentTimestampUpperBound;

A minimum of two is required for remittance: ** receiving address (destination) ** and ** sending source address (sender) **. However, as you can see, each Transaction object has only one address. Therefore, IOTA introduced the concept of Bundle. By including multiple Transaction objects in the Bundle, various necessary items such as the receiving address, the remittance source address, and the signature are managed by dividing the roles into separate Transaction objects.

Remittance API

The API for sending money is easy to see.

Transfer class

Hold remittance information.

Transfer.java


public class Transfer {

    private String timestamp;      //Time stamp
    private String address;        //Receiving address (destination)
    private String hash;
    private Boolean persistence;   // true:Approved, false:Unapproved
    private long value;            //Amount of remittance
    private String message;        //Any trite
    private String tag;            //Tag (27 trites)

    //Transfer object generation
    //Destination address, remittance amount, arbitrary message trick, tag
    public Transfer(String address, long value, String message, String tag) {
        this.address = address;
        this.value = value;
        this.message = message;
        this.tag = tag;
    }
...

sendTransfer function

A function called sendTransfer is used for remittance. Make multiple remittances at once by taking a list of Transfer objects as an argument.

IotaApi.java


/**
 * Wrapper function that basically does prepareTransfers, as well as attachToTangle and finally, it broadcasts and stores the transactions locally.
 *
 * @param seed               Tryte-encoded seed
 * @param security           The security level of private key / seed.
 * @param depth              The depth.
 * @param minWeightMagnitude The minimum weight magnitude.
 * @param transfers          Array of transfer objects.
 * @param inputs             Optional: List of inputs used for funding the transfer.
 * @param remainderAddress   Optional: If defined, this remainderAddress will be used for sending the remainder value (of the inputs) to.
 * @param validateInputs     Whether or not to validate the balances of the provided inputs.
 * @param validateAddresses  Whether or not to validate if the destination address is already used and if a key reuse is detect.
 * @return Array of valid Transaction objects.
 * @throws ArgumentException is thrown when the specified input is not valid.
 */
public SendTransferResponse sendTransfer(
        String seed,
        int security, int depth, int minWeightMagnitude,
        final List<Transfer> transfers,
        List<Input> inputs,
        String remainderAddress,
        boolean validateInputs, boolean validateAddresses) throws ArgumentException {
....
}

money transfer

** Take a quick look at the example "Mr. A puts a message on Mr. B and remits 100 currencies" **.

//The message is a trite of any size
String message = "MESSAGE..."

//The tag is 27 trites
String tag = "SAMPLE9TAG99999999999"

//The address is 81 Trite. Mr. B's address.
String address = "B9ADDRESS..."

//Generate Transfer object (send 100 currencies to Mr. B's address with a message)
Transfer transfer = new Transfer(address,100,message,tag);
List<Transfer> list = new List<>();
list.add(transfer);

//money transfer
sendTransfer("Specify Mr. A's seed",security,depth,minWeightMagnitude,list,null,null,true,true);

I tried to simplify the remittance part of the source code of the official wallet. I haven't tried this, so I can't say anything, but the remittance is done in the above flow. This article will focus on what's inside this sendTransfer function. The correct way to send money is to look at the official source, so I'll post a link.

Python iota.lib.py/examples/send_transfer.py Android android-wallet-app/app/src/main/java/org/iota/wallet/ui/fragment/NewTransferFragment.java

Bundle structure

First, IOTA creates a Bundle for remittance. A Bundle is a collection of Transaction, which is the smallest unit of IOTA. Information necessary for one remittance such as remittance amount and signature is summarized. The Bundle has three main parts.

① Output section-'output' (specify where and how much money to send) ② Input section-'input' (specify where to bring the amount) ③ Difference output unit-'remainder' (specify where to send the change)

An example of sending 13i to the addressDEFBQV .... (Security = 2) bundle_basic.png

Output --output

Sending money to a specified destination address is called ** output **. The output section, which is the first half of the Bundle, undertakes the output. The output unit has the following roles.

① Specify the remittance amount ② Designation of remittance destination ③ Storage of arbitrary message (message)

The example of ** "Mr. A puts a message on Mr. B and remits 100 currencies" ** is as follows.

bundle_output.png

As you can see from the figure, specify the remittance amount to value of ** Tx.0 ** and the destination to ʻaddress. Then, the message part is divided into chunks of size 2187 trites and stored in sigFof Tx.0, Tx.1, ... in order from the front. Ifmessage is shorter than 2187 trites, the output is only Tx.0, that is, one Transactionis enough. Also, if themessage is long, the Transactionwill increase and the output section itself will be long. Sincemessage is rarely a multiple of 2187, it is usually filled with a fraction of sigFwith '9'. Also, although eachmessage is represented by a trite in sigF, of course it can be converted from a trite to a character, so the content of the sentence is missing on the Tangle. Therefore, a usage method called ** MAM (Masked Authenticated Message) **, which provides a private space on the Tangle by encrypting this sigF`, has been proposed and is under research and development (next section).

Relevance to MAM

MAM is one of IOTA's most anticipated features, allowing you to save data on Tangle while maintaining privacy. In short, it encrypts the contents of this sigF, which is now exposed on Tangle and can be viewed by anyone. With IOTA, which has no fees, you can send zero yen, so you can actively use the sigF of the transaction as a private data area. The last dream of this year is to publish a commentary article.

Input section --input

Collecting the remittance amount from the address with the balance on the Tangle is called ** input **. You must have enough money somewhere to execute the output specified in the output section. You also have to prevent double payments by signing that the payment was made from the address. The input unit that undertakes them has the following roles.

① Specify the input amount ② Specify input address ③ Signature of input address

** Continuing with the example of "Mr. A puts a message on Mr. B and remits 100 currencies" **, specify where to bring more than 100 currencies. I say "more than" here because the surplus can be collected at the next difference output section.

bundle_input.png

In this example, there are two inputs (input 1 and input 2). The reason is that the total amount of each ʻaddressheld (Mr. A ① + Mr. A ② = **-144 **) can finally cover the remittance amount ** 100 **. The surplus ** 44 ** will be handled in the next section, the difference output section. If Mr. A has a balance of 100 or more at a certain address, for example, it is sufficient to input one of them, and as a result, the length of the input part becomes short. More important than that is thesigF. The signature is divided into two for one input address. This depends on the security argument of the sendTransferfunction. Ifsecurity = 1, only" 1 "is generated. In other words, in this figure, a total of two signatures are required for Mr. A ① and Mr. A ②. If security = 3`, each input address needs to be signed up to" 3 ", and a total of 2 * 3 = 6 Transactions are generated in the input section. The formula is as follows.

$ Transaction number = security * input number $

For the signature method, see [Past Articles](https://qiita.com/ABmushi/items/422d1bf94be0c919583a#%E7%BD%B2%E5%90%8D%E3%81%AE%E6%96% I mentioned it in B9% E6% B3% 95), so I hope you can refer to it.

Difference output --remainder

Since there is usually no input address that has a balance that matches the output amount, the balance that exceeds the output amount is collected from multiple input addresses. Therefore, change occurs. In IOTA, if an address once signed is used as an input address and a new signature is made, the Private Key will be leaked. In other words, do not receive money at an address once signed. If the change is returned to the original input address, it violates that principle. The change is then output to another new address. The difference output unit has the following roles.

① Designation of difference ② Specify output address

** In the example of "Mr. A puts a message on Mr. B and remits 100 currencies" **, the remainder of ** 44 ** currencies finally came out. Take a look at the figure below.

bundle_remainder.png

It's very simple. The difference output unit generates only one TX if there is a difference. The amount of change is only output to the new address of Mr. A (Mr. A ③). For those who are wondering what the new address is, [Past Articles](https://qiita.com/ABmushi/items/e271ff05884a7d47658d#%E3%82%A2%E3%83%89%E3%83%AC%E3 Please read back% 82% B9). By the way, if the change is zero (the exact input address is found), the difference output unit itself is not generated.

When sending money to multiple addresses

If you want to send money to multiple different addresses, ** increase the output by the number of addresses. ** **

bundle_mult_out.png It is easy to handle the input section and the difference output section. In this example, the input section searches for input addresses for (100 + 1000 + 634 = 1734) or more, and the difference is just to put the change in one Tx, and nothing special is done.

The whole picture of Bundle

Now, IOTA's Transaction does not just generate, it has the task of approving two Transactions called trunkTransaction and branchTransaction.

Selection of tips to approve

Transactions called Tips to approve can be easily obtained with a function called getTransactionToApprove. It's too easy, but there's a lot of advanced mathematics behind it that bothers the heads of amateurs like me. It's very unwieldy, so I'd like to ask someone who can do math to explain this.

Bundle approval relationship

As I mentioned in the previous article, I dared to redraw the figure again. 　bundle_approve.png Apply the trunkTransaction and branchTransaction returned by the getTransactionsToApprove function to the Milestone and ʻother Tx` in the figure, respectively. Take a look at the appropriate transactions and bundles in Tangle Explorer, such as https://iotasear.ch/. It should be exactly as introduced in this article. (Please report if it is different)

Cheat sheet

Printable size. I want to update it from time to time to make it beautiful. bundle_cheat_sheet.png

References

** IOTA Java Library JOTA ** iotaledger / iota.lib.java

As always, we look forward to your feedback on the article.

Recommended Posts

IOTA: [Technical explanation] The whole picture of the remittance bundle.
Explanation of the FizzBuzz problem
Explanation of the order of rails routes