Cryptography designs

design/cryptography.md

@@ -0,0 +1,33 @@
+# Cryptography Design
+
+## Scope
+
+Following the Cryptography section of the Obscuro blockchain whitepaper this document describes the design around cryptography in Obscuro.
+
+The Cryptography area has been broken down into sections for interative implementation.
+
+## Areas
+
+* Rollup Encryption design
+* Key Derivation design
+* Data Revelation design
+
+## Rollup Encryption
+
+The rollups in Obscuro have an encrypted design.
+The encryption and decryption rollup approach is described in the [Rollup Encryption](rollup_encryption.md) document.
+
+## Key Derivation 
+
+In order to avoid reusing the same key for all encryption, keys are deterministically derived from the Master Seed.
+The derivation of new keys given a master seed is described in the [Key Derivation](key_derivation.md) document.
+
+## Transaction Revelation Period
+
+Transactions are able to specify the different revelation period desired, while being EVM compatible.
+The transaction changes that specify the revelation period are described in the [Transaction Revelation Period](transaction_revelation_period.md) document.
+
+## Data Revelation Mechanism
+
+Generating different Encryption Keys and associating them with different time lengths allows to create multiple Data Revelation Periods.
+The data revelation mechanism is described in the [Data Revelation](data_revelation.md) document.

design/data_revelation.md

@@ -0,0 +1,33 @@
+# Data Revelation
+
+## Scope
+
+The data revelation ensures that Obscuro transactions encrypted with different keys, can be revealed independently at the right time.
+
+The mechanism needs a reliable way to measure the time that cannot be easily attacked.
+
+## Requirements
+* Keys must be released only after X amount of time has passed
+* Clock mechanism must determine how much time has passed
+
+## Design
+
+### Keys must be released only after X amount of time has passed
+
+A database stores the rollup, decrypt time, key tuple.
+When a new block arrives the enclave stores the current time and all keys before that time are now available.
+Validators fetch the key from the enclave and store the keys locally for redundancy.
+
+### Clock mechanism must determine how much time has passed
+
+Given the predictable block creation rate the Revelation Mechanism Clock is based on the number of blocks that have been issued.
+
+In ethereum blocks have a rate of ~12seconds. This is the standard tick of the revelation clock.
+
+## Attacks
+
+### Time fast-forward
+
+This attack is described as someone fast forwarding the clock and having access to the revelation key before the time it would be expected.
+The attack is mitigated because the keys are never released from the validators.
+

design/key_derivation.md

