From 1086975c8f919dde3ca02cc1808d4c7decf6bd02 Mon Sep 17 00:00:00 2001 From: marekyggdrasil Date: Sun, 21 Aug 2022 12:24:31 +0200 Subject: [PATCH 1/9] Documented the block body for the GRIN wiki website --- docs/wiki/blocks/block-body.md | 70 ++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/wiki/blocks/block-body.md b/docs/wiki/blocks/block-body.md index e69de29b..f932896f 100644 --- a/docs/wiki/blocks/block-body.md +++ b/docs/wiki/blocks/block-body.md @@ -0,0 +1,70 @@ +# Block Body + +General format of a **Block Body** in a Mimblewimble/Grin is basically a Mimblewimble transaction which consists of a list of **Inputs**, **Outputs** and **Kernels**. + +| Field | Description | Size | +|:--------------|:----------------------|:---------------------| +| # inputs | Number of inputs | 8 bytes | +| # outputs | Number of outputs | 8 bytes | +| # kernels | Number of kernels | 8 bytes | +| inputs | Serialized inputs | 34 bytes per input | +| outputs | Serialized outputs | 42 bytes per output | +| kernels | Serialized kernels | x bytes per kernel | + +The kernel size **x** depends on the kernel type. More details in its dedicated section below. + +## Inputs + +Each of the inputs consists of **Feature** and a **Commitment**. + +| Field | Description | Size | +|:--------------|:----------------------------------------|:--------------------| +| Feature | **Plain** (0x00) or **Coinbase** (0x01) | 1 byte | +| Commitment | Pedersen commitment | 33 bytes | + +## Outputs + +Just as in case of the inputs, the outputs consist of **Feature** and a **Commitment** but in addition they also hold **Range proofs** + +| Field | Description | Size | +|:--------------|:----------------------------------------|:--------------------| +| Feature | **Plain** (0x00) or **Coinbase** (0x01) | 1 byte | +| Commitment | Pedersen commitment | 33 bytes | +| Range proof | Proves the transaction is net positive | 8 bytes | + +## Kernels + +Every kernel starts with **Kernel feature** which indicates how it should be deserialized. In each variant, the kernel concludes with an **Excess commitment** and a **Excess signature**. What differs them is what is in the middle. We will describe each variant separately + +### Coinbase kernel + +The most basic kernel that does not contain **Fee** nor **Lock height**. + +| Field | Description | Size | +|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| +| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | +| Excess commitment | Pedersen commitment | 33 bytes | +| Excess signature | Schnorr signature | 64 bytes | + +### Plain kernel + +A kernel resulting from a transaction, unlike **Coinbase** kernel it also includes **Fee** billed for the transaction. + +| Field | Description | Size | +|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| +| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | +| Fee | Transaction fee | 8 bytes | +| Excess commitment | Pedersen commitment | 33 bytes | +| Excess signature | Schnorr signature | 64 bytes | + +### Height locked / no recent duplicate / V1 protocol kernel + +The first protocol **kernel** would always consist of **Feature**, **Fee**, **Lock height** and standard **Excess commitment** and **Signature**. Once V2 protocol was introduced this kind of kernel becamse **Height locked** kernel or **No recent duplicate** kernel. + +| Field | Description | Size | +|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| +| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | +| Fee | Transaction fee | 8 bytes | +| Lock height | Block height starting from which the kernel becomes valid | 8 bytes | +| Excess commitment | Pedersen commitment | 33 bytes | +| Excess signature | Schnorr signature | 64 bytes | From 8da2005615c548276a545488f75c1cc837ffa1c5 Mon Sep 17 00:00:00 2001 From: marekyggdrasil Date: Sun, 21 Aug 2022 15:08:50 +0200 Subject: [PATCH 2/9] Range proofs are of a variable size --- docs/wiki/blocks/block-body.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/wiki/blocks/block-body.md b/docs/wiki/blocks/block-body.md index f932896f..08063a4f 100644 --- a/docs/wiki/blocks/block-body.md +++ b/docs/wiki/blocks/block-body.md @@ -26,11 +26,14 @@ Each of the inputs consists of **Feature** and a **Commitment**. Just as in case of the inputs, the outputs consist of **Feature** and a **Commitment** but in addition they also hold **Range proofs** -| Field | Description | Size | -|:--------------|:----------------------------------------|:--------------------| -| Feature | **Plain** (0x00) or **Coinbase** (0x01) | 1 byte | -| Commitment | Pedersen commitment | 33 bytes | -| Range proof | Proves the transaction is net positive | 8 bytes | +| Field | Description | Size | +|:-----------------------|:----------------------------------------|:--------------------| +| Feature | **Plain** (0x00) or **Coinbase** (0x01) | 1 byte | +| Commitment | Pedersen commitment | 33 bytes | +| Range proof size **x** | Proves the transaction is net positive | 8 bytes | +| Range proof | Proves the transaction is net positive | **x** bytes | + +Note that the **range proof** is of a variable size which is indicated by its first 8 bytes. ## Kernels From 4f2f29c69947f285ee224b0d8a0630dcabbf025a Mon Sep 17 00:00:00 2001 From: marekyggdrasil Date: Sun, 21 Aug 2022 15:12:59 +0200 Subject: [PATCH 3/9] Splitting height locked kernels and NRD kernel descriptions --- docs/wiki/blocks/block-body.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/wiki/blocks/block-body.md b/docs/wiki/blocks/block-body.md index 08063a4f..e879e6f9 100644 --- a/docs/wiki/blocks/block-body.md +++ b/docs/wiki/blocks/block-body.md @@ -60,9 +60,21 @@ A kernel resulting from a transaction, unlike **Coinbase** kernel it also includ | Excess commitment | Pedersen commitment | 33 bytes | | Excess signature | Schnorr signature | 64 bytes | -### Height locked / no recent duplicate / V1 protocol kernel +### Height locked kernels -The first protocol **kernel** would always consist of **Feature**, **Fee**, **Lock height** and standard **Excess commitment** and **Signature**. Once V2 protocol was introduced this kind of kernel becamse **Height locked** kernel or **No recent duplicate** kernel. +The first protocol **kernel** would always consist of **Feature**, **Fee**, **Lock height** and standard **Excess commitment** and **Signature**. Starting from the V2 protocol a specific type of kernel - **height locked** kernel supports the **lock height**. + +| Field | Description | Size | +|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| +| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | +| Fee | Transaction fee | 8 bytes | +| Lock height | Block height starting from which the kernel becomes valid | 8 bytes | +| Excess commitment | Pedersen commitment | 33 bytes | +| Excess signature | Schnorr signature | 64 bytes | + +### NRD (No Recent Duplicate) kernels + +( need help describing ) | Field | Description | Size | |:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| From a8f5354f01228e046e9dd613166e0b7d2a743d91 Mon Sep 17 00:00:00 2001 From: marekyggdrasil Date: Sun, 21 Aug 2022 15:14:32 +0200 Subject: [PATCH 4/9] Block body is Transaction body --- docs/wiki/blocks/block-body.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/wiki/blocks/block-body.md b/docs/wiki/blocks/block-body.md index e879e6f9..fd352b68 100644 --- a/docs/wiki/blocks/block-body.md +++ b/docs/wiki/blocks/block-body.md @@ -1,6 +1,6 @@ -# Block Body +# Transaction Body -General format of a **Block Body** in a Mimblewimble/Grin is basically a Mimblewimble transaction which consists of a list of **Inputs**, **Outputs** and **Kernels**. +General format of a **Transaction Body** in a Mimblewimble/Grin is basically a Mimblewimble transaction which consists of a list of **Inputs**, **Outputs** and **Kernels**. | Field | Description | Size | |:--------------|:----------------------|:---------------------| From 26cf56b5ffab650474ea55234ba95b8bf3dbffa2 Mon Sep 17 00:00:00 2001 From: marekyggdrasil Date: Wed, 24 Aug 2022 15:09:39 +0200 Subject: [PATCH 5/9] Briefly explained the NRD kernels --- docs/wiki/blocks/block-body.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki/blocks/block-body.md b/docs/wiki/blocks/block-body.md index fd352b68..8a41cca3 100644 --- a/docs/wiki/blocks/block-body.md +++ b/docs/wiki/blocks/block-body.md @@ -74,7 +74,7 @@ The first protocol **kernel** would always consist of **Feature**, **Fee**, **Lo ### NRD (No Recent Duplicate) kernels -( need help describing ) +When transaction is representing a creation of a payment channel it is relevant to ensure that one of the parties cannot update own kernel associated to own output in the transaction. The NRD kernels are created simultaneously and correlated preventing such an attack. More details in the [mailing list archive](https://lists.launchpad.net/mimblewimble/msg00636.html). | Field | Description | Size | |:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| From 29a10ddb1c1f6738b1e29810b8ca6d3d578e5bae Mon Sep 17 00:00:00 2001 From: marekyggdrasil Date: Wed, 24 Aug 2022 15:14:24 +0200 Subject: [PATCH 6/9] Explained that block body is just a transaction body --- docs/wiki/blocks/block-body.md | 86 +--------------------- docs/wiki/transactions/transaction-body.md | 85 +++++++++++++++++++++ 2 files changed, 87 insertions(+), 84 deletions(-) create mode 100644 docs/wiki/transactions/transaction-body.md diff --git a/docs/wiki/blocks/block-body.md b/docs/wiki/blocks/block-body.md index 8a41cca3..a4e6955e 100644 --- a/docs/wiki/blocks/block-body.md +++ b/docs/wiki/blocks/block-body.md @@ -1,85 +1,3 @@ -# Transaction Body +# Block Body -General format of a **Transaction Body** in a Mimblewimble/Grin is basically a Mimblewimble transaction which consists of a list of **Inputs**, **Outputs** and **Kernels**. - -| Field | Description | Size | -|:--------------|:----------------------|:---------------------| -| # inputs | Number of inputs | 8 bytes | -| # outputs | Number of outputs | 8 bytes | -| # kernels | Number of kernels | 8 bytes | -| inputs | Serialized inputs | 34 bytes per input | -| outputs | Serialized outputs | 42 bytes per output | -| kernels | Serialized kernels | x bytes per kernel | - -The kernel size **x** depends on the kernel type. More details in its dedicated section below. - -## Inputs - -Each of the inputs consists of **Feature** and a **Commitment**. - -| Field | Description | Size | -|:--------------|:----------------------------------------|:--------------------| -| Feature | **Plain** (0x00) or **Coinbase** (0x01) | 1 byte | -| Commitment | Pedersen commitment | 33 bytes | - -## Outputs - -Just as in case of the inputs, the outputs consist of **Feature** and a **Commitment** but in addition they also hold **Range proofs** - -| Field | Description | Size | -|:-----------------------|:----------------------------------------|:--------------------| -| Feature | **Plain** (0x00) or **Coinbase** (0x01) | 1 byte | -| Commitment | Pedersen commitment | 33 bytes | -| Range proof size **x** | Proves the transaction is net positive | 8 bytes | -| Range proof | Proves the transaction is net positive | **x** bytes | - -Note that the **range proof** is of a variable size which is indicated by its first 8 bytes. - -## Kernels - -Every kernel starts with **Kernel feature** which indicates how it should be deserialized. In each variant, the kernel concludes with an **Excess commitment** and a **Excess signature**. What differs them is what is in the middle. We will describe each variant separately - -### Coinbase kernel - -The most basic kernel that does not contain **Fee** nor **Lock height**. - -| Field | Description | Size | -|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| -| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | -| Excess commitment | Pedersen commitment | 33 bytes | -| Excess signature | Schnorr signature | 64 bytes | - -### Plain kernel - -A kernel resulting from a transaction, unlike **Coinbase** kernel it also includes **Fee** billed for the transaction. - -| Field | Description | Size | -|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| -| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | -| Fee | Transaction fee | 8 bytes | -| Excess commitment | Pedersen commitment | 33 bytes | -| Excess signature | Schnorr signature | 64 bytes | - -### Height locked kernels - -The first protocol **kernel** would always consist of **Feature**, **Fee**, **Lock height** and standard **Excess commitment** and **Signature**. Starting from the V2 protocol a specific type of kernel - **height locked** kernel supports the **lock height**. - -| Field | Description | Size | -|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| -| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | -| Fee | Transaction fee | 8 bytes | -| Lock height | Block height starting from which the kernel becomes valid | 8 bytes | -| Excess commitment | Pedersen commitment | 33 bytes | -| Excess signature | Schnorr signature | 64 bytes | - -### NRD (No Recent Duplicate) kernels - -When transaction is representing a creation of a payment channel it is relevant to ensure that one of the parties cannot update own kernel associated to own output in the transaction. The NRD kernels are created simultaneously and correlated preventing such an attack. More details in the [mailing list archive](https://lists.launchpad.net/mimblewimble/msg00636.html). - -| Field | Description | Size | -|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| -| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | -| Fee | Transaction fee | 8 bytes | -| Lock height | Block height starting from which the kernel becomes valid | 8 bytes | -| Excess commitment | Pedersen commitment | 33 bytes | -| Excess signature | Schnorr signature | 64 bytes | +The block body contains transactions. They are aggregated into one single transaction and follow the description of a [transaction body](../transactions/transaction-body.md). diff --git a/docs/wiki/transactions/transaction-body.md b/docs/wiki/transactions/transaction-body.md new file mode 100644 index 00000000..8a41cca3 --- /dev/null +++ b/docs/wiki/transactions/transaction-body.md @@ -0,0 +1,85 @@ +# Transaction Body + +General format of a **Transaction Body** in a Mimblewimble/Grin is basically a Mimblewimble transaction which consists of a list of **Inputs**, **Outputs** and **Kernels**. + +| Field | Description | Size | +|:--------------|:----------------------|:---------------------| +| # inputs | Number of inputs | 8 bytes | +| # outputs | Number of outputs | 8 bytes | +| # kernels | Number of kernels | 8 bytes | +| inputs | Serialized inputs | 34 bytes per input | +| outputs | Serialized outputs | 42 bytes per output | +| kernels | Serialized kernels | x bytes per kernel | + +The kernel size **x** depends on the kernel type. More details in its dedicated section below. + +## Inputs + +Each of the inputs consists of **Feature** and a **Commitment**. + +| Field | Description | Size | +|:--------------|:----------------------------------------|:--------------------| +| Feature | **Plain** (0x00) or **Coinbase** (0x01) | 1 byte | +| Commitment | Pedersen commitment | 33 bytes | + +## Outputs + +Just as in case of the inputs, the outputs consist of **Feature** and a **Commitment** but in addition they also hold **Range proofs** + +| Field | Description | Size | +|:-----------------------|:----------------------------------------|:--------------------| +| Feature | **Plain** (0x00) or **Coinbase** (0x01) | 1 byte | +| Commitment | Pedersen commitment | 33 bytes | +| Range proof size **x** | Proves the transaction is net positive | 8 bytes | +| Range proof | Proves the transaction is net positive | **x** bytes | + +Note that the **range proof** is of a variable size which is indicated by its first 8 bytes. + +## Kernels + +Every kernel starts with **Kernel feature** which indicates how it should be deserialized. In each variant, the kernel concludes with an **Excess commitment** and a **Excess signature**. What differs them is what is in the middle. We will describe each variant separately + +### Coinbase kernel + +The most basic kernel that does not contain **Fee** nor **Lock height**. + +| Field | Description | Size | +|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| +| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | +| Excess commitment | Pedersen commitment | 33 bytes | +| Excess signature | Schnorr signature | 64 bytes | + +### Plain kernel + +A kernel resulting from a transaction, unlike **Coinbase** kernel it also includes **Fee** billed for the transaction. + +| Field | Description | Size | +|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| +| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | +| Fee | Transaction fee | 8 bytes | +| Excess commitment | Pedersen commitment | 33 bytes | +| Excess signature | Schnorr signature | 64 bytes | + +### Height locked kernels + +The first protocol **kernel** would always consist of **Feature**, **Fee**, **Lock height** and standard **Excess commitment** and **Signature**. Starting from the V2 protocol a specific type of kernel - **height locked** kernel supports the **lock height**. + +| Field | Description | Size | +|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| +| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | +| Fee | Transaction fee | 8 bytes | +| Lock height | Block height starting from which the kernel becomes valid | 8 bytes | +| Excess commitment | Pedersen commitment | 33 bytes | +| Excess signature | Schnorr signature | 64 bytes | + +### NRD (No Recent Duplicate) kernels + +When transaction is representing a creation of a payment channel it is relevant to ensure that one of the parties cannot update own kernel associated to own output in the transaction. The NRD kernels are created simultaneously and correlated preventing such an attack. More details in the [mailing list archive](https://lists.launchpad.net/mimblewimble/msg00636.html). + +| Field | Description | Size | +|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| +| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | +| Fee | Transaction fee | 8 bytes | +| Lock height | Block height starting from which the kernel becomes valid | 8 bytes | +| Excess commitment | Pedersen commitment | 33 bytes | +| Excess signature | Schnorr signature | 64 bytes | From 8aa233b5eec5e342355919c1439b8c20c3b2e450 Mon Sep 17 00:00:00 2001 From: marekyggdrasil Date: Thu, 25 Aug 2022 16:42:15 +0200 Subject: [PATCH 7/9] Explained the coinbase kernel --- docs/wiki/transactions/transaction-body.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki/transactions/transaction-body.md b/docs/wiki/transactions/transaction-body.md index 8a41cca3..aa0ff8cc 100644 --- a/docs/wiki/transactions/transaction-body.md +++ b/docs/wiki/transactions/transaction-body.md @@ -41,7 +41,7 @@ Every kernel starts with **Kernel feature** which indicates how it should be des ### Coinbase kernel -The most basic kernel that does not contain **Fee** nor **Lock height**. +This kernel is used for coinbase outputs that collect both the fixed block subsidy of 60 Grin and all the transaction fees in the block. | Field | Description | Size | |:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| From aa76270c2813fc28619fd488206f5c527be51f16 Mon Sep 17 00:00:00 2001 From: marekyggdrasil Date: Thu, 25 Aug 2022 16:46:07 +0200 Subject: [PATCH 8/9] Another iteration of the NRD kernel description --- docs/wiki/transactions/transaction-body.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki/transactions/transaction-body.md b/docs/wiki/transactions/transaction-body.md index aa0ff8cc..678342e7 100644 --- a/docs/wiki/transactions/transaction-body.md +++ b/docs/wiki/transactions/transaction-body.md @@ -74,7 +74,7 @@ The first protocol **kernel** would always consist of **Feature**, **Fee**, **Lo ### NRD (No Recent Duplicate) kernels -When transaction is representing a creation of a payment channel it is relevant to ensure that one of the parties cannot update own kernel associated to own output in the transaction. The NRD kernels are created simultaneously and correlated preventing such an attack. More details in the [mailing list archive](https://lists.launchpad.net/mimblewimble/msg00636.html). +An NRD kernel is only valid in the absence of an identical instance existing within the last relative-height blocks. More information is available in the [NRD kernel RFC](../../grin-rfcs/text/0013-nrd-kernels.md) as well as in the [mailing list archive](https://lists.launchpad.net/mimblewimble/msg00636.html). | Field | Description | Size | |:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| From 210e8862a07fdbdae29b83e06bb294208216bd23 Mon Sep 17 00:00:00 2001 From: marekyggdrasil Date: Thu, 25 Aug 2022 16:49:56 +0200 Subject: [PATCH 9/9] Time locks in NRD kernels are relative --- docs/wiki/transactions/transaction-body.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/wiki/transactions/transaction-body.md b/docs/wiki/transactions/transaction-body.md index 678342e7..7176c222 100644 --- a/docs/wiki/transactions/transaction-body.md +++ b/docs/wiki/transactions/transaction-body.md @@ -76,10 +76,10 @@ The first protocol **kernel** would always consist of **Feature**, **Fee**, **Lo An NRD kernel is only valid in the absence of an identical instance existing within the last relative-height blocks. More information is available in the [NRD kernel RFC](../../grin-rfcs/text/0013-nrd-kernels.md) as well as in the [mailing list archive](https://lists.launchpad.net/mimblewimble/msg00636.html). -| Field | Description | Size | -|:------------------|:--------------------------------------------------------------------------------------------------|:--------------------| -| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | -| Fee | Transaction fee | 8 bytes | -| Lock height | Block height starting from which the kernel becomes valid | 8 bytes | -| Excess commitment | Pedersen commitment | 33 bytes | -| Excess signature | Schnorr signature | 64 bytes | +| Field | Description | Size | +|:---------------------|:--------------------------------------------------------------------------------------------------|:--------------------| +| Feature | **Plain** (0x00), **Coinbase** (0x01), **Height Locked** (0x02) or **No recent duplicate** (0x03) | 1 byte | +| Fee | Transaction fee | 8 bytes | +| Relative lock height | Number of most recent blocks in which the same NRD must be absent | 8 bytes | +| Excess commitment | Pedersen commitment | 33 bytes | +| Excess signature | Schnorr signature | 64 bytes |