Document WabiSabi based protocol

This document describes a concrete but general protocol which uses
WabiSabi credentials to collaboratively create transactions.

The specifics of ransaction structure are out of scope.

The SVG files are generated with `plantuml -tsvg`, and should arguably
not be in the repository, but github will not render plantuml source
files directly.

See also #64

diagrams/interaction_diagram.txt

@@ -0,0 +1,120 @@
+@startuml
+collections Satoshis
+participant Coordinator
+participant Alice1
+participant Alice2
+participant Bob
+database Mempool
+
+title Scenario: A Participant Is Consolidating 2 Coins (Alice1, Alice2) Into 1 (Bob)\n
+
+== Input Registration ==
+
+Satoshis -> Coordinator ++ : GetCoinjoinStatuses
+return CoinjoinStatuses[]
+
+Alice1 -> Coordinator ++: IREG - RoundId, Input, RoundParamSig, ZeroCredReqs[]
+note right of Coordinator
+    IsRoundFound()
+    IsIRegPhase()
+    IsUnspent()
+    IsConfirmed()
+    IsMature()
+    IsStandardScript()
+    IsNotMalleable()
+    CheckRoundParamSig()
+    IsAllowedIfBlameRound()
+    IsNotBanned()
+    UpdateIfDuplicateInput()
+end note
+return AliceId, ZeroCreds[]
+...
+
+Alice1 -> Coordinator ++: CCONF - RoundId, AliceId, PresentedCreds[], RealCredReqs[], BalanceProof, ZeroCredReqs[]
+note right of Coordinator
+    IsRoundFound()
+    IsIRegOrCConfPhase()
+    IsAliceFound()
+    EnsureUniqueSerialNumber()
+    CheckCredProofs()
+end note
+return ZeroCreds[]
+
+Alice2 -> Coordinator ++: IREG - RoundId, Input, RoundParamSig, ZeroCredReqs[]
+note right of Coordinator
+    IsRoundFound()
+    IsIRegPhase()
+    IsUnspent()
+    IsConfirmed()
+    IsMature()
+    IsStandardScript()
+    IsNotMalleable()
+    CheckRoundParamSig()
+    IsAllowedIfBlameRound()
+    IsNotBanned()
+    UpdateIfDuplicateInput()
+end note
+return AliceId, ZeroCreds[]
+
+== Connection Confirmation ==
+
+Alice1 -> Coordinator ++: CCONF - RoundId, AliceId, PresentedCreds[], RealCredReqs[], BalanceProof, ZeroCredReqs[]
+note right of Coordinator
+    IsRoundFound()
+    IsIRegOrCConfPhase()
+    IsAliceFound()
+    EnsureUniqueSerialNumber()
+    CheckCredProofs()
+end note
+return RealCreds[]
+
+Alice2 -> Coordinator ++: CCONF - RoundId, AliceId, PresentedCreds[], RealCredReqs[], BalanceProof, ZeroCredReqs[]
+note right of Coordinator
+    IsRoundFound()
+    IsIRegOrCConfPhase()
+    IsAliceFound()
+    EnsureUniqueSerialNumber()
+    CheckCredProofs()
+end note
+return RealCreds[]
+
+== Output Registration ==
+
+Bob -> Coordinator ++: OREG - RoundId, Output, PresentedCreds[]
+note right of Coordinator
+    IsRoundFound()
+    IsORegPhase()
+    IsStandardScript()
+    EnsureUniqueSerialNumber()
+    CheckCredProofs()
+end note
+return UnsignedTransactionSecret
+
+== Transaction Signing ==
+
+Alice1 -> Coordinator ++: TSIG - RoundId, AliceId, InputSig
+note right of Coordinator
+    IsRoundFound()
+    IsTSigPhase()
+    IsAliceFound()
+    CheckInputSig()
+end note
+return ACK
+
+Alice2 -> Coordinator ++: TSIG - RoundId, AliceId, InputSig
+note right of Coordinator
+    IsRoundFound()
+    IsTSigPhase()
+    IsAliceFound()
+    CheckInputSig()
+end note
+return ACK
+
+== Transaction Broadcasting ==
+
+Coordinator -> Mempool**  : SignedTransaction
+
+Satoshis -> Coordinator ++ : GetCoinjoinStatuses
+return CoinjoinStatuses[]
+
+@enduml

