Documentation ¶
Overview ¶
The tumbler package implements the TumbleBit protocol described in https://eprint.iacr.org/2016/575.pdf.
Index ¶
- Constants
- Variables
- func DisableLog()
- func UseLogger(logger btclog.Logger)
- type Config
- type Epoch
- type EscrowOffer
- type EscrowRequest
- type PaymentOffer
- type PuzzleDisclosure
- type Session
- func (s *Session) FinalizeEscrow(ctx context.Context) ([]byte, error)
- func (s *Session) FinalizeExchange(ctx context.Context, reason int, details error)
- func (s *Session) GetPuzzlePromises(ctx context.Context, cp *SignatureChallenges) (*SignaturePromises, error)
- func (s *Session) GetSolutionPromises(ctx context.Context, sc *SolutionChallenges) (*SolutionPromises, error)
- func (s *Session) PaymentOffer(ctx context.Context, po *PaymentOffer) error
- func (s *Session) PublishSolution(ctx context.Context, secrets [][]byte) error
- func (s *Session) RevealSolution(ctx context.Context, po *PaymentOffer) ([][]byte, error)
- func (s *Session) SetupEscrow(ctx context.Context, er *EscrowRequest) (*EscrowOffer, error)
- func (s *Session) SignChallengeHashes(ctx context.Context, hashes [][]byte) ([][]byte, []byte, error)
- func (s *Session) String() string
- func (s *Session) TryLock() bool
- func (s *Session) Unlock()
- func (s *Session) ValidatePuzzles(ctx context.Context, cd *TransactionDisclosure) (*TransactionSecrets, error)
- func (s *Session) ValidateSolutions(ctx context.Context, pd *PuzzleDisclosure) (*SolutionSecrets, error)
- type SignatureChallenges
- type SignaturePromises
- type SolutionChallenges
- type SolutionPromises
- type SolutionSecrets
- type TransactionDisclosure
- type TransactionSecrets
- type Tumbler
- func (tb *Tumbler) ChainParams() *chaincfg.Params
- func (tb *Tumbler) Connect(s *Session) [16]byte
- func (tb *Tumbler) DeferAction(s *Session, cb func(ctx context.Context, s *Session, arg interface{}), ...)
- func (tb *Tumbler) Disconnect(s *Session)
- func (tb *Tumbler) Lookup(key []byte) (*Session, bool)
- func (tb *Tumbler) NewEpoch(blockHeight int32) error
- func (tb *Tumbler) Run(ctx context.Context) error
Constants ¶
const ( // EpochDuration defines the duration of a single epoch, i.e. // the period within which Escrow, Payment and Chash-Out phases of // the TumbleBit protocol take place. Incidentally, it also specifies // for how long tumbler's funds are escrowed and when it can post a // redeeming transaction to reclaim those funds. EpochDuration = 10 // EpochRenewal defines an interval between two consecutive epochs // expressed in a number of blocks. EpochRenewal = EpochDuration / 2 // PuzzleDifficulty determines Tumbler's RSA group size. // Perhaps should be made more generic and expressed in terms of O(2^n) // complexity, where n is 128, 192 or 256 "bits of security". PuzzleDifficulty = 2048 // RealTransactionCount specifies a number of real transactions that // client should be supplying. The chosen values constitute to approx. // ~80 bits of security, i.e. one in a 2^(42+42) chance of cheating // for the Tumbler during puzzle-promise protocol. RealTransactionCount = 42 // FakeTransactionCount specifies a number of fake transactions to // mix in to the provided list of transaction hashes. Shouldn't be // less than the amount of RealTransactionCount. FakeTransactionCount = RealTransactionCount // RealPreimageCount is the number of preimages payer will put in their // P2SH transaction. NOTE: When changing this value, the redeem script // size estimator (wallet.redeemEscrowSigScriptSize) needs to be updated // as well. RealPreimageCount = 15 // FakePreimageCount is the number of fake preimages used to verify // Tumbler's fairness during puzzle-solving protocol. FakePreimageCount = 285 )
const ( // Initial state StateInitial = iota // Payee states StateEscrowComplete StatePuzzlesPromised StatePuzzlesValidated StateEscrowPublished MaxPayeeState // Payer states StateSolutionsPromised StateSolutionsValidated StateOfferReceived StateSolutionPublished MaxPayerState )
const ( // Exchange has completed successfully ReasonSuccess = iota // Aborting due to a session expiration timeout ReasonSessionExpired // Aborting due to a issue during exchange ReasonFailedExchange // Aborting due to an internal error (i.e. broken RPC connection) ReasonInternalError )
const ConfirmationInterval = 5 * time.Minute
Variables ¶
var (
ErrEpochNotFound = errors.New("no such epoch")
)
Functions ¶
func DisableLog ¶
func DisableLog()
DisableLog disables all library log output. Logging output is disabled by default until either UseLogger or SetLogWriter are called.
Types ¶
type Config ¶
type Config struct { ChainParams *chaincfg.Params EpochDuration int32 EpochRenewal int32 PuzzleDifficulty int Wallet *wallet.Wallet }
Config represents configuration options needed to initialize a tumbler.
type EscrowOffer ¶
type EscrowOffer struct { Epoch int32 LockTime int32 Address string PublicKey string EscrowScript []byte EscrowTx []byte }
EscrowOffer presents the client with a signed but not published escrow transaction set up for a particular epoch and with a specified locktime.
type EscrowRequest ¶
EscrowRequest asks tumbler to escrow the specified amount redeemable by the owner of the public key in case it obtains a correct puzzle solution.
type PaymentOffer ¶
type PaymentOffer struct { Amount int64 PublicKey string EscrowHash []byte EscrowScript []byte EscrowTx []byte Puzzle []byte RealPuzzleList []byte RealFactors [][]byte }
PaymentOffer contains a transaction offering escrowed funds for puzzle preimages. It needs to be validated and published by the tumbler along with a corresponding fulfilling transaction.
PaymentOffer reveals remaining secret data used to construct actual puzzles as published on the blockchain by the payer. Tumbler must post a solution transaction fulfilling the specified condition.
type PuzzleDisclosure ¶
PuzzleDisclosure reveals indexes and secret data used to construct fictional puzzles that were mixed in into the set in the proposal.
type Session ¶
type Session struct { Cookie [16]byte // Identification cookie // contains filtered or unexported fields }
Session keeps state of the exchange with a connected client.
func NewSession ¶
NewSession creates a new Session object with a provided address.
func (*Session) FinalizeEscrow ¶
FinalizeEscrow publishes the escrow transaction onto the blockchain.
func (*Session) FinalizeExchange ¶
func (*Session) GetPuzzlePromises ¶
func (s *Session) GetPuzzlePromises(ctx context.Context, cp *SignatureChallenges) (*SignaturePromises, error)
GetPuzzlePromises obtains cryptographically concealed signature promises.
This marks the starting point for the Puzzle-Promise fairness test where TumbleBit server attempts to convince the client that it will correctly sign the Cash-out transaction when presented by the client without revealing any secret information about the process.
func (*Session) GetSolutionPromises ¶
func (s *Session) GetSolutionPromises(ctx context.Context, sc *SolutionChallenges) (*SolutionPromises, error)
GetSolutionPromises obtains cryptographically concealed puzzle solution promises.
This marks the start of the Puzzle-Solver protocol where a client learns whether or not the tumbler server it's communicating with can provide a solution for a puzzle it obtained from the other client.
Without revealing an actual puzzle the client needs to solve, it provides a set of potential puzzles, most of which are dummy ones that exist only to attest the fairness and indiscriminate nature of the server's puzzle solving capabilities.
func (*Session) PaymentOffer ¶
func (s *Session) PaymentOffer(ctx context.Context, po *PaymentOffer) error
PaymentOffer validates the offer transaction and records it in the ongoing contract. It proceeds to call RevealSolution and PublishSolution to reveal and publish hash commitments on the blockchain.
func (*Session) PublishSolution ¶
PublishSolution publishes preimages fulfilling the offer transaction.
func (*Session) RevealSolution ¶
RevealSolution completes the Puzzle-Solver protocol and reveals blinding factors for the remaining puzzles letting the tumbler know that all of them correspond to a single puzzle it requires a solution for.
The tumbler reveals secrets for unlocking puzzles via a fulfilling transaction on the blockchain. Secrets MUST NOT be sent to the client.
func (*Session) SetupEscrow ¶
func (s *Session) SetupEscrow(ctx context.Context, er *EscrowRequest) (*EscrowOffer, error)
SetupEscrow creates and signs a transaction that escrows tumbler's funds for an EpochDuration. The transaction is a P2SH that requires signatures from both client and tumbler to transfer escrowed funds to the client.
func (*Session) SignChallengeHashes ¶
func (s *Session) SignChallengeHashes(ctx context.Context, hashes [][]byte) ([][]byte, []byte, error)
SignChallengeHashes is a helper function that asks wallet to sign challenge hash values. It's not part of GetPuzzlePromises to make testing feasible.
func (*Session) TryLock ¶
TryLock attempts to acquire the semaphore and returns true if successful and false otherwise.
func (*Session) Unlock ¶
func (s *Session) Unlock()
Unlock releases the semaphore but panics if it was already released.
func (*Session) ValidatePuzzles ¶
func (s *Session) ValidatePuzzles(ctx context.Context, cd *TransactionDisclosure) (*TransactionSecrets, error)
ValidatePuzzles obtains the proof that server is fair and indiscriminate.
A client reveals dummy transactions that were mixed in into the pool of potential Cash-out transactions signed by the tumbler. Iff they verify as dummy transactions, the tumbler discloses secret values used to create associated promises showing its fairness.
Tumbler also creates a proof that it possesses secrets needed to unlock remaining puzzles by returning quotients of their secrets that can be verified by the client with puzzle.VerifyQuotients.
func (*Session) ValidateSolutions ¶
func (s *Session) ValidateSolutions(ctx context.Context, pd *PuzzleDisclosure) (*SolutionSecrets, error)
ValidateSolutions obtains the proof that server is fair and indiscriminate.
A client reveals which puzzles in the mix aren't associated with the one it needs to solve in order to make a payment. It also lets the tumbler know how these puzzles were constructed so that the tumbler can verify that all specified puzzles are indeed fake and revealing solutions won't let the client accidentally obtain the solution for an actual puzzle.
The client on the other hand learns that the tumbler it's communicating with is capable of solving the real puzzle.
type SignatureChallenges ¶
type SignatureChallenges struct { FakeSetHash []byte RealSetHash []byte TransactionHashes [][]byte Signatures [][]byte PublicKey []byte }
SignatureChallenges requests signature promises for specified transaction hashes, some of which are dummy as indicated by the FakeSetHash as opposed to legitimate ones indicated by the RealSetHash. Hash values act as a proof that client has included both in the mix.
type SignaturePromises ¶
type SignaturePromises struct { PublicKey []byte PuzzleKey []byte Puzzles [][]byte Promises [][]byte }
SignaturePromises contains signature promises for transactions requested in SignatureChallenges as well as computational puzzles that unlock appropriate promises once solved.
type SolutionChallenges ¶
SolutionChallenges requests promises of puzzle solutions in order to establish ability of the tumbler to solve puzzles obtained from the payee.
type SolutionPromises ¶
PurchasePromise contains solution promises that once unlocked will provide solutions to all puzzles specified in the proposal.
type SolutionSecrets ¶
type SolutionSecrets struct {
Secrets [][]byte
}
SolutionSecrets provides secret data used to construct promises for puzzles identified as fictional by the client and attested by the tumbler.
type TransactionDisclosure ¶
type TransactionDisclosure struct { FakeTxList []byte RealTxList []byte RandomPads [][]byte Salt []byte }
TransactionDisclosure reveals secret data used to build dummy transactions along with indexes of legitimate and dummy transactions specified in the TransactionHashes vector in the proposal.
type TransactionSecrets ¶
TransactionSecrets provides the required proof that tumbler has signed all provided transactions indiscriminately by revealing secret values used to construct promises for dummy transactions.
type Tumbler ¶
type Tumbler struct {
// contains filtered or unexported fields
}
Tumbler describes an instance of a TumbleBit server.
func NewTumbler ¶
NewTumbler creates a new configured tumbler server object associated with a wallet service that provides wallet and blockchain facilities.
func (*Tumbler) ChainParams ¶
ChainParams returns the network parameters for the blockchain the tumbler belongs to.
func (*Tumbler) DeferAction ¶
func (tb *Tumbler) DeferAction(s *Session, cb func(ctx context.Context, s *Session, arg interface{}), arg interface{}, u time.Time)
DeferAction adds the session to the ticker's list of deferred actions. Caller must ensure to provide the s.deferFn function pointer.
func (*Tumbler) Disconnect ¶
Disconnect removes the session from the lookup table and expiration list.