Adaptor point doc

AttestationPoint.md

@@ -0,0 +1,108 @@
+# Deterministic Attestation Point Computation
+
+## Introduction
+
+Discreet Log Contracts (DLCs) are oracle contracts enforced using a set of adaptor signature "point-locks."
+This means that in order to spend any execution branch of a DLC, one must reveal the scalar pre-image for a point.
+As is described in this document, the points used for adaptor signing correspond to anticipations of all
+possible oracle attestations such that exactly one adaptor secret is revealed, unlocking exactly one signature,
+making exactly one Contract Execution Transaction (CET) valid for on-chain publication.
+
+By an anticipation of an oracle attestation, we mean an elliptic curve point `S` whose scalar pre-image `s` (i.e. `S = s*G`)
+is an oracle attestation of a specific message, `m` (or the sum of multiple such attestations).
+The point `S` can be thought of as an encryption key to be used on the signature of the CET which corresponds to the
+event where `m` is attested to so that this signature can only be used should this attestation be broadcast.
+The key point is that `S` can be computed *in advance* given information in oracle announcements so that anticipation points
+(aka attestation points or sometimes adaptor points) can be used to construct a DLC and later the corresponding attestations
+are used to execute that DLC.
+
+At a high level, this is done using the fact that oracle attestations, `s`, are validated against public key information in the usual way
+by checking that `s*G` is equal to a point computed in another way from public information, thus this point can be used as an attestation point.
+
+## Table of Contents
+
+* [Disambiguation of Terms](#disambiguation-of-terms)
+* [Attestation Point Computation](#attestation-point-computation)
+  * [Single Attestation Points](#single-attestation-points)
+  * [Multiple Attestation Aggregate Points](#multiple-attestation-aggregate-points)
+* [Single Oracle Enumerated Outcome Attestation Points](#single-oracle-enumerated-outcome-attestation-points)
+* [Single Oracle Numeric Outcome Attestation Points](#single-oracle-numeric-outcome-attestation-points)
+* [Multiple Oracle Attestation Points](#multiple-oracle-attestation-points)
+* [Authors](#authors)
+
+## Disambiguation of Terms
+
+* **CET** - A Contract Execution Transaction (CET) is a Bitcoin transaction which spends the DLC funding output as an input
+  and outputs the DLC participants payouts.
+  Note that every adaptor point, attestation point, adaptor signature, and oracle outcome will map to some CET but that this mapping
+  is not one-to-one since multiple points/signatures/outcomes can map to the same CET if those outcomes result in equal payouts.
+* **Adaptor Point** - An Adaptor Point is an elliptic curve point used as an encryption key for a signature so that the encrypted signature
+  is known as an adaptor signature.
+  This encryption is used to make signatures (and transitively, transactions) conditional on the scalar pre-image of this point becoming known.
+  Often times an adaptor point is assigned meaning through its functional use in a Bitcoin contracting scheme such as a DLC.
+  Specifically for DLCs, adaptor points always correspond to oracle attestations so that they are always attestation points and
+  these two terms are occasionally used inter-changeably in these specifications.
+* **Attestation Point** - Also known as an anticipation point, an Attestation Point is an elliptic curve point `S = s*G` such that its scalar pre-image,
+  `s`, is an oracle attestation (or sum of multiple oracle attestations).
+  These points can be computed without explicitly knowing the scalar pre-image using only an oracle's public announcement information.
+  These points are used in the DLC specification as Adaptor Points.
+* **Adaptor Signature** - An Adaptor Signature is an encrypted (on-chain-valid) digital signature which is constructed by a signer with their key
+  along with an Adaptor Point, which is an encryption (public) key.
+  This signature can be validated without decryption so long as the verifier knows not only the message being signed and the signers public key,
+  but also the Adaptor Point used to encrypt the signature.
+  The adaptor signature can only be decrypted into a valid on-chain signature using knowledge of the scalar pre-image of the Adaptor Point.
+  This process also leaks this scalar pre-image to the adaptor signer as the difference between the decrypted and encrypted signature is this secret.
+* **Digit Prefix** - When an oracle attests to a numeric outcomes such as `77 = 001001101` each bit is individually attested to.
+  As such, when DLC payouts are constant on some interval, DLC participants often only use a prefix of the bits signed and not all of them to
+  correspond to the set of outcomes where that prefix is followed by any bit-string, e.g. the Digit Prefix `001001` corresponds to the inclusive
+  interval of outcomes `[72, 79]` (assuming a `num_digits` of `9`) because `72 = 001001000` and `79 = 001001111`.
+* **Oracle Outcome** - TODO
+
+TODO: Don't forget to link to this from Protocol and Messaging docs as well as the two Numeric Outcome docs.
+
+## Attestation Point Computation
+
+### Single Attestation Points
+
+When a single oracle attests to a single value (e.g. an element of an enumeration or a single digit of a numeric outcome),
+their attestation is `s = k + m*x` where `k` is the scalar pre-image of the nonce, `R = k*G`, committed to in the
+announcement, `m` is the index of the message value being attested to, and `x` is the oracle's private attestation key.
+
+Thus, to compute the point `S = s*G = (k + m*x)*G = k*G + m*(x*G) = R + m*P` we simply add the nonce, `R`, to
+the index, `m`, times the oracle public attestation key, `P = x*G`.
+
+Using an attestation point computed in this way as an adaptor point will result in an adaptor signature which can only be decrypted
+in the case that the oracle attestation of the specific value in question, `m`, becomes known.
+
+### Multiple Attestation Aggregate Points
+
+Given public keys `P1, ..., Pn` and nonces `R1, ..., Rn` we can compute `n` individual adaptor points for
+a given events `(m1, ..., mn)` in the usual way: `Si = si * G = Ri + mi*Pi`.
+To compute an aggregate attestation point for the event where the oracles attestation keys `Pi` are each attesting to their
+corresponding `mi` the sum of the corresponding adaptor points is used:
+`S(1..n) = s(1..n) * G = (s1 + s2 + ... + sn) * G = s1 * G + s2 * G + ... + sn * G = S1 + S2 + ... + Sn`.
+
+When the oracle broadcasts its `n` attestations `s1, ..., sn`, the corresponding aggreate adaptor secret
+can be computed as `s(1..m) = s1 + s2 + ... + sm` which can be used to broadcast a corresponding CET.
+
+Intro the usefulness of aggregate attestation points (as a general AND process for oracle locks) and then paste and modify [this](NumericOutcomeCompression.md#adaptor-points-with-multiple-attestations).
+
+## Single Oracle Enumerated Outcome Attestation Points
+
+Link to single attestation points and then simply contextualize within single oracle enum outcome and explicitly define order.
+
+## Single Oracle Numeric Outcome Attestation Points
+
+Link to aggregate attestation points and then contextualize within single oracle numeric outcome with explicit discussion of digit prefixes including examples and then explicitly define order by linking out to the Numeric Outcome docs.
+
+## Multiple Oracle Attestation Points
+
+Link to aggregate attestation points and then define multi-oracle ordering as the chosen combination generating function paired with the orders defined earlier in this document. 
+
+## Authors
+
+Nadav Kohen <[email protected]>
+
+![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
+<br>
+This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).

NumericOutcome.md

@@ -2,30 +2,30 @@
 
 ## Introduction
 
-This document combines the [CET Compression](CETCompression.md) and [Payout Curve](PayoutCurve.md) specifications, along with
+This document combines the [Numeric Outcome Compression](NumericOutcomeCompression.md) and [Payout Curve](PayoutCurve.md) specifications, along with
 independently introduced [Rounding Intervals](#rounding-intervals) to specify the complete procedure for CET
 construction, adaptor signing, and signature verification for DLCs over numeric outcomes.
 
-When dealing with enumerated outcomes, DLCs require a single nonce and Contract Execution
-Transactions (CETs) are claimed using a single oracle signature.
-This scheme results in DLCs which contain a unique CET for every possible outcome, which is
-only feasible if the number of possible outcomes is of manageable size. 
+When dealing with enumerated outcomes, DLCs require only a single nonce and Contract Execution
+Transactions (CETs) are claimed using a single oracle attestation.
+This scheme results in DLCs which contain a unique adaptor signature for every possible outcome, which
+is only feasible if the number of possible outcomes is of manageable size. 
 
 If an outcome can be any of a large range of numbers, then using a simple enumeration of
 all possible numbers in this range is unwieldy.
 We optimize for this case by using numeric decomposition in which the oracle signs each digit of the outcome
-individually so that many possible outcomes can be [compressed](CETCompression.md) into a single CET by ignoring certain digits.
+individually so that many possible outcomes can be [compressed](NumericOutcomeCompression.md) into a single adaptor signature by ignoring certain digits.
 
 We also compress the information needed to communicate all outcomes, as this can usually be viewed as a
-[payout curve](PayoutCurve.md) parameterized by only a few numbers which determine payouts for the entire possible range.
+[payout curve](PayoutCurve.md) parameterized by only a few numbers which determine payouts for the entire possible domain.
 
-Lastly, we introduce a method of deterministic rounding which allows DLC participants to increase CET
-compression where they are willing to allow some additional rounding error in their payouts.
+Lastly, we introduce a method of deterministic rounding which allows DLC participants to increase Numeric
+outcome compression in places where they are willing to allow some additional rounding error in their payouts.
 
-We put all of these pieces together to specify CET calculation and signature validation procedures
+We put all of these pieces together to specify CET calculation, adaptor signing, and signature validation procedures
 for Numeric Outcome DLCs.
 
-This specification, as well as the [payout curve](PayoutCurve.md) and [CET compression](CETCompression.md) specifications are primarily concerned
+This specification, as well as the [payout curve](PayoutCurve.md) and [Numeric Outcome compression](NumericOutcomeCompression.md) specifications are primarily concerned
 with the protocol-level deterministic reproduction and concise communication of generic higher-level information.
 These documents are not likely to concern application-level and UI/UX developers, who should operate at
 their own levels of abstraction, only to compile application-level information into the formats specified here
@@ -37,18 +37,19 @@ when interacting with lowest-level core DLC logic.
   * [Reference Implementations](#reference-implementations)
   * [Rounding Interval Serialization](#rounding-interval-serialization)
 
-* [Contract Execution Transaction Calculation](#contract-execution-transaction-calculation)
+* [Contract Execution Transaction Calculation and Signing](#contract-execution-transaction-calculation-and-signing)
 * [Contract Execution Transaction Signature Validation](#contract-execution-transaction-signature-validation)
 * [Authors](#authors)
 
 ## Rounding Intervals
 
-As detailed in the [CET compression document](CETCompression.md#cet-compression), any time some continuous interval of the domain results in the same payout value,
-we can compress the CETs required for that interval to be logarithmic in size compared to using one CET per outcome on the interval.
+As detailed in the [numeric outcome compression document](NumericOutcomeCompression.md#numeric-outcome-compression), any time some continuous interval of the domain results in a constant
+payout value, we can compress the adaptor signatures required for that interval to be logarithmic in size compared to using one adaptor
+signature per outcome on the interval.
 As such, it can be beneficial to round the outputs of the payout function to allow for bounded approximation of pieces of the payout
 curve by constant-payout intervals.
 For example, if two parties are both willing to round payout values to the nearest 100 satoshis, they can have significant savings
-on the number of CETs required to enforce their contract.
+on the number of adaptor signatures required to enforce their contract.
 To this end, we allow parties to negotiate rounding intervals which may vary along the curve, allowing for less rounding near more
 probable outcomes and allowing for more rounding to occur near extremes.
 
@@ -88,12 +89,12 @@ If `begin_interval_1` is strictly greater than `0`, then the interval between `0
 * `begin_interval_1`, if it exists, MUST be non-negative.
 * `begin_interval` MUST strictly increase.
 
-## Contract Execution Transaction Calculation
+## Contract Execution Transaction Calculation and Signing
 
 Given the offerrer's [payout function](PayoutCurve.md), a `total_collateral` amount and [rounding intervals](#rounding-intervals), we wish to compute a list of pairs
 of digit prefixes (i.e. arrays of integers) and Satoshi values.
-Each of these pairs will then be turned into a CET whose adaptor point is [computed from the digit prefix](CETCompression.md#adaptor-points-with-multiple-signatures) and whose
-output values will be equal to the Satoshi payout and `total_collateral` minus that payout.
+Each of these pairs will then be turned into a CET whose adaptor point used for signing is [computed from the digit prefix](NumericOutcomeCompression.md#adaptor-points-with-multiple-signatures) and
+whose output values will be equal to the Satoshi payout and `total_collateral` minus that payout.
 
 We must first modify the pure function given to us (e.g. by interpolating points) by applying rounding, and then setting all
 negative payouts to `0` and all computed payouts above `total_collateral` to equal `total_collateral`.
@@ -111,21 +112,31 @@ at the unmodified function's derivatives.
 Regardless of how these intervals are computed, it is required that the constant-valued intervals be as large as possible.
 For example, if you have two constant-valued intervals in a row with the same value, these must be merged.
 
-Finally, once these intervals have been computed, the [CET compression](CETCompression.md#cet-compression) algorithm is run on each constant-valued interval which generates
-a digit prefix (list of integers) to be paired with the (constant) payout for that interval.
-For variable-payout intervals, a unique CET is constructed for every `event_outcome` where all digits of that `event_outcome` are included
-in the array of integers and the Satoshi payout is equal to the output of the modified function for that `event_outcome`.
+Finally, once these intervals have been computed, the [numeric outcome compression](NumericOutcomeCompression.md#numeric-outcome-compression) algorithm is run on each constant-valued interval
+which generates a digit prefix (list of integers) to be paired with the (constant) payout for that interval.
+Only a single CET is required for each interval (as these intervals have constant payouts) where each of them receives multiple adaptor signatures.
+
+For variable-payout intervals, a unique CET and adaptor signature is constructed for every `event_outcome` where all digits of that `event_outcome`
+are included in the digit prefix (array of integers) and the Satoshi payout is equal to the output of the modified function for that `event_outcome`.
+
+The following diagram illustrates the entire process starting with the domain of all possible outcomes and the modified payout curve, then
+partitioning by payout into intervals of constant value (in red), running numeric outcome compression to get digit prefixes, turning these prefixes
+into adaptor points for their interval's CET and finally using those adaptor points to create adaptor signatures on their corresponding CETs.
+
+![CET and Adaptor Signature Construction](images/DLCCompressionWhiteBack.png)
 
 ## Contract Execution Transaction Signature Validation
 
-To validate the adaptor signatures for CETs given in a `dlc_accept` or `dlc_sign` message, do the [process above](#contract-execution-transaction-calculation[) of computing the list of pairs of
+To validate the adaptor signatures for CETs given in a `dlc_accept` or `dlc_sign` message, do the [process above](#contract-execution-transaction-calculation-and-signing) of computing the list of pairs of
 arrays of digits and payout values to construct the CETs and their adaptor points and then run the `adaptor_verify` function.
 
-However, if `adaptor_verify` results in a failed validation, do not terminate the CET signing process.
+However, if `adaptor_verify` results in a failed validation, do not terminate the CET signature validation process.
 Instead, you must look at whether you rounded up (to `value - (value % rounding_mod) + rounding_mod`)
 or down (to `value - (value % rounding_mod)`).
-If you rounded up, compute the CET resulting from rounding down or if you rounded down, compute the CET resulting from rounding up.
-Call the `adaptor_verify` function against this new CET and if it passes verification, consider that adaptor signature valid and continue.
+If you rounded up, compute the CET and adaptor point resulting from rounding down or if you rounded down, compute the CET and adaptor point
+ resulting from rounding up.
+Call the `adaptor_verify` function against this new CET with the new adaptor point and if it passes verification, consider that adaptor signature
+valid and continue.
 
 This extra step is necessary because there is no way to introduce deterministic floating point computations into this specification without also
 introducing complexity of magnitude much larger than that of this entire specification.