@@ -0,0 +1,82 @@
+# Key Derivation design
+
+## Scope
+
+The Obscuro blockchain has a master seed that is at the heart of the chain's encryption.
+This master seed is shared between enclaves upon successful attestation.
+Keys are derived from the master seed, that read/write to the transaction in the blockchain.
+
+As per defined in the whitepaper, the key used per rollup will actually be multiple keys (one for each revelation period). However, that was de-scoped in this document.
+
+
+## Requirements
+
+* The same unique key is deterministically generated from the same inputs
+  * Each unique key is derived from the master seed
+  * Each unique key is not able to disclose other unique keys
+  * Each unique key is not able to disclose the master seed
+* Each enclave is able to determine the unique key given the enclave master seed and rollup height
+
+## Design
+
+KDF's or Key Derivation Functions are functions or schemes to derive key or output keying material (OKM) from other secret information, the input keying material (IKM). That information may be another key or, for instance a password. It is important that the secret contains enough randomness to generate keys, without an attacker to be able to perform attacks using information about the input.
+
+There are basically two families of KDFs. PBKDF's such as PBKDF1, PBKDF2, bcrypt, scrypt, Argon2 take passwords that need to be strengthened as input keying material and then perform strengthening. KBKDF's - Key Based Key Derivation Functions - take key material that already contains enough entropy as input.
+
+
+The base construction of a KDF is:
+
+- input:
+
+  a binary encoded secret or key;  
+  other information to derive a specific key (optional);
+  output size (if configurable).
+
+
+- output:
+
+  a derived key or derived keying material.
+
+Furthermore, there are many parameters possible:
+
+  - a salt;
+
+  - work factor (for PBKDF's);
+
+  - memory usage (for PBKDF's);
+
+  - parallelism (for PBKDF's).
+
+
+### Comparison
+
+#### PBKDF Family
+- Variable cost algorithm (given the params might cost more or less to compute, specially iterations)
+- Typically used for deriving a cryptographic key from a password.
+- Specially focused on Key-stretching or password-stretching used protecting (as best it can) the low entropy source material.
+
+Pros:
+ - Adds entropy to weak keys (Key-stretching)
+ - Allows a configurable set of interations to protect from brute-force attacks
+
+Cons:
+  - If the key already has sufficient entropy then it's slow
+  - Resource hungry
+
+#### HKDF Family
+- Fixed cost algorithm (no iterations)
+- Typically used for deriving a cryptographic key from a strong key.
+
+Pros:
+- Fast
+- Not resource intensive
+
+Cons:
+- Does not do Key-stretching
+
+
+## Decision
+
+Use HKDF standardized in https://www.rfc-editor.org/rfc/rfc5869.
+
+Use rollup height ( or some other shared field ) in the Info component of HKDF and use a fixed size salt as per https://soatok.blog/2021/11/17/understanding-hkdf/

design/rollup_encryption.md

@@ -0,0 +1,62 @@
+# Rollup Encryption Design
+
+## Scope
+
+The rollup is a public available object that's written as a bytecode in the Layer 1 chain.
+Obscuro blockchain is a chain of rollups that represent the state changes.
+Given the private nature of Obscuro, the rollups must be confidential.
+The confidentiality model is described in this section.
+
+
+## Confidentiality Model
+
+The rollups are composed of public and private segments.
+Public segments are metadata related information, not covered in this document.
+Private segments are the state changes, namely the transactions.
+These transactions are encrypted.
+
+
+## Encryption Algorithm
+
+Each transaction payload will be encrypted with a specific cypher which will take as one of the inputs the derived key.
+
+AES-256 is the industry standard. It's based on a design principle known as a Substitution permutation network. It is fast in both software and hardware.
+
+### AES Cypher mode
+
+There are many cypher mode that AES can operate on.
+
+#### Modes that require padding (block encryption modes: ECB, CBC)
+Padding can generally be dangerous because it opens up the possibility of padding oracle attacks
+
+
+#### Stream cipher modes (CTR, OFB, CFB's)
+These modes generate a pseudo random stream of data that may or may not depend on the plaintext.
+Similarly to stream ciphers generally, the generated pseudo random stream is XORed with the plaintext to generate the ciphertext.
+As you can use as many bits of the random stream as you like you don't need padding at all.
+
+#### Authenticated encryption (CCM, OCB, GCM)
+To prevent padding oracle attacks and changes to the ciphertext, one can compute a message authentication code (MAC) on the ciphertext and only decrypt it if it has not been tampered with. This is called encrypt-then-mac.
+
+
+#### Conclusion
+
+While there is *a lot* of literature around the different types of cypher mode and its implementation, the clear winner is GCM.
+
+AES-GCM provides the following features:
+- Stream cypher ( no padding attacks )
+- Authentication based (if Message Authentication Code is tampered then decryption the remaining ciphertext is avoided)
+- Faster than CCM and free to use when compared with OCB
+- Intel has implemented special instructions that speed up the underlying GHASH calculation
+
+
+### Other symmetric encryption algorithms
+
+Other symmetric algorithms exist like XChaCha20, but they lack the battle tested scrutiny that AES-256 as been submitted to.
+
+Nonetheless, the implementation of the encryption algorithm should be interfaced in such a way that swapping algorithms is easy.
+This will allow testing different algorithms behaviour and performance in-loco.
+
+## Decision
+
+Use AES-256-GCM to encrypt and decrypt the transaction payload.

design/transaction_revelation_period.md

@@ -0,0 +1,96 @@
+# Transaction Revelation Period
+
+## Scope
+
+The data revelation feature ensures that Obscuro transactions are revealed after a certain period of time.
+The transaction must be backwards compatible with EVM transactions and at the same time they must be able to indicate the revelation period.
+
+For simplicity of design 1 block is the clock tick, and 1 block equals 12 seconds in real world time.
+
+
+## Requirements
+* Transactions must be backwards compatible with the EVM
+  * Transactions must follow the same signature process
+  * Transactions must be seamlessly created by existing web3 frameworks
+* Transactions must specify the revelation period
+* There are 5 revelation periods
+  * XS - 12 seconds (1 block)
+  * S - 1 hour (3600/12 = 300 blocks)
+  * M - 1 day (24 * 3600/12 = 7200 blocks)
+  * L - 1 month (30 * 24 * 3600/12 = 216000 blocks)
+  * XL - 1 year (12 * 30 * 24 * 3600/12 = 2592000 blocks)
+
+## Design
+
+### Transactions must be backwards compatible with the EVM
+
+Transactions are encrypted per default. 
+Using any type of transaction will encrypt the transaction for a default period of 1 block (XS).
+This will guarantee that the use of regular EVM compatible frameworks is assured.
+
+### Transactions must specify the revelation period
+
+Since [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) ethereum supports custom type transactions.
+This EIP allows to specify custom transactions to be supported by the ethereum protocol.
+
+Obscuro heavily relies on Geth to handle the ethereum protocol and EVM execution. 
+Geth does not implement a generic custom type transaction. It does implement 3 types of transactions. 
+`Legacy`, `AccessList` and `DynamicFee` transactions.
+
+Both `AccessList` and `DynamicFee` transactions have an `AccessList` field that used by the transaction issuer to specify future storage/address accesses that the transaction will make.
+
+AccessLists are available in web3 frameworks such as [ethers](https://docs.ethers.io/v5/api/providers/types/#types--access-lists).
+
+
+Obscuro uses a single Address and one of multiple Storage Keys to specify the Revelation period for the transaction.
+
+
+#### In depth AccessList usage 
+
+The specification of the `AccessList` Field is as follows:
+
+```
+For the transaction to be valid, accessList must be of type [[{20 bytes}, [{32 bytes}...]]...], 
+where ... means “zero or more of the thing to the left”.
+For example, the following is a valid access list (all hex strings would in reality be in byte representation):
+
+[
+    [
+        "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae",
+        [
+            "0x0000000000000000000000000000000000000000000000000000000000000003",
+            "0x0000000000000000000000000000000000000000000000000000000000000007"
+        ]
+    ],
+    [
+        "0xbb9bc244d798123fde783fcc1c72d3bb8c189413",
+        []
+    ]
+]
+```
+
+Obscuro uses the `AccessList` object to determine the revelation period.
+A special address and special storage keys combination is checked for internally.
+
+To simplify the protocol the Null address (0x0000000000000000000000000000000000000000) will be used and the hexadecimal representation of 1 to 5 is used to specify the revelation period. 
+
+An example would be:
+```
+[
+    [
+        "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae",                             <- Canonical AccessList usage
+        [
+            "0x0000000000000000000000000000000000000000000000000000000000000003",
+            "0x0000000000000000000000000000000000000000000000000000000000000007"
+        ]
+    ],
+    [
+        "0x0000000000000000000000000000000000000000",                             <- Obscuro Revelation Period
+         [
+            "0x0000000000000000000000000000000000000000000000000000000000000003", <- 1 day revelation Period
+            "0x0000000000000000000000000000000000000000000000000000000000000007"  <- ignored
+        ]
+    ]
+]
+```
+

integration/ethereummock/node.go

@@ -309,6 +309,7 @@ func (m *Node) startMining() {
 	m.logger.Info(" starting miner...")
 	// stores all transactions seen from the beginning of time.
 	mempool := make([]*types.Transaction, 0)
+	types.DynamicFeeTx{}
 	z := int32(0)
 	interrupt := &z