Merge pull request #730 from ScorexFoundation/develop

Release v4.0.4

README.md

@@ -1,45 +1,123 @@
-# sigmastate-interpreter
-Interpreter for a family of Sigma-State authentication languages
-
-## Brief Description
-
-Every coin in Bitcoin is protected by a program in the stack-based Script language. An interpreter for the language is 
-evaluating the program against a redeeming program (in the same language) as well as a context (few variables
-containing information about a spending transaction and the blockchain), producing a single boolean value as a result. 
-While Bitcoin Script allows for some contracts to be programmed, its abilities are limited while many instructions
-were removed after denial-of-service or security issues discovered. Also, to add new cryptographic primitives, for example, 
-ring signatures, a hard-fork is required.
-
-Generalizing the Bitcoin Script, we introduce a notion of an authentication language where a verifier is running an 
-interpreter which three inputs are a proposition defined in terms of the language, a context and also a proof (not
-necessarily defined in the same language) generated by a prover for the proposition against the same context. The 
-interpreter is deterministically producing a boolean value and must finish evaluation for any possible inputs within 
-concrete constant time.
-
-We propose an alternative authentication language, named Σ-State. It defines guarding proposition for a coin as a logic 
-formula which combines predicates over a context and cryptographic statements provable via Σ-protocols with 
-AND, OR, k-out-of-n connectives. A prover willing to spend the coin first reduces the compound proposition to a 
-compound cryptographic statement by evaluating predicates over known shared context (state of the blockchain system and
-a spending transaction). Then the prover is turning a corresponding (and possibly complex) Σ-protocol into a signature 
-with the help of a Fiat-Shamir transformation. A verifier (a full-node in a blockchain setting) then is checking the proposition 
-against the context and the signature. Language expressiveness is defined by a set of predicates over context and a 
-set of cryptographic statements. We show how the latter could be updated with a soft-fork by using a language like 
-ZKPDL [1], and how the former could be updated with a soft-fork by using versioning conventions. We propose a set of 
-context predicates for a Bitcoin-like cryptocurrency with a guarantee of constant upper-bound verification time. 
-We provide several examples: ring and threshold signatures, pre-issued mining rewards, crowdfunding, and demurrage currency.
-
-## Getting started
-
-Because there is currently no published version of Sigma-state interpreter,
-to use it in your project you first need to:
-
- 1. Clone or download [sigmastate-interpreter](https://github.com/ScorexFoundation/sigmastate-interpreter) 
-   (`git clone git@github.com:ScorexFoundation/sigmastate-interpreter.git` from command line).
- 2. Run `sbt publishLocal` in the directory it was cloned to. 
- This will publish the artifacts in the local ivy repository (usually at `$HOME/.ivy`)
- 3. In your own project add library dependency
- ```
-libraryDependencies ++= Seq(
-  "org.scorexfoundation" %% "sigma-state" % "0.9.4"
-) 
- ```
+# ErgoScript compiler and ErgoTree interpreter 
+
+This repository contains implementations of ErgoScript compiler and ErgoTree
+Interpreter for a family of Sigma-protocol based authentication languages (or simply
+Sigma language).
+
+This library is used internally in [Ergo
+Node](https://github.com/ergoplatform/ergo) and
+[ergo-wallet](https://github.com/ergoplatform/ergo/tree/master/ergo-wallet), the
+public interfaces are subject to change.
+
+For development of Ergo applications using JVM languages (Java/Scala/Kotlin/etc)
+a better alternative is to use
+[Appkit](https://github.com/ergoplatform/ergo-appkit).
+
+## Sigma Language Background
+
+Every coin in Bitcoin is protected by a program in the stack-based Script
+language. An interpreter for the language is evaluating the program against a
+context (few variables containing information about a spending transaction and
+the blockchain), producing a single boolean value as a result. While Bitcoin
+Script allows for some contracts to be programmed, its abilities are limited.
+Also, to add new cryptographic primitives, for example, ring signatures, a
+hard-fork is required.
+
+Generalizing the Bitcoin Script, ErgoScript compiler and ErgoTree interpreter
+implement an _authentication language_ which allows to express coin spending
+conditions. The [ErgoScript
+Compiler](sigmastate/src/main/scala/sigmastate/lang/SigmaCompiler.scala#L48)
+compiles the source code into
+[ErgoTree](sigmastate/src/main/scala/sigmastate/Values.scala#L990) byte code,
+which can be saved in UTXO coins to protect their spending (same as in Bitcoin).
+
+ErgoTree, in turn, is a bytecode language and memory representation which can be
+deterministically interpreted in the given _blockchain context_. 
+ErgoTree defines guarding proposition for a coin as a logic formula which
+combines predicates over a context and cryptographic statements provable via
+[Σ-protocols](https://en.wikipedia.org/wiki/Proof_of_knowledge#Sigma_protocols)
+with AND, OR, k-out-of-n connectives.
+
+An _interacting party_ willing to spend the coin first constructs a
+[prover](sigmastate/src/main/scala/sigmastate/interpreter/ProverInterpreter.scala)
+with a set of secrets it knows and then the prover is executed in two steps:
+
+- _Reduction_ - the prover uses the ErgoTree interpreter and deterministically
+reduces the ErgoTree proposition to a compound _cryptographic statement_(aka
+sigma proposition, Σ-protocol) by evaluating ErgoTree over known shared context
+(state of the blockchain system and a spending transaction). This step produces
+a value of the [SigmaBoolean](sigmastate/src/main/scala/sigmastate/Values.scala)
+type.
+
+- Signing - the prover is turning the obtained (and possibly
+complex) Σ-proposition into a signature with the help of a [Fiat-Shamir
+transformation](https://en.wikipedia.org/wiki/Fiat-Shamir_heuristic). This step
+produces a _proof_ that the party knows the secrets such that the knowledge can
+be verified before the spending transaction is added to the blockchain.
+
+To allow valid coin spending a
+[verifier](sigmastate/src/main/scala/sigmastate/interpreter/Interpreter.scala)
+is running the ErgoTree interpreter with the following three inputs:
+- a quarding proposition given by an ErgoTree 
+- a blockchain _context_ of the transaction being verified
+- a _proof_ (aka transaction signature) generated by a _prover_ 
+
+The verifier is executed as part of transaction validation for each input and is
+executed in tree steps:
+
+- _Reduction_ - same as prover, the verifier uses the ErgoTree interpreter and
+deterministically produces a value of the
+[SigmaBoolean](sigmastate/src/main/scala/sigmastate/Values.scala) type. 
+However, this step must finish evaluation for any possible inputs within
+concrete fixed time limit (aka maximum cost), which is checked by the interpreter.
+
+- Cost estimation - the verifier estimates the complexity of cryptographic Sigma
+proposition (based in the size and the concrete nodes of SigmaBoolean tree). The
+spending fails if the estimated cost exceeds the maximum limit.
+
+- Signature verification - the signature checker takes 1) the proof, 2) the
+SigmaBoolean (aka [sigma
+protocol](https://en.wikipedia.org/wiki/Proof_of_knowledge#Sigma_protocols)
+proposition) and 3) the signed message (e.g. transaction bytes).
+The checker than verifies the proof, which means it verifies that all the
+necessary secrets has been known and used to construct the proof (i.e. sign the
+transaction).
+
+## Getting Started 
+
+This library is
+[publishied](https://mvnrepository.com/artifact/org.scorexfoundation/sigma-state)
+on Maven repository and can be added to the SBT configuration of Scala project.
+
+```scala
+libraryDependencies += "org.scorexfoundation" %% "sigma-state" % "4.0.3"
+```
+
+## Repository Organization
+
+| sub-module  | description |
+|---|-----|
+| common | Used in all other submodules and contain basic utility classes |
+| core   | Implementation of graph-based intermediate representation of ErgoTree, which is used in cost estimation and interpretation |
+| docs   | Collection of documents |
+| library | Implementation of graph IR nodes for Coll, Size and other types  |
+| library-api | Declarations of interfaces   |
+| library-impl | Implementation of interfaces   |
+| sigma-api | Declarations of runtime interfaces which are used in ErgoTree interpreter  |
+| sigma-impl | Implementation of sigma-api interfaces   |
+| sigma-library | Implementation of graph IR nodes for Sigma types   |
+| sigmastate | Implementation ErgoTree, Interpreter and cost estimation   |
+
+## References
+
+- [Ergo Site](https://ergoplatform.org/en/)
+- [Ergo Sources](https://github.com/ergoplatform/ergo)
+- [Ergo Appkit](https://github.com/ergoplatform/ergo-appkit)
+- [Ergo Appkit Examples](https://github.com/aslesarenko/ergo-appkit-examples)
+- [ergo-android](https://github.com/aslesarenko/ergo-android)
+- [ergo-wallet-android](https://github.com/MrStahlfelge/ergo-wallet-android)
+- [ErgoTree Specification](https://ergoplatform.org/docs/ErgoTree.pdf)
+- [Ergo Documents](https://ergoplatform.org/en/documents/)
+
+
+

build.sbt

@@ -142,7 +142,7 @@ credentials ++= (for {
 pgpPublicRing := file("ci/pubring.asc")
 pgpSecretRing := file("ci/secring.asc")
 pgpPassphrase := sys.env.get("PGP_PASSPHRASE").map(_.toArray)
-usePgpKeyHex("28E27A67AEA38DA458C72228CA9254B5E0640FE4")
+usePgpKeyHex("C1FD62B4D44BDF702CDF2B726FF59DA944B150DD")
 
 def libraryDefSettings = commonSettings ++ testSettings ++ Seq(
   scalacOptions ++= Seq(

common/src/main/scala/scalan/AnyVals.scala

@@ -43,6 +43,7 @@ class AVHashMap[K,V](val hashMap: HashMap[K,V]) extends AnyVal {
   @inline final def keySet: java.util.Set[K] = hashMap.keySet()
 }
 object AVHashMap {
+  /** Helper method to create a new map with the given capacity. */
   def apply[K,V](initialCapacity: Int) = new AVHashMap[K,V](new HashMap[K,V](initialCapacity))
 }
 

common/src/main/scala/scalan/util/BenchmarkUtil.scala

@@ -31,6 +31,15 @@ object BenchmarkUtil {
     (res, t - t0)
   }
 
+  /** Execute block and measure the time of its execution in nanoseconds. */
+  def measureTimeNano[T](block: => T): (T, Long) = {
+    val start = System.nanoTime()
+    val res = block
+    val end = System.nanoTime()
+    (res, end - start)
+  }
+
+
   def runTasks(nTasks: Int)(block: Int => Unit) = {
     val (_, total) = measureTime {
       val tasks = (1 to nTasks).map(iTask => Future(block(iTask)))

common/src/main/scala/scalan/util/Extensions.scala

@@ -164,7 +164,14 @@ object Extensions {
       * @see BigInteger#longValueExact
       */
     @inline final def to256BitValueExact: BigInteger = {
-      if (x.bitLength() <= 255) x // TODO HF: allow 256 bit values
+      // Comparing with 255 is correct because bitLength() method excludes the sign bit.
+      // For example, these are the boundary values:
+      // (new BigInteger("80" + "00" * 31, 16)).bitLength() = 256
+      // (new BigInteger("7F" + "ff" * 31, 16)).bitLength() = 255
+      // (new BigInteger("-7F" + "ff" * 31, 16)).bitLength() = 255
+      // (new BigInteger("-80" + "00" * 31, 16)).bitLength() = 255
+      // (new BigInteger("-80" + "00" * 30 + "01", 16)).bitLength() = 256
+      if (x.bitLength() <= 255) x
       else
         throw new ArithmeticException("BigInteger out of 256 bit range");
     }

common/src/test/scala/scalan/TestUtils.scala

@@ -3,6 +3,7 @@ package scalan
 import scalan.util.FileUtil
 import org.scalactic.TripleEquals
 import org.scalatest.{Inside, Matchers, TestSuite}
+import scalan.util.StringUtil.StringUtilExtensions
 
 /**
   * Created by slesarenko on 11/10/2017.
@@ -35,8 +36,8 @@ trait TestUtils extends TestSuite with Matchers with Inside with TripleEquals {
 
   protected def currentTestName: String = {
     val testName = _currentTestName.get()
-    assert(testName != null, "currentTestName called outside a test")
-    testName
+    if (testName.isNullOrEmpty) "_outside_tests_"
+    else testName
   }
 
   protected def currentTestNameAsFileName: String = FileUtil.cleanFileName(currentTestName)