diagrams/round_states.txt

@@ -0,0 +1,65 @@
+@startuml
+
+hide empty description
+state "Input Registration" as in
+state "Input Registered" as regin <<sdlreceive>>
+state "Connection Confirmation" as conf
+state "Input Confirmed" as confin <<sdlreceive>>
+state "Output Registration" as out
+state "Output Registered" as regout <<sdlreceive>>
+state "Transaction Signing" as sign
+note left of sign
+    If signing times out a new MAC key must be generated
+    and only signing inputs permitted to re-register
+end note
+state "Input Signed" as sig <<sdlreceive>>
+state "Transaction Broadcast" as bcast
+state c1 <<choice>>
+state c2 <<choice>>
+state c3 <<choice>>
+state c4 <<choice>>
+state c5 <<choice>>
+state c6 <<choice>>
+state c7 <<choice>>
+note left of c7
+    If broadcast fails, only inptus which weren't
+    double spent are  permitted to re-register
+end note
+
+[*] --> in
+in --> regin
+regin --> c1
+in --> c5 : timeout
+c5 --> conf : [registered >= min]
+c5 --> [*] : [registered < min]
+c1 --> in : [registered < max]
+c1 --> conf : [registered == max]
+conf --> c6 : timeout
+c6 --> [*] : [confirmed < min]
+c6 --> out : [confirmed >= min]
+conf --> confin
+confin --> c2
+c2 --> conf  : [unconfirmed > 0]
+c2 --> out : [unconfirmed == 0]
+out --> regout
+regout --> c3
+c3 --> sign : [balance == 0]
+c3 --> out : [balance > 0]
+out --> sign : timeout
+sign --> sig
+sig --> c4
+c4 --> sign : [unsigned > 0]
+c4 --> bcast : [unsigned == 0]
+sign --> in  : timeout
+bcast --> c7
+c7 --> [*]
+c7 -up-> in
+
+
+
+regin: nonempty description
+confin: nonempty description
+regout: nonempty description
+sig: nonempty description
+
+@enduml

diagrams/utxo_states.txt

@@ -0,0 +1,85 @@
+@startuml
+
+hide empty description
+
+state "Created" as created
+created: funding tx
+created: in mempool
+note right of created
+    A child of a banned
+    input may start in
+    the banned stated.
+
+    For simplicity, and
+    because destroying
+    UTXOs incurs a cost,
+    we illustrate a DoS
+    policy that doesn't
+    take provenance into
+    account.
+end note
+state "Mined" as mined
+mined: funding tx
+mined: confirmed
+note left of destroyed
+    For simplicity reorgs
+    are not shown, so the
+    mined and destroyed
+    states assume sufficient
+    confirmation depth.
+end note
+state "Spent" as spent
+spent: spending tx
+spent: in mempool
+state "Destroyed" as destroyed
+destroyed: spending tx
+destroyed: confirmed
+
+
+state "Coordinator State" as round {
+    state "Registered" as ireg
+    state "Confirmed" as cconf
+    state "Signed" as signed
+    state nc <<choice>>
+    state "Banned" as banned
+
+    ireg --> cconf
+    cconf --> signed
+    cconf --> nc
+    signed --> ireg
+
+    ireg --> nc
+
+    mined --> ireg
+    signed --> spent
+    signed --> mined
+
+    nc --> banned
+    nc --> mined
+    note left of nc
+        DoS prevention policy
+
+        De-registration and timeouts
+        are follow this path, since
+        repeated de-registration may
+        suggest a DoS attack
+
+        Repeated non-signing inputs
+        strongly suggests DoS attempts
+        but there's always plausible
+        deniability due to connectivity
+        issues, so bans should expire.
+    end note
+
+    banned --> mined
+    banned --> destroyed
+}
+[*] --> created
+created --> mined
+mined --> spent
+spent --> destroyed
+spent --> mined
+created --> [*]
+destroyed --> [*]
+
+@enduml