tumbler

package
v0.0.0-...-31898ba Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 28, 2019 License: ISC Imports: 17 Imported by: 0

Documentation

Overview

The tumbler package implements the TumbleBit protocol described in https://eprint.iacr.org/2016/575.pdf.

Index

Constants

View Source 
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
)
View Source 
const (
	// Initial state
	StateInitial = iota
	// Payee states
	StateEscrowComplete
	StatePuzzlesPromised
	StatePuzzlesValidated
	StateEscrowPublished
	MaxPayeeState
	// Payer states
	StateSolutionsPromised
	StateSolutionsValidated
	StateOfferReceived
	StateSolutionPublished
	MaxPayerState
)
View Source 
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
)
View Source 
const ConfirmationInterval = 5 * time.Minute

Variables

View Source 
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.

func UseLogger 

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

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 Epoch 

type Epoch struct {
	Address     string
	Pubkey      string
	BlockHeight int32
	// contains filtered or unexported fields
}

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 

type EscrowRequest struct {
	Address   string
	PublicKey string
	Amount    int64
}

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 

type PuzzleDisclosure struct {
	FakePuzzleList []byte
	FakeFactors    [][]byte
}

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 

func NewSession(tb *Tumbler, address string) *Session

NewSession creates a new Session object with a provided address.

func (*Session) FinalizeEscrow 

func (s *Session) FinalizeEscrow(ctx context.Context) ([]byte, error)

FinalizeEscrow publishes the escrow transaction onto the blockchain.

func (*Session) FinalizeExchange 

func (s *Session) FinalizeExchange(ctx context.Context, reason int, details error)

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 

func (s *Session) PublishSolution(ctx context.Context, secrets [][]byte) error

PublishSolution publishes preimages fulfilling the offer transaction.

func (*Session) RevealSolution 

func (s *Session) RevealSolution(ctx context.Context, po *PaymentOffer) ([][]byte, error)

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) String 

func (s *Session) String() string

func (*Session) TryLock 

func (s *Session) TryLock() bool

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 

type SolutionChallenges struct {
	Epoch   int32
	Puzzles [][]byte
}

SolutionChallenges requests promises of puzzle solutions in order to establish ability of the tumbler to solve puzzles obtained from the payee.

type SolutionPromises 

type SolutionPromises struct {
	Promises  [][]byte
	KeyHashes [][]byte
}

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 

type TransactionSecrets struct {
	Secrets   [][]byte
	Quotients [][]byte
}

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 

func NewTumbler(cfg *Config) *Tumbler

NewTumbler creates a new configured tumbler server object associated with a wallet service that provides wallet and blockchain facilities.

func (*Tumbler) ChainParams 

func (tb *Tumbler) ChainParams() *chaincfg.Params

ChainParams returns the network parameters for the blockchain the tumbler belongs to.

func (*Tumbler) Connect 

func (tb *Tumbler) Connect(s *Session) [16]byte

Connect associates session with a tumbler service.

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 

func (tb *Tumbler) Disconnect(s *Session)

Disconnect removes the session from the lookup table and expiration list.

func (*Tumbler) Lookup 

func (tb *Tumbler) Lookup(key []byte) (*Session, bool)

Lookup attempts to locate an active exchange by a cookie.

func (*Tumbler) NewEpoch 

func (tb *Tumbler) NewEpoch(blockHeight int32) error

NewEpoch creates a new epoch interval starting at the specified block height which acts as a way to lookup existing epochs as well as to expire old ones. Each new epoch generates a unique puzzle key.

func (*Tumbler) Run 

func (tb *Tumbler) Run(ctx context.Context) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.