From 06c32b96d86590675e1358494ea90b5923d823a9 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Wed, 2 Oct 2019 18:13:51 +0200 Subject: [PATCH 01/43] Initial commit --- text/0000-bee-bundle/0000-bee-bundle.md | 54 +++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 text/0000-bee-bundle/0000-bee-bundle.md diff --git a/text/0000-bee-bundle/0000-bee-bundle.md b/text/0000-bee-bundle/0000-bee-bundle.md new file mode 100644 index 00000000..f04cbb0b --- /dev/null +++ b/text/0000-bee-bundle/0000-bee-bundle.md @@ -0,0 +1,54 @@ ++ Feature name: (fill me in with a unique ident, `my_awesome_feature`) ++ Start date: (fill me in with today's date, YYYY-MM-DD) ++ RFC PR: [iotaledger/bee-rfcs#0000](https://github.com/iotaledger/bee-rfcs/pull/0000) ++ Bee issue: [iotaledger/bee#0000](https://github.com/iotaledger/bee/issues/0000) + +# Summary + +One paragraph explanation of the feature. + +# Motivation + +Why are we doing this? What use cases does it support? What is the expected +outcome? + +1. Write a summary of the motivation. +2. List all the specific use cases that your proposal is trying to address. +3. Where applicable, write from the perspective of the person who will be using + the software, for example using the "Job story" format: + +When ＿＿＿ , I want to ＿＿＿, so I can ＿＿＿. + ++ **Example 1:** When I query a node for a list of transactions, I want to be + able to sort them by date, so I can work with the most relevant ones. ++ **Example 2:** When I configure a node, I want to be able to control how much + transaction history the node stores, so I can make sure I only store the data + I need without incurring additional operational costs. + +# Detailed design + +This is the bulk of the RFC. Explain the design in enough detail for somebody +familiar with the IOTA and to understand, and for somebody familiar with Rust +to implement. This should get into specifics and corner-cases, and include +examples of how the feature is used. + +# Drawbacks + +Why should we *not* do this? + +# Rationale and alternatives + +- Why is this design the best in the space of possible designs? +- What other designs have been considered and what is the rationale for not + choosing them? +- What is the impact of not doing this? + +# Unresolved questions + +- What parts of the design do you expect to resolve through the RFC process + before this gets merged? +- What parts of the design do you expect to resolve through the implementation + of this feature before stabilization? +- What related issues do you consider out of scope for this RFC that could be + addressed in the future independently of the solution that comes out of this + RFC? From be8347be93225c7cc3e2fde1ddcce3616175ab2f Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Wed, 2 Oct 2019 18:19:32 +0200 Subject: [PATCH 02/43] Header information and folder/file names --- .../0018-bee-bundle.md} | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) rename text/{0000-bee-bundle/0000-bee-bundle.md => 0018-bee-bundle/0018-bee-bundle.md} (85%) diff --git a/text/0000-bee-bundle/0000-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md similarity index 85% rename from text/0000-bee-bundle/0000-bee-bundle.md rename to text/0018-bee-bundle/0018-bee-bundle.md index f04cbb0b..3ab2f2c5 100644 --- a/text/0000-bee-bundle/0000-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -1,7 +1,7 @@ -+ Feature name: (fill me in with a unique ident, `my_awesome_feature`) -+ Start date: (fill me in with today's date, YYYY-MM-DD) -+ RFC PR: [iotaledger/bee-rfcs#0000](https://github.com/iotaledger/bee-rfcs/pull/0000) -+ Bee issue: [iotaledger/bee#0000](https://github.com/iotaledger/bee/issues/0000) ++ Feature name: `bee-bundle` ++ Start date: 2019-10-02 ++ RFC PR: [iotaledger/bee-rfcs#18](https://github.com/iotaledger/bee-rfcs/pull/18) ++ Bee issue: [iotaledger/bee#63](https://github.com/iotaledger/bee/issues/63) # Summary From b774f9f7aca1a78517319d01b2fc48523f366e6a Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Thu, 3 Oct 2019 10:16:01 +0200 Subject: [PATCH 03/43] TODO sections --- text/0018-bee-bundle/0018-bee-bundle.md | 38 ++++--------------------- 1 file changed, 6 insertions(+), 32 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 3ab2f2c5..54a510fe 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -5,50 +5,24 @@ # Summary -One paragraph explanation of the feature. + # Motivation -Why are we doing this? What use cases does it support? What is the expected -outcome? - -1. Write a summary of the motivation. -2. List all the specific use cases that your proposal is trying to address. -3. Where applicable, write from the perspective of the person who will be using - the software, for example using the "Job story" format: - -When ＿＿＿ , I want to ＿＿＿, so I can ＿＿＿. - -+ **Example 1:** When I query a node for a list of transactions, I want to be - able to sort them by date, so I can work with the most relevant ones. -+ **Example 2:** When I configure a node, I want to be able to control how much - transaction history the node stores, so I can make sure I only store the data - I need without incurring additional operational costs. + # Detailed design -This is the bulk of the RFC. Explain the design in enough detail for somebody -familiar with the IOTA and to understand, and for somebody familiar with Rust -to implement. This should get into specifics and corner-cases, and include -examples of how the feature is used. + # Drawbacks -Why should we *not* do this? + # Rationale and alternatives -- Why is this design the best in the space of possible designs? -- What other designs have been considered and what is the rationale for not - choosing them? -- What is the impact of not doing this? + # Unresolved questions -- What parts of the design do you expect to resolve through the RFC process - before this gets merged? -- What parts of the design do you expect to resolve through the implementation - of this feature before stabilization? -- What related issues do you consider out of scope for this RFC that could be - addressed in the future independently of the solution that comes out of this - RFC? + From 785f6bead4f237a1817b7c2712176313947e84b1 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Thu, 3 Oct 2019 15:08:51 +0200 Subject: [PATCH 04/43] Bundle hash generation --- text/0018-bee-bundle/0018-bee-bundle.md | 39 +++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 54a510fe..4c7969e1 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -5,6 +5,12 @@ # Summary +Useful links: +- [Bundles and transactions +](https://docs.iota.org/docs/dev-essentials/0.1/concepts/bundles-and-transactions) +- [What is a bundle? +](https://docs.iota.org/docs/getting-started/0.1/introduction/what-is-a-bundle) + # Motivation @@ -13,6 +19,39 @@ # Detailed design +## Bundle hash generation + +The hash of a bundle is based on the bundle essence of each of its transactions. The bundle essence of a transaction is composed of the following fields. + +| Name | Size | +| ------------- | --------- | +| address | 243 trits | +| value | 81 trits | +| obsolete_tag | 81 trits | +| timestamp | 27 trits | +| current_index | 27 trits | +| last_index | 27 trits | + +The bundle hash is generated with a sponge by iterating through the bundle, from `0` to `last_index`, absorbing the bundle essence of each transaction and eventually squeezing the bundle hash from the sponge. + +Pseudocode: + +``` +bundleHash(bundle) +| sponge = Sponge(HASH_FUNCTION) +| for transaction in bundle +| | sponge.absorb(transaction.essence()) +| return sponge.squeeze() +``` + +*In the current mainnet, the hash function of the sponge used to generate bundle hashes is Kerl.* + +## Bundle finalisation + + + +## Bundle validation + # Drawbacks From f50f83d5ea742efc667c3090f3e604e41230b4c3 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Thu, 3 Oct 2019 16:14:53 +0200 Subject: [PATCH 05/43] Bundle finalisation --- text/0018-bee-bundle/0018-bee-bundle.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 4c7969e1..b0659a33 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -48,7 +48,21 @@ bundleHash(bundle) ## Bundle finalisation - +Finalising a bundle means computing the bundle hash, verifying that it matches the security requirement and setting it to all the transactions. + +Pseudocode: + +``` +bundleFinalise(bundle) +| hash = bundleHash(bundle) +| while hash.normalise().find('M') +| | bundle.at(0).obsolete_tag++ +| | hash = bundleHash(bundle) +| for transaction in bundle +| | transaction.setBundleHash(hash) +``` + +*Security requirement: due to the implementation of the signature process, the normalised bundle hash can't contain a `M` or `13` because it could expose a significant part of the private key, weakening the signature. The bundle hash is then repetitively generated with a slight modification until its normalisation doesn't contain a `M`.* ## Bundle validation @@ -65,3 +79,6 @@ bundleHash(bundle) # Unresolved questions + +- Should this RFC include explanation and/or pseudocode for bundle hash normalisation ? +- Should this RFC expands a bit more on the M-Bug ? Or give a link ? From d59e5da4cd1d0dcb2e0cbf4571a19873d5a33889 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Thu, 3 Oct 2019 18:45:50 +0200 Subject: [PATCH 06/43] Bundle validation --- text/0018-bee-bundle/0018-bee-bundle.md | 56 ++++++++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index b0659a33..f936335b 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -39,8 +39,10 @@ Pseudocode: ``` bundleHash(bundle) | sponge = Sponge(HASH_FUNCTION) +| | for transaction in bundle | | sponge.absorb(transaction.essence()) +| | return sponge.squeeze() ``` @@ -55,9 +57,11 @@ Pseudocode: ``` bundleFinalise(bundle) | hash = bundleHash(bundle) +| | while hash.normalise().find('M') | | bundle.at(0).obsolete_tag++ | | hash = bundleHash(bundle) +| | for transaction in bundle | | transaction.setBundleHash(hash) ``` @@ -66,7 +70,57 @@ bundleFinalise(bundle) ## Bundle validation - +Validating a bundle means checking the syntactic and semantic integrity of a bundle as a whole and of its constituent transactions. As bundles are atomic transfers, either all or none of the transactions will be accepted by the network. + +The following assertions must be true: + +- bundle has announced size; +- transactions share the same bundle hash; +- transactions absolute value doesn't exceed total IOTA supply; +- bundle absolute sum never exceeds total IOTA supply; +- transactions appear in the announced order; +- value transactions have an address ending in `0` i.e. has been generated with Kerl; +- bundle inputs and outputs are balanced i.e. the bundle sum equals `0`; +- announced bundle hash matches the computed bundle hash; +- for spending transactions, the signature is valid; + +Pseudocode: + +``` +bundleValidate(bundle): +| value = 0 +| current_index = 0 +| +| if bundle.length() != bundle.at(0).last_index + 1 +| | return BUNDLE_INVALID_LENGTH +| +| bundle_hash = bundle.at(0).bundle_hash +| last_index = bundle.at(0).last_index +| +| for transaction in bundle +| | if transaction.bundle_hash != bundle_hash +| | | return BUNDLE_INVALID_HASH +| | if abs(transaction.value) > IOTA_SUPPLY +| | | return BUNDLE_INVALID_TRANSACTION_VALUE +| | value = value + transaction.value +| | if abs(value) > IOTA_SUPPLY +| | | return BUNDLE_INVALID_VALUE +| | if transaction.current_index != current_index++ +| | | return BUNDLE_INVALID_INDEX +| | if transaction.last_index != last_index +| | | return BUNDLE_INVALID_INDEX +| | if transaction.value != 0 && transaction.address.last != 0 +| | | return BUNDLE_INVALID_ADDRESS +| +| if value != 0 +| | return BUNDLE_INVALID_VALUE +| if bundle_hash != bundleHash(bundle) +| | return BUNDLE_INVALID_HASH +| if !bundleSignaturesValidate(bundle) +| | return BUNDLE_INVALID_SIGNATURE +| +| return BUNDLE_VALID +``` # Drawbacks From aa8b1a6930648c43c3b493d3c3db7a7c64e66e65 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Fri, 4 Oct 2019 10:55:42 +0200 Subject: [PATCH 07/43] Organized design section --- text/0018-bee-bundle/0018-bee-bundle.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index f936335b..5d5e3819 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -19,7 +19,11 @@ Useful links: # Detailed design -## Bundle hash generation +In this section, we present the main algorithms needed to process bundles, server side and client side, as well as `Bundle` and `BundleBuilder` objects. + +## Algorithms + +### Bundle hash generation The hash of a bundle is based on the bundle essence of each of its transactions. The bundle essence of a transaction is composed of the following fields. @@ -48,7 +52,7 @@ bundleHash(bundle) *In the current mainnet, the hash function of the sponge used to generate bundle hashes is Kerl.* -## Bundle finalisation +### Bundle finalisation Finalising a bundle means computing the bundle hash, verifying that it matches the security requirement and setting it to all the transactions. @@ -68,7 +72,7 @@ bundleFinalise(bundle) *Security requirement: due to the implementation of the signature process, the normalised bundle hash can't contain a `M` or `13` because it could expose a significant part of the private key, weakening the signature. The bundle hash is then repetitively generated with a slight modification until its normalisation doesn't contain a `M`.* -## Bundle validation +### Bundle validation Validating a bundle means checking the syntactic and semantic integrity of a bundle as a whole and of its constituent transactions. As bundles are atomic transfers, either all or none of the transactions will be accepted by the network. @@ -122,6 +126,18 @@ bundleValidate(bundle): | return BUNDLE_VALID ``` +## Bundle and BundleBuilder + + + +### Bundle + + + +### BundleBuilder + + + # Drawbacks From abe39f1f1bbc1578720ffa16ee5166ef642c79be Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Fri, 4 Oct 2019 15:32:17 +0200 Subject: [PATCH 08/43] Summary --- text/0018-bee-bundle/0018-bee-bundle.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 5d5e3819..8a938f3f 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -5,13 +5,19 @@ # Summary +The smallest communication unit in the IOTA protocol is the `Transaction`. Everything, including payment settlements and/or plain data, is propagated through the IOTA network in `Transactions`. + +A `Transaction` is `2673` trytes and the part available to the user is `2187` trytes. This part holds a signature in case of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs more than one `Transaction` to fulfil his operation, for example signatures with security level `2` or `3` don't fit in a single `Transaction` and user-provided data may exceed the allowance so they need to be fragmented across multiple `Transactions`. Moreover, a `Transaction` may not make sense on its own, for example an input/output `Transaction` alone would change the total amount of the ledger so it has to be paired with another complementary input/output. + +For these reasons, `Transactions` have to be processed as a whole, in groups called `Bundles`. A `Bundle` is an atomic operation in the sense that either all or none of its `Transactions` are accepted by the network. Even single `Transactions` are propagated through the network within a `Bundle` making it the only confirmable communication unit of the IOTA protocol. + +This RFC proposes ways to create and manipulate a `Bundle` and describe the associated algorithms. + Useful links: -- [Bundles and transactions -](https://docs.iota.org/docs/dev-essentials/0.1/concepts/bundles-and-transactions) - [What is a bundle? ](https://docs.iota.org/docs/getting-started/0.1/introduction/what-is-a-bundle) - - +- [Bundles and transactions +](https://docs.iota.org/docs/dev-essentials/0.1/concepts/bundles-and-transactions) # Motivation From b4a2122836d9c36044f480347103f3cb94be7558 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Fri, 4 Oct 2019 16:58:22 +0200 Subject: [PATCH 09/43] TODO and remove a question --- text/0018-bee-bundle/0018-bee-bundle.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 8a938f3f..64e9c81f 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -29,6 +29,8 @@ In this section, we present the main algorithms needed to process bundles, serve ## Algorithms + + ### Bundle hash generation The hash of a bundle is based on the bundle essence of each of its transactions. The bundle essence of a transaction is composed of the following fields. @@ -132,6 +134,8 @@ bundleValidate(bundle): | return BUNDLE_VALID ``` + + ## Bundle and BundleBuilder @@ -156,5 +160,4 @@ bundleValidate(bundle): -- Should this RFC include explanation and/or pseudocode for bundle hash normalisation ? - Should this RFC expands a bit more on the M-Bug ? Or give a link ? From ac93b287aeac433b93eddfd7862a9fddca9b559e Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Fri, 4 Oct 2019 17:30:38 +0200 Subject: [PATCH 10/43] Details on bundle hash --- text/0018-bee-bundle/0018-bee-bundle.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 64e9c81f..cd9b84c3 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -5,13 +5,13 @@ # Summary -The smallest communication unit in the IOTA protocol is the `Transaction`. Everything, including payment settlements and/or plain data, is propagated through the IOTA network in `Transactions`. +The smallest communication unit in the IOTA protocol is the transaction. Everything, including payment settlements and/or plain data, is propagated through the IOTA network in transactions. -A `Transaction` is `2673` trytes and the part available to the user is `2187` trytes. This part holds a signature in case of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs more than one `Transaction` to fulfil his operation, for example signatures with security level `2` or `3` don't fit in a single `Transaction` and user-provided data may exceed the allowance so they need to be fragmented across multiple `Transactions`. Moreover, a `Transaction` may not make sense on its own, for example an input/output `Transaction` alone would change the total amount of the ledger so it has to be paired with another complementary input/output. +A transaction is `2673` trytes and the part available to the user is `2187` trytes. This part holds a signature in case of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs more than one transaction to fulfil his operation, for example signatures with security level `2` or `3` don't fit in a single transaction and user-provided data may exceed the allowance so they need to be fragmented across multiple transactions. Moreover, a transaction may not make sense on its own, for example an input/output transaction alone would change the total amount of the ledger so it has to be paired with another complementary input/output. -For these reasons, `Transactions` have to be processed as a whole, in groups called `Bundles`. A `Bundle` is an atomic operation in the sense that either all or none of its `Transactions` are accepted by the network. Even single `Transactions` are propagated through the network within a `Bundle` making it the only confirmable communication unit of the IOTA protocol. +For these reasons, transactions have to be processed as a whole, in groups called bundles. A bundle is an atomic operation in the sense that either all or none of its transactions are accepted by the network. Even single transactions are propagated through the network within a bundle making it the only confirmable communication unit of the IOTA protocol. -This RFC proposes ways to create and manipulate a `Bundle` and describe the associated algorithms. +This RFC proposes ways to create and manipulate a bundle and describe the associated algorithms. Useful links: - [What is a bundle? @@ -25,7 +25,7 @@ Useful links: # Detailed design -In this section, we present the main algorithms needed to process bundles, server side and client side, as well as `Bundle` and `BundleBuilder` objects. + ## Algorithms @@ -33,7 +33,9 @@ In this section, we present the main algorithms needed to process bundles, serve ### Bundle hash generation -The hash of a bundle is based on the bundle essence of each of its transactions. The bundle essence of a transaction is composed of the following fields. +A bundle hash ties different transactions together. By having this common hash in their `bundle` field, it makes it clear that these transactions should be processed as a whole. + +The hash of a bundle is derived from the bundle essence of each of its transactions. The bundle essence of a transaction is composed of the following fields. | Name | Size | | ------------- | --------- | From dd81c80f26c7eb1937d2d58739407e6316fdfffc Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Fri, 4 Oct 2019 18:47:00 +0200 Subject: [PATCH 11/43] Server side or client side --- text/0018-bee-bundle/0018-bee-bundle.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index cd9b84c3..0205e514 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -33,6 +33,8 @@ Useful links: ### Bundle hash generation +*Client side and server side operation.* + A bundle hash ties different transactions together. By having this common hash in their `bundle` field, it makes it clear that these transactions should be processed as a whole. The hash of a bundle is derived from the bundle essence of each of its transactions. The bundle essence of a transaction is composed of the following fields. @@ -64,6 +66,8 @@ bundleHash(bundle) ### Bundle finalisation +*Client side operation.* + Finalising a bundle means computing the bundle hash, verifying that it matches the security requirement and setting it to all the transactions. Pseudocode: @@ -84,6 +88,8 @@ bundleFinalise(bundle) ### Bundle validation +*Server side operation.* + Validating a bundle means checking the syntactic and semantic integrity of a bundle as a whole and of its constituent transactions. As bundles are atomic transfers, either all or none of the transactions will be accepted by the network. The following assertions must be true: From 3acd470f7cd5fc031461b9a95d41ce66984bafb8 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Fri, 4 Oct 2019 20:39:45 +0200 Subject: [PATCH 12/43] Bundle finalisation detail --- text/0018-bee-bundle/0018-bee-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 0205e514..dcaa1f18 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -68,7 +68,7 @@ bundleHash(bundle) *Client side operation.* -Finalising a bundle means computing the bundle hash, verifying that it matches the security requirement and setting it to all the transactions. +Finalising a bundle means computing the bundle hash, verifying that it matches the security requirement and setting it to all the transactions of the bundle. After finalisation, transactions of a bundle are ready to be safely attached to the tangle. Pseudocode: From 1953b9cd3fd31cc8b60f3e5c8e16981f58eb16dc Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 7 Oct 2019 10:13:23 +0200 Subject: [PATCH 13/43] Bundle validation detail --- text/0018-bee-bundle/0018-bee-bundle.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index dcaa1f18..bb8d25b2 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -90,9 +90,9 @@ bundleFinalise(bundle) *Server side operation.* -Validating a bundle means checking the syntactic and semantic integrity of a bundle as a whole and of its constituent transactions. As bundles are atomic transfers, either all or none of the transactions will be accepted by the network. +Validating a bundle means checking the syntactic and semantic integrity of a bundle as a whole and of its constituent transactions. As bundles are atomic transfers, either all or none of the transactions will be accepted by the network. After validation, transactions of a bundle are candidates to be included to the ledger. -The following assertions must be true: +For a bundle to be considered valid, the following assertions must be true: - bundle has announced size; - transactions share the same bundle hash; From 17a984d42e15c7f21b42b92885e169bac41063c9 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 7 Oct 2019 11:32:25 +0200 Subject: [PATCH 14/43] Add link to transaction-module RFC --- text/0018-bee-bundle/0018-bee-bundle.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index bb8d25b2..f15802a2 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -5,6 +5,9 @@ # Summary +This RFC is based on [`transaction-module`](). + + The smallest communication unit in the IOTA protocol is the transaction. Everything, including payment settlements and/or plain data, is propagated through the IOTA network in transactions. A transaction is `2673` trytes and the part available to the user is `2187` trytes. This part holds a signature in case of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs more than one transaction to fulfil his operation, for example signatures with security level `2` or `3` don't fit in a single transaction and user-provided data may exceed the allowance so they need to be fragmented across multiple transactions. Moreover, a transaction may not make sense on its own, for example an input/output transaction alone would change the total amount of the ledger so it has to be paired with another complementary input/output. From 1fccc63c6317e1f6a6e30268b8913da824d285bd Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 7 Oct 2019 12:10:46 +0200 Subject: [PATCH 15/43] Bundle struct --- text/0018-bee-bundle/0018-bee-bundle.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index f15802a2..925d5049 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -145,14 +145,30 @@ bundleValidate(bundle): | return BUNDLE_VALID ``` - - ## Bundle and BundleBuilder +Transactions are final and bundles are essentially arrays of transactions so they are also final. Once a bundle is created and validated, it shouldn't be tempered. For this reason we have `Bundle` type and `BundleBuilder` type. + ### Bundle +A bundle can simply be represented as an array of transactions. As bundles are final, they shouldn't be modifiable outside of the scope of the bundle module. + +```rust +struct Bundle { + transactions: Vec +} +``` + +```rust +impl Bundle { + pub fn transactions(&self) -> &Vec { + &self.transactions + } +} +``` + ### BundleBuilder From bb8f23f2d1f1d23181d33a7762ba4bb18cbd36c6 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 7 Oct 2019 14:12:33 +0200 Subject: [PATCH 16/43] Address Tsvi review --- text/0018-bee-bundle/0018-bee-bundle.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 925d5049..b33199f9 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -10,7 +10,7 @@ This RFC is based on [`transaction-module`](). The smallest communication unit in the IOTA protocol is the transaction. Everything, including payment settlements and/or plain data, is propagated through the IOTA network in transactions. -A transaction is `2673` trytes and the part available to the user is `2187` trytes. This part holds a signature in case of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs more than one transaction to fulfil his operation, for example signatures with security level `2` or `3` don't fit in a single transaction and user-provided data may exceed the allowance so they need to be fragmented across multiple transactions. Moreover, a transaction may not make sense on its own, for example an input/output transaction alone would change the total amount of the ledger so it has to be paired with another complementary input/output. +A transaction is `2673` trytes and the part available to the user is `2187` trytes. This part holds a signature in case of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs more than one transaction to fulfil their operation, for example signatures with security level `2` or `3` don't fit in a single transaction and user-provided data may exceed the allowance so they need to be fragmented across multiple transactions. Moreover, a value transaction doesn't make sense on its own because it would change the total amount of the ledger so it has to be paired with other complementary transactions that together will balance the total value to zero. For these reasons, transactions have to be processed as a whole, in groups called bundles. A bundle is an atomic operation in the sense that either all or none of its transactions are accepted by the network. Even single transactions are propagated through the network within a bundle making it the only confirmable communication unit of the IOTA protocol. @@ -101,7 +101,7 @@ For a bundle to be considered valid, the following assertions must be true: - transactions share the same bundle hash; - transactions absolute value doesn't exceed total IOTA supply; - bundle absolute sum never exceeds total IOTA supply; -- transactions appear in the announced order; +- order of transactions in the bundle is the same as announced by `current_index` and `last_index`; - value transactions have an address ending in `0` i.e. has been generated with Kerl; - bundle inputs and outputs are balanced i.e. the bundle sum equals `0`; - announced bundle hash matches the computed bundle hash; From 00d4aadbc34bce617bf853b7938693e94ce64c24 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 7 Oct 2019 15:40:03 +0200 Subject: [PATCH 17/43] Reverse Structs and Algorithms --- text/0018-bee-bundle/0018-bee-bundle.md | 60 ++++++++++++------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index b33199f9..f318f707 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -30,6 +30,36 @@ Useful links: +## Bundle and BundleBuilder + +Transactions are final and bundles are essentially arrays of transactions so they are also final. Once a bundle is created and validated, it shouldn't be tempered. For this reason we have `Bundle` type and `BundleBuilder` type. + + + +### Bundle + +A bundle can simply be represented as an array of transactions. As bundles are final, they shouldn't be modifiable outside of the scope of the bundle module. + +```rust +struct Bundle { + transactions: Vec +} +``` + +```rust +impl Bundle { + pub fn transactions(&self) -> &Vec { + &self.transactions + } +} +``` + + + +### BundleBuilder + + + ## Algorithms @@ -145,36 +175,6 @@ bundleValidate(bundle): | return BUNDLE_VALID ``` -## Bundle and BundleBuilder - -Transactions are final and bundles are essentially arrays of transactions so they are also final. Once a bundle is created and validated, it shouldn't be tempered. For this reason we have `Bundle` type and `BundleBuilder` type. - - - -### Bundle - -A bundle can simply be represented as an array of transactions. As bundles are final, they shouldn't be modifiable outside of the scope of the bundle module. - -```rust -struct Bundle { - transactions: Vec -} -``` - -```rust -impl Bundle { - pub fn transactions(&self) -> &Vec { - &self.transactions - } -} -``` - - - -### BundleBuilder - - - # Drawbacks From 2f15fc3bc7af996b9494676feb10d9ed534597c9 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 7 Oct 2019 15:55:42 +0200 Subject: [PATCH 18/43] Rework Bundle & BundleBuilder introduction --- text/0018-bee-bundle/0018-bee-bundle.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index f318f707..7582bda5 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -32,9 +32,7 @@ Useful links: ## Bundle and BundleBuilder -Transactions are final and bundles are essentially arrays of transactions so they are also final. Once a bundle is created and validated, it shouldn't be tempered. For this reason we have `Bundle` type and `BundleBuilder` type. - - +Transactions are final and bundles, essentially being arrays of transactions, are also final. Once a bundle is created and validated, it shouldn't be tempered. For this reason we have a `Bundle` type and a `BundleBuilder` type. An instantiated `Bundle` object represents a syntactically and semantically valid IOTA bundle and a `BundleBuilder` is the only gateway to a `Bundle` object. ### Bundle From c8554df9d751345ac0599c652b1910110545e3a5 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 7 Oct 2019 16:10:35 +0200 Subject: [PATCH 19/43] Algorithms introduction --- text/0018-bee-bundle/0018-bee-bundle.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 7582bda5..6ea01f67 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -60,7 +60,9 @@ impl Bundle { ## Algorithms - +In this section, we describe the algorithms needed to build a `Bundle`. The lifecycle of a `BundleBuilder` depends on if it's being used in client side or server side: +- client side: `finalise` -> [`sign` ->] `validate` -> `build` +- server side: `addTransaction`/`addTransactionBuilder` -> `validate` -> `build` ### Bundle hash generation From 4cb1ec49dda734f9cb553f3a8ebf48fcf2be5646 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 7 Oct 2019 16:52:36 +0200 Subject: [PATCH 20/43] Rename operations --- text/0018-bee-bundle/0018-bee-bundle.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 6ea01f67..7ad5c892 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -64,7 +64,7 @@ In this section, we describe the algorithms needed to build a `Bundle`. The life - client side: `finalise` -> [`sign` ->] `validate` -> `build` - server side: `addTransaction`/`addTransactionBuilder` -> `validate` -> `build` -### Bundle hash generation +### Hash *Client side and server side operation.* @@ -86,7 +86,7 @@ The bundle hash is generated with a sponge by iterating through the bundle, from Pseudocode: ``` -bundleHash(bundle) +hash(bundle) | sponge = Sponge(HASH_FUNCTION) | | for transaction in bundle @@ -97,7 +97,7 @@ bundleHash(bundle) *In the current mainnet, the hash function of the sponge used to generate bundle hashes is Kerl.* -### Bundle finalisation +### Finalise *Client side operation.* @@ -106,7 +106,7 @@ Finalising a bundle means computing the bundle hash, verifying that it matches t Pseudocode: ``` -bundleFinalise(bundle) +finalise(bundle) | hash = bundleHash(bundle) | | while hash.normalise().find('M') @@ -119,7 +119,7 @@ bundleFinalise(bundle) *Security requirement: due to the implementation of the signature process, the normalised bundle hash can't contain a `M` or `13` because it could expose a significant part of the private key, weakening the signature. The bundle hash is then repetitively generated with a slight modification until its normalisation doesn't contain a `M`.* -### Bundle validation +### Validate *Server side operation.* @@ -140,7 +140,7 @@ For a bundle to be considered valid, the following assertions must be true: Pseudocode: ``` -bundleValidate(bundle): +validate(bundle): | value = 0 | current_index = 0 | From e2196babdb9f394f3c0aecb1edcde5878af2ce1c Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 7 Oct 2019 18:48:17 +0200 Subject: [PATCH 21/43] Sign pseudocode --- text/0018-bee-bundle/0018-bee-bundle.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 7ad5c892..7bfe6190 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -119,6 +119,28 @@ finalise(bundle) *Security requirement: due to the implementation of the signature process, the normalised bundle hash can't contain a `M` or `13` because it could expose a significant part of the private key, weakening the signature. The bundle hash is then repetitively generated with a slight modification until its normalisation doesn't contain a `M`.* +### Sign + +Pseudocode: + +``` +sign(bundle, seed, inputs) +| current_index = 0 +| +| for transaction in bundle +| | if transaction.value < 0 +| | | if transaction.current_index >= current_index +| | | | input = inputs[transaction.address] +| | | | fragments = sign(seed, input.index, input.security, transaction.bundle) +| | | | for fragment in fragments +| | | | | bundle[current_index].signature = fragment +| | | | | current_index = current_index + 1 +| | else +| | | current_index = current_index + 1 +``` + + + ### Validate *Server side operation.* From 676a5b6f53c0a0ce964631745c9a4c2bc5bb2329 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 7 Oct 2019 20:40:05 +0200 Subject: [PATCH 22/43] Sign paragraph --- text/0018-bee-bundle/0018-bee-bundle.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 7bfe6190..21ce7ccf 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -121,6 +121,10 @@ finalise(bundle) ### Sign +*Client side operation.* + +Signing a bundle allow you to prove that you are the owner of the address you are trying to move funds from. With no signature or a bad signature, the bundle won't be considered valid and the funds won't be moved. Only the owner of the right seed is able to generate the right signature for this address. + Pseudocode: ``` @@ -139,11 +143,11 @@ sign(bundle, seed, inputs) | | | current_index = current_index + 1 ``` - +*Since signature size depends on the security level, a single signature can spread out to up to 3 transactions. `inputs` is an object that contain all unused addresses of a seed with a sufficient balance.* ### Validate -*Server side operation.* +*Client side and server side operation.* Validating a bundle means checking the syntactic and semantic integrity of a bundle as a whole and of its constituent transactions. As bundles are atomic transfers, either all or none of the transactions will be accepted by the network. After validation, transactions of a bundle are candidates to be included to the ledger. From 4a72e334a70970fb2cd569df7e6fa13fb1e3a02e Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 7 Oct 2019 21:03:05 +0200 Subject: [PATCH 23/43] Add pow section --- text/0018-bee-bundle/0018-bee-bundle.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 21ce7ccf..16711e9e 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -61,9 +61,11 @@ impl Bundle { ## Algorithms In this section, we describe the algorithms needed to build a `Bundle`. The lifecycle of a `BundleBuilder` depends on if it's being used in client side or server side: -- client side: `finalise` -> [`sign` ->] `validate` -> `build` +- client side: `finalise` -> [`sign` ->] -> [`pow` ->] -> `validate` -> `build` - server side: `addTransaction`/`addTransactionBuilder` -> `validate` -> `build` +*`sign` is optional because data transactions don't have to be signed. `pow` is optional because one can use remote pow instead.* + ### Hash *Client side and server side operation.* @@ -145,6 +147,12 @@ sign(bundle, seed, inputs) *Since signature size depends on the security level, a single signature can spread out to up to 3 transactions. `inputs` is an object that contain all unused addresses of a seed with a sufficient balance.* +### Pow + +*Client side operation.* + + + ### Validate *Client side and server side operation.* From fe3e7894deb04d97752bd943ab0a224558f252b6 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Tue, 8 Oct 2019 10:17:18 +0200 Subject: [PATCH 24/43] Bundle detail --- text/0018-bee-bundle/0018-bee-bundle.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 16711e9e..e95c7658 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -36,7 +36,9 @@ Transactions are final and bundles, essentially being arrays of transactions, ar ### Bundle -A bundle can simply be represented as an array of transactions. As bundles are final, they shouldn't be modifiable outside of the scope of the bundle module. +As bundles are final, they shouldn't be modifiable outside of the scope of the bundle module. + +A bundle can simply be represented as an array of transactions: ```rust struct Bundle { @@ -44,6 +46,8 @@ struct Bundle { } ``` +And its implementation should only allow to retrieve transactions: + ```rust impl Bundle { pub fn transactions(&self) -> &Vec { @@ -52,8 +56,6 @@ impl Bundle { } ``` - - ### BundleBuilder @@ -139,7 +141,7 @@ sign(bundle, seed, inputs) | | | | input = inputs[transaction.address] | | | | fragments = sign(seed, input.index, input.security, transaction.bundle) | | | | for fragment in fragments -| | | | | bundle[current_index].signature = fragment +| | | | | bundle.at(current_index).signature = fragment | | | | | current_index = current_index + 1 | | else | | | current_index = current_index + 1 @@ -222,3 +224,4 @@ validate(bundle): - Should this RFC expands a bit more on the M-Bug ? Or give a link ? +- Should `Bundle` provide a `.transactions` or a `.at` method ? From 56e17e04bd88c905d61cfa7b6e202775244f02df Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Tue, 8 Oct 2019 10:47:18 +0200 Subject: [PATCH 25/43] BundleBuilder methods --- text/0018-bee-bundle/0018-bee-bundle.md | 38 ++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index e95c7658..e6a12d41 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -58,7 +58,43 @@ impl Bundle { ### BundleBuilder - +The `BundleBuilder` offers a simple and convenient way to build bundles: + +```rust +pub struct BundleBuilder { + transactions: Vec +} +``` + +```rust +impl BundleBuilder { + pub fn hash(&self) { + unimplemented!() + } + + pub fn finalise(&self) { + unimplemented!() + } + + pub fn sign(&self) { + unimplemented!() + } + + pub fn pow(&self) { + unimplemented!() + } + + pub fn validate(&self) { + unimplemented!() + } + + pub fn build(&self) { + unimplemented!() + } +} +``` + +*We do not list parameters and/or return values as they are implementation details.* ## Algorithms From 370be66cc71c5a03efd8cf9bef5da06f040768c1 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Tue, 8 Oct 2019 13:27:45 +0200 Subject: [PATCH 26/43] Rationales & alternatives --- text/0018-bee-bundle/0018-bee-bundle.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index e6a12d41..c3d9a4b3 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -253,11 +253,11 @@ validate(bundle): # Rationale and alternatives - +- A `Bundle` is a fundamental component of the IOTA protocol and must be implemented; +- There is no more intuitive and simple way to implement a `Bundle` than the one proposed; +- Since bundles are final, `BundleBuilder` is mandatory; # Unresolved questions - - - Should this RFC expands a bit more on the M-Bug ? Or give a link ? - Should `Bundle` provide a `.transactions` or a `.at` method ? From c8947b1a2c7bd0f69ad66e4c1f7a449bcfd96883 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Tue, 8 Oct 2019 15:52:42 +0200 Subject: [PATCH 27/43] Pow pseudocode --- text/0018-bee-bundle/0018-bee-bundle.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index c3d9a4b3..6827d0b5 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -189,7 +189,23 @@ sign(bundle, seed, inputs) *Client side operation.* - +Pseudocode: + +``` +pow(bundle, trunk, branch, mwm) +| for transaction in rev(bundle) +| | transaction.trunk = trunk +| | transaction.branch = branch +| | if transaction.current_index == transaction.last_index +| | | branch = trunk +| | transaction.attachment_timestamp = timestamp() +| | transaction.attachment_timestamp_lower = 0 +| | transaction.attachment_timestamp_upper = 3812798742493 +| | if transaction.tag.empty() +| | | transaction.tag = transaction.obsolete_tag +| | trunk = transaction.pow(mwm) + +``` ### Validate From 3ef83e9de21869713d48c46eccbe2afe3cf7c496 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Tue, 8 Oct 2019 16:14:32 +0200 Subject: [PATCH 28/43] Pow introduction --- text/0018-bee-bundle/0018-bee-bundle.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 6827d0b5..47b9b4c0 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -189,6 +189,8 @@ sign(bundle, seed, inputs) *Client side operation.* +Proof of Work (PoW) allows your transactions to be accepted by the network. On the IOTA network, PoW is only a rate control mechanism. Doing PoW on a bundle means doing PoW on each of its transactions and set trunks and branch accordingly. After PoW, a bundle is ready to be sent to the network. + Pseudocode: ``` From 8a0b32290a60c54c40fe2a27370bf16272aae99e Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Tue, 8 Oct 2019 16:18:55 +0200 Subject: [PATCH 29/43] Transaction -> TransactionBuilder --- text/0018-bee-bundle/0018-bee-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 47b9b4c0..dea22336 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -62,7 +62,7 @@ The `BundleBuilder` offers a simple and convenient way to build bundles: ```rust pub struct BundleBuilder { - transactions: Vec + transactions: Vec } ``` From ac9f0bd8b93ff09be96c31a455590590c5ae5a48 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Tue, 8 Oct 2019 16:23:47 +0200 Subject: [PATCH 30/43] Typo --- text/0018-bee-bundle/0018-bee-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index dea22336..ce3b1414 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -189,7 +189,7 @@ sign(bundle, seed, inputs) *Client side operation.* -Proof of Work (PoW) allows your transactions to be accepted by the network. On the IOTA network, PoW is only a rate control mechanism. Doing PoW on a bundle means doing PoW on each of its transactions and set trunks and branch accordingly. After PoW, a bundle is ready to be sent to the network. +Proof of Work (PoW) allows your transactions to be accepted by the network. On the IOTA network, PoW is only a rate control mechanism. Doing PoW on a bundle means doing PoW on each of its transactions and setting trunks and branch accordingly. After PoW, a bundle is ready to be sent to the network. Pseudocode: From d283653bf2148d6dbdc68b80e46d101c327a3961 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Wed, 9 Oct 2019 12:06:01 +0200 Subject: [PATCH 31/43] Remove redundant arrows --- text/0018-bee-bundle/0018-bee-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index ce3b1414..52384808 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -99,7 +99,7 @@ impl BundleBuilder { ## Algorithms In this section, we describe the algorithms needed to build a `Bundle`. The lifecycle of a `BundleBuilder` depends on if it's being used in client side or server side: -- client side: `finalise` -> [`sign` ->] -> [`pow` ->] -> `validate` -> `build` +- client side: `finalise` -> [`sign` ->] [`pow` ->] `validate` -> `build` - server side: `addTransaction`/`addTransactionBuilder` -> `validate` -> `build` *`sign` is optional because data transactions don't have to be signed. `pow` is optional because one can use remote pow instead.* From 8ad72b185b4f048824388097f32b34c468d66321 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Wed, 9 Oct 2019 12:07:11 +0200 Subject: [PATCH 32/43] small_snake_case --- text/0018-bee-bundle/0018-bee-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 52384808..4f87cb43 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -100,7 +100,7 @@ impl BundleBuilder { In this section, we describe the algorithms needed to build a `Bundle`. The lifecycle of a `BundleBuilder` depends on if it's being used in client side or server side: - client side: `finalise` -> [`sign` ->] [`pow` ->] `validate` -> `build` -- server side: `addTransaction`/`addTransactionBuilder` -> `validate` -> `build` +- server side: `add_transaction`/`add_transaction_builder` -> `validate` -> `build` *`sign` is optional because data transactions don't have to be signed. `pow` is optional because one can use remote pow instead.* From 190648bf13629eac1a976850a25fb33a39d7af88 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Wed, 9 Oct 2019 13:05:09 +0200 Subject: [PATCH 33/43] Useful links --- text/0018-bee-bundle/0018-bee-bundle.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 4f87cb43..d9975ede 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -17,10 +17,10 @@ For these reasons, transactions have to be processed as a whole, in groups calle This RFC proposes ways to create and manipulate a bundle and describe the associated algorithms. Useful links: -- [What is a bundle? -](https://docs.iota.org/docs/getting-started/0.1/introduction/what-is-a-bundle) -- [Bundles and transactions -](https://docs.iota.org/docs/dev-essentials/0.1/concepts/bundles-and-transactions) +- [Trinary](https://docs.iota.org/docs/dev-essentials/0.1/concepts/trinary) +- [What is a bundle?](https://docs.iota.org/docs/getting-started/0.1/introduction/what-is-a-bundle) +- [Bundles and transactions](https://docs.iota.org/docs/dev-essentials/0.1/concepts/bundles-and-transactions) +- [Structure of a bundle](https://docs.iota.org/docs/dev-essentials/0.1/references/structure-of-a-bundle) # Motivation From bbd2b6439d8cd12d7789982405db74dc62886044 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Wed, 9 Oct 2019 17:13:03 +0200 Subject: [PATCH 34/43] Break at 120 columns --- text/0018-bee-bundle/0018-bee-bundle.md | 57 ++++++++++++++++++------- 1 file changed, 42 insertions(+), 15 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index d9975ede..5343d999 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -8,11 +8,20 @@ This RFC is based on [`transaction-module`](). -The smallest communication unit in the IOTA protocol is the transaction. Everything, including payment settlements and/or plain data, is propagated through the IOTA network in transactions. +The smallest communication unit in the IOTA protocol is the transaction. Everything, including payment settlements +and/or plain data, is propagated through the IOTA network in transactions. -A transaction is `2673` trytes and the part available to the user is `2187` trytes. This part holds a signature in case of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs more than one transaction to fulfil their operation, for example signatures with security level `2` or `3` don't fit in a single transaction and user-provided data may exceed the allowance so they need to be fragmented across multiple transactions. Moreover, a value transaction doesn't make sense on its own because it would change the total amount of the ledger so it has to be paired with other complementary transactions that together will balance the total value to zero. +A transaction is `2673` trytes and the part available to the user is `2187` trytes. This part holds a signature in case +of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs more than one +transaction to fulfil their operation, for example signatures with security level `2` or `3` don't fit in a single +transaction and user-provided data may exceed the allowance so they need to be fragmented across multiple transactions. +Moreover, a value transaction doesn't make sense on its own because it would change the total amount of the ledger so +it has to be paired with other complementary transactions that together will balance the total value to zero. -For these reasons, transactions have to be processed as a whole, in groups called bundles. A bundle is an atomic operation in the sense that either all or none of its transactions are accepted by the network. Even single transactions are propagated through the network within a bundle making it the only confirmable communication unit of the IOTA protocol. +For these reasons, transactions have to be processed as a whole, in groups called bundles. A bundle is an atomic +operation in the sense that either all or none of its transactions are accepted by the network. Even single +transactions are propagated through the network within a bundle making it the only confirmable communication unit of +the IOTA protocol. This RFC proposes ways to create and manipulate a bundle and describe the associated algorithms. @@ -32,7 +41,10 @@ Useful links: ## Bundle and BundleBuilder -Transactions are final and bundles, essentially being arrays of transactions, are also final. Once a bundle is created and validated, it shouldn't be tempered. For this reason we have a `Bundle` type and a `BundleBuilder` type. An instantiated `Bundle` object represents a syntactically and semantically valid IOTA bundle and a `BundleBuilder` is the only gateway to a `Bundle` object. +Transactions are final and bundles, essentially being arrays of transactions, are also final. Once a bundle is created +and validated, it shouldn't be tempered. For this reason we have a `Bundle` type and a `BundleBuilder` type. +An instantiated `Bundle` object represents a syntactically and semantically valid IOTA bundle and a `BundleBuilder` is +the only gateway to a `Bundle` object. ### Bundle @@ -98,19 +110,23 @@ impl BundleBuilder { ## Algorithms -In this section, we describe the algorithms needed to build a `Bundle`. The lifecycle of a `BundleBuilder` depends on if it's being used in client side or server side: +In this section, we describe the algorithms needed to build a `Bundle`. The lifecycle of a `BundleBuilder` depends on +if it's being used in client side or server side: - client side: `finalise` -> [`sign` ->] [`pow` ->] `validate` -> `build` - server side: `add_transaction`/`add_transaction_builder` -> `validate` -> `build` -*`sign` is optional because data transactions don't have to be signed. `pow` is optional because one can use remote pow instead.* +*`sign` is optional because data transactions don't have to be signed. `pow` is optional because one can use remote +pow instead.* ### Hash *Client side and server side operation.* -A bundle hash ties different transactions together. By having this common hash in their `bundle` field, it makes it clear that these transactions should be processed as a whole. +A bundle hash ties different transactions together. By having this common hash in their `bundle` field, it makes it +clear that these transactions should be processed as a whole. -The hash of a bundle is derived from the bundle essence of each of its transactions. The bundle essence of a transaction is composed of the following fields. +The hash of a bundle is derived from the bundle essence of each of its transactions. The bundle essence of a +transaction is composed of the following fields. | Name | Size | | ------------- | --------- | @@ -121,7 +137,8 @@ The hash of a bundle is derived from the bundle essence of each of its transacti | current_index | 27 trits | | last_index | 27 trits | -The bundle hash is generated with a sponge by iterating through the bundle, from `0` to `last_index`, absorbing the bundle essence of each transaction and eventually squeezing the bundle hash from the sponge. +The bundle hash is generated with a sponge by iterating through the bundle, from `0` to `last_index`, absorbing the +bundle essence of each transaction and eventually squeezing the bundle hash from the sponge. Pseudocode: @@ -141,7 +158,9 @@ hash(bundle) *Client side operation.* -Finalising a bundle means computing the bundle hash, verifying that it matches the security requirement and setting it to all the transactions of the bundle. After finalisation, transactions of a bundle are ready to be safely attached to the tangle. +Finalising a bundle means computing the bundle hash, verifying that it matches the security requirement and setting it +to all the transactions of the bundle. After finalisation, transactions of a bundle are ready to be safely attached to +the tangle. Pseudocode: @@ -157,13 +176,17 @@ finalise(bundle) | | transaction.setBundleHash(hash) ``` -*Security requirement: due to the implementation of the signature process, the normalised bundle hash can't contain a `M` or `13` because it could expose a significant part of the private key, weakening the signature. The bundle hash is then repetitively generated with a slight modification until its normalisation doesn't contain a `M`.* +*Security requirement: due to the implementation of the signature process, the normalised bundle hash can't contain a +`M` or `13` because it could expose a significant part of the private key, weakening the signature. The bundle hash is +then repetitively generated with a slight modification until its normalisation doesn't contain a `M`.* ### Sign *Client side operation.* -Signing a bundle allow you to prove that you are the owner of the address you are trying to move funds from. With no signature or a bad signature, the bundle won't be considered valid and the funds won't be moved. Only the owner of the right seed is able to generate the right signature for this address. +Signing a bundle allow you to prove that you are the owner of the address you are trying to move funds from. With no +signature or a bad signature, the bundle won't be considered valid and the funds won't be moved. Only the owner of the +right seed is able to generate the right signature for this address. Pseudocode: @@ -183,13 +206,16 @@ sign(bundle, seed, inputs) | | | current_index = current_index + 1 ``` -*Since signature size depends on the security level, a single signature can spread out to up to 3 transactions. `inputs` is an object that contain all unused addresses of a seed with a sufficient balance.* +*Since signature size depends on the security level, a single signature can spread out to up to 3 transactions. +`inputs` is an object that contain all unused addresses of a seed with a sufficient balance.* ### Pow *Client side operation.* -Proof of Work (PoW) allows your transactions to be accepted by the network. On the IOTA network, PoW is only a rate control mechanism. Doing PoW on a bundle means doing PoW on each of its transactions and setting trunks and branch accordingly. After PoW, a bundle is ready to be sent to the network. +Proof of Work (PoW) allows your transactions to be accepted by the network. On the IOTA network, PoW is only a rate +control mechanism. Doing PoW on a bundle means doing PoW on each of its transactions and setting trunks and branch +accordingly. After PoW, a bundle is ready to be sent to the network. Pseudocode: @@ -213,7 +239,8 @@ pow(bundle, trunk, branch, mwm) *Client side and server side operation.* -Validating a bundle means checking the syntactic and semantic integrity of a bundle as a whole and of its constituent transactions. As bundles are atomic transfers, either all or none of the transactions will be accepted by the network. After validation, transactions of a bundle are candidates to be included to the ledger. +Validating a bundle means checking the syntactic and semantic integrity of a bundle as a whole and of its constituent transactions. As bundles are atomic transfers, either all or none of the transactions will be accepted by the network. +After validation, transactions of a bundle are candidates to be included to the ledger. For a bundle to be considered valid, the following assertions must be true: From be58b46a0cfbb778c4a4c641dd1fa002342b466c Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 14 Oct 2019 09:37:47 +0200 Subject: [PATCH 35/43] trytes -> trits --- text/0018-bee-bundle/0018-bee-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 5343d999..d67cb271 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -11,7 +11,7 @@ This RFC is based on [`transaction-module`](). The smallest communication unit in the IOTA protocol is the transaction. Everything, including payment settlements and/or plain data, is propagated through the IOTA network in transactions. -A transaction is `2673` trytes and the part available to the user is `2187` trytes. This part holds a signature in case +A transaction is `8019` trits and the part available to the user is `6561` trits. This part holds a signature in case of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs more than one transaction to fulfil their operation, for example signatures with security level `2` or `3` don't fit in a single transaction and user-provided data may exceed the allowance so they need to be fragmented across multiple transactions. From 8a720099826fec7ec53bb50c4e4b73c2bdae8e9c Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 14 Oct 2019 10:20:21 +0200 Subject: [PATCH 36/43] Detail on natural order --- text/0018-bee-bundle/0018-bee-bundle.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index d67cb271..349c9d28 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -50,7 +50,9 @@ the only gateway to a `Bundle` object. As bundles are final, they shouldn't be modifiable outside of the scope of the bundle module. -A bundle can simply be represented as an array of transactions: +Since there is a natural order to transactions in a bundle (each transaction has a `current_index` and a `last_index` +and `current_index` goes from `0` to `last_index`), a bundle can simply be represented by a data structure that keeps +the order intact, like an array: ```rust struct Bundle { @@ -306,3 +308,4 @@ validate(bundle): - Should this RFC expands a bit more on the M-Bug ? Or give a link ? - Should `Bundle` provide a `.transactions` or a `.at` method ? +- The inner structure of a Bundle could be a `HashMap` ? From 6b0a9da898d3c7d8868bb2ae323f082bdb5c099a Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 14 Oct 2019 12:59:55 +0200 Subject: [PATCH 37/43] Hide inner data structure as implementation detail --- text/0018-bee-bundle/0018-bee-bundle.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 349c9d28..9276721a 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -50,13 +50,24 @@ the only gateway to a `Bundle` object. As bundles are final, they shouldn't be modifiable outside of the scope of the bundle module. -Since there is a natural order to transactions in a bundle (each transaction has a `current_index` and a `last_index` -and `current_index` goes from `0` to `last_index`), a bundle can simply be represented by a data structure that keeps -the order intact, like an array: +There is a natural order to transactions in a bundle that can be represented in two ways: +- each transaction has a `current_index` and a `last_index` and `current_index` goes from `0` to `last_index`, a bundle can then simply be represented by a data structure that contiguously keeps the order like `Vec`; +- each transaction is chained to the next one through its `trunk` which means we can consider data structures like +`HashMap` or `BTreeMap`; + +For this reason, we hide this as an implementation detail and instead provide a newtype: + +```rust +struct Transactions(Vec) +//struct Transactions(HashMap) +//struct Transactions(BTreeMap) +``` + +Then the `Bundle` type looks like: ```rust struct Bundle { - transactions: Vec + transactions: Transactions } ``` @@ -64,7 +75,7 @@ And its implementation should only allow to retrieve transactions: ```rust impl Bundle { - pub fn transactions(&self) -> &Vec { + pub fn transactions(&self) -> &Transactions { &self.transactions } } @@ -308,4 +319,3 @@ validate(bundle): - Should this RFC expands a bit more on the M-Bug ? Or give a link ? - Should `Bundle` provide a `.transactions` or a `.at` method ? -- The inner structure of a Bundle could be a `HashMap` ? From b96996ba7043d89a2fed2d02e12a99e08f1fe03e Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 14 Oct 2019 14:02:01 +0200 Subject: [PATCH 38/43] Detail on user available part --- text/0018-bee-bundle/0018-bee-bundle.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 9276721a..a5efe9e4 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -11,12 +11,13 @@ This RFC is based on [`transaction-module`](). The smallest communication unit in the IOTA protocol is the transaction. Everything, including payment settlements and/or plain data, is propagated through the IOTA network in transactions. -A transaction is `8019` trits and the part available to the user is `6561` trits. This part holds a signature in case -of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs more than one -transaction to fulfil their operation, for example signatures with security level `2` or `3` don't fit in a single -transaction and user-provided data may exceed the allowance so they need to be fragmented across multiple transactions. -Moreover, a value transaction doesn't make sense on its own because it would change the total amount of the ledger so -it has to be paired with other complementary transactions that together will balance the total value to zero. +A transaction is `8019` trits and the main part available to the user, `sig_or_msg`, is `6561` trits. This part holds a +signature in case of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs +more than one transaction to fulfil their operation, for example signatures with security level `2` or `3` don't fit in +a single transaction and user-provided data may exceed the allowance so they need to be fragmented across multiple +transactions. Moreover, a value transaction doesn't make sense on its own because it would change the total amount of +the ledger so it has to be paired with other complementary transactions that together will balance the total value to +zero. For these reasons, transactions have to be processed as a whole, in groups called bundles. A bundle is an atomic operation in the sense that either all or none of its transactions are accepted by the network. Even single @@ -51,7 +52,8 @@ the only gateway to a `Bundle` object. As bundles are final, they shouldn't be modifiable outside of the scope of the bundle module. There is a natural order to transactions in a bundle that can be represented in two ways: -- each transaction has a `current_index` and a `last_index` and `current_index` goes from `0` to `last_index`, a bundle can then simply be represented by a data structure that contiguously keeps the order like `Vec`; +- each transaction has a `current_index` and a `last_index` and `current_index` goes from `0` to `last_index`, a bundle +can then simply be represented by a data structure that contiguously keeps the order like `Vec`; - each transaction is chained to the next one through its `trunk` which means we can consider data structures like `HashMap` or `BTreeMap`; @@ -252,7 +254,8 @@ pow(bundle, trunk, branch, mwm) *Client side and server side operation.* -Validating a bundle means checking the syntactic and semantic integrity of a bundle as a whole and of its constituent transactions. As bundles are atomic transfers, either all or none of the transactions will be accepted by the network. +Validating a bundle means checking the syntactic and semantic integrity of a bundle as a whole and of its constituent +transactions. As bundles are atomic transfers, either all or none of the transactions will be accepted by the network. After validation, transactions of a bundle are candidates to be included to the ledger. For a bundle to be considered valid, the following assertions must be true: From 3abe8d55d7ed3ed5df54c11bc7fbc07d050b357c Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 14 Oct 2019 14:02:54 +0200 Subject: [PATCH 39/43] Remove mention to Transaction RFC in prevision of merging --- text/0018-bee-bundle/0018-bee-bundle.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index a5efe9e4..200fa74a 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -5,9 +5,6 @@ # Summary -This RFC is based on [`transaction-module`](). - - The smallest communication unit in the IOTA protocol is the transaction. Everything, including payment settlements and/or plain data, is propagated through the IOTA network in transactions. From 696504454572e97b7df96eb82b12be25314427c2 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 14 Oct 2019 14:06:53 +0200 Subject: [PATCH 40/43] user available part -> payload --- text/0018-bee-bundle/0018-bee-bundle.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 200fa74a..ba1a3f62 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -8,13 +8,12 @@ The smallest communication unit in the IOTA protocol is the transaction. Everything, including payment settlements and/or plain data, is propagated through the IOTA network in transactions. -A transaction is `8019` trits and the main part available to the user, `sig_or_msg`, is `6561` trits. This part holds a -signature in case of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs -more than one transaction to fulfil their operation, for example signatures with security level `2` or `3` don't fit in -a single transaction and user-provided data may exceed the allowance so they need to be fragmented across multiple -transactions. Moreover, a value transaction doesn't make sense on its own because it would change the total amount of -the ledger so it has to be paired with other complementary transactions that together will balance the total value to -zero. +A transaction is `8019` trits and the payload (i.e. `sig_or_msg`) is `6561` trits. This payload holds a signature in +case of a payment settlement and plain data otherwise. Since it has a limited size, a user often needs more than one +transaction to fulfil their operation, for example signatures with security level `2` or `3` don't fit in a single +transaction and user-provided data may exceed the allowance so they need to be fragmented across multiple transactions. +Moreover, a value transaction doesn't make sense on its own because it would change the total amount of the ledger so +it has to be paired with other complementary transactions that together will balance the total value to zero. For these reasons, transactions have to be processed as a whole, in groups called bundles. A bundle is an atomic operation in the sense that either all or none of its transactions are accepted by the network. Even single From 52283bad61b36f76164826876511c98b76c90130 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 14 Oct 2019 14:20:21 +0200 Subject: [PATCH 41/43] Rempve mention to current mainnet --- text/0018-bee-bundle/0018-bee-bundle.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index ba1a3f62..c9d6ebb0 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -155,7 +155,7 @@ Pseudocode: ``` hash(bundle) -| sponge = Sponge(HASH_FUNCTION) +| sponge = Sponge(Kerl) | | for transaction in bundle | | sponge.absorb(transaction.essence()) @@ -163,8 +163,6 @@ hash(bundle) | return sponge.squeeze() ``` -*In the current mainnet, the hash function of the sponge used to generate bundle hashes is Kerl.* - ### Finalise *Client side operation.* From 35cff9cdb9c88125648fccad0c172faaa6754d89 Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 14 Oct 2019 14:33:05 +0200 Subject: [PATCH 42/43] Bundle essence as a subset --- text/0018-bee-bundle/0018-bee-bundle.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index c9d6ebb0..24acdc56 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -136,8 +136,8 @@ pow instead.* A bundle hash ties different transactions together. By having this common hash in their `bundle` field, it makes it clear that these transactions should be processed as a whole. -The hash of a bundle is derived from the bundle essence of each of its transactions. The bundle essence of a -transaction is composed of the following fields. +The hash of a bundle is derived from the bundle essence of each of its transactions. A bundle essence is a `486` trits +subset of the transaction fields. | Name | Size | | ------------- | --------- | From f70a11d2c13d3b5d50ded4f66f693059a00b649b Mon Sep 17 00:00:00 2001 From: Thibault Martinez Date: Mon, 14 Oct 2019 15:12:53 +0200 Subject: [PATCH 43/43] Rename functions --- text/0018-bee-bundle/0018-bee-bundle.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/text/0018-bee-bundle/0018-bee-bundle.md b/text/0018-bee-bundle/0018-bee-bundle.md index 24acdc56..3511b86b 100644 --- a/text/0018-bee-bundle/0018-bee-bundle.md +++ b/text/0018-bee-bundle/0018-bee-bundle.md @@ -91,7 +91,7 @@ pub struct BundleBuilder { ```rust impl BundleBuilder { - pub fn hash(&self) { + pub fn calculate_hash(&self) { unimplemented!() } @@ -103,7 +103,7 @@ impl BundleBuilder { unimplemented!() } - pub fn pow(&self) { + pub fn calculate_proof_of_work(&self) { unimplemented!() } @@ -154,7 +154,7 @@ bundle essence of each transaction and eventually squeezing the bundle hash from Pseudocode: ``` -hash(bundle) +calculate_hash(bundle) | sponge = Sponge(Kerl) | | for transaction in bundle @@ -218,7 +218,7 @@ sign(bundle, seed, inputs) *Since signature size depends on the security level, a single signature can spread out to up to 3 transactions. `inputs` is an object that contain all unused addresses of a seed with a sufficient balance.* -### Pow +### Proof of Work *Client side operation.* @@ -229,7 +229,7 @@ accordingly. After PoW, a bundle is ready to be sent to the network. Pseudocode: ``` -pow(bundle, trunk, branch, mwm) +calculate_proof_of_work(bundle, trunk, branch, mwm) | for transaction in rev(bundle) | | transaction.trunk = trunk | | transaction.branch = branch