Documentation

Index

Constants

View Source
const (
	// InitUserLotLimit is the number of lots a new user is permitted to have in
	// active orders and swaps. The market should multiply their lot size by
	// this number to get the limit in units of the base asset. This is
	// potentially a per-market setting instead of an auth constant.
	InitUserTakerLotLimit = 6
	AbsTakerLotLimit      = 150
	BookedLotLimit        = 1200
)
View Source
const DefaultRequestTimeout = 30 * time.Second

DefaultRequestTimeout is the default timeout for requests to wait for responses from connected users after the request is successfully sent.

Variables

View Source
var (
	ErrUserNotConnected = dex.ErrorKind("user not connected")
)

Functions

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func UseLogger

func UseLogger(logger slog.Logger)

UseLogger uses a specified Logger to output package logging info.

Types

type AuthManager

type AuthManager struct {
	// contains filtered or unexported fields
}

AuthManager handles authentication-related tasks, including validating client signatures, maintaining association between accounts and `comms.Link`s, and signing messages with the DEX's private key. AuthManager manages requests to the 'connect' route.

func NewAuthManager

func NewAuthManager(cfg *Config) *AuthManager

NewAuthManager is the constructor for an AuthManager.

func (*AuthManager) Auth

func (auth *AuthManager) Auth(user account.AccountID, msg, sig []byte) error

Auth validates the signature/message pair with the users public key.

func (*AuthManager) ExpectUsers

func (auth *AuthManager) ExpectUsers(users map[account.AccountID]struct{}, within time.Duration)

ExpectUsers specifies which users are expected to connect within a certain time or have their orders unbooked (revoked). This should be run prior to starting the AuthManager. This is not part of the constructor since it is convenient to obtain this information from the Market's Books, and Market requires the AuthManager. The same information could be pulled from storage, but the Market is the authoritative book. The AuthManager should be started via Run immediately after calling ExpectUsers so the users can connect.

func (*AuthManager) ForgiveMatchFail

func (auth *AuthManager) ForgiveMatchFail(user account.AccountID, mid order.MatchID) (forgiven, unbanned bool, err error)

ForgiveMatchFail forgives a user for a specific match failure, potentially allowing them to resume trading if their score becomes passing.

func (*AuthManager) GraceLimit

func (auth *AuthManager) GraceLimit() int

GraceLimit returns the number of initial orders allowed for a new user before the cancellation rate threshold is enforced.

func (*AuthManager) Inaction

func (auth *AuthManager) Inaction(user account.AccountID, misstep NoActionStep, mmid db.MarketMatchID, matchValue uint64, refTime time.Time, oid order.OrderID)

Inaction registers an inaction violation by the user at the given step. The refTime is time to which the at-fault user's inaction deadline for the match is referenced. e.g. For a swap that failed in TakerSwapCast, refTime would be the maker's redeem time, which is recorded in the DB when the server validates the maker's redemption and informs the taker, and is roughly when the actor was first able to take the missed action. TODO: provide lots instead of value, or convert to lots somehow. But, Swapper has no clue about lot size, and neither does DB!

func (*AuthManager) MissedPreimage

func (auth *AuthManager) MissedPreimage(user account.AccountID, epochEnd time.Time, oid order.OrderID)

MissedPreimage registers a missed preimage violation by the user.

func (*AuthManager) Notify

func (auth *AuthManager) Notify(acctID account.AccountID, msg *msgjson.Message)

Notify sends a message to a client. The message should be a notification. See msgjson.NewNotification.

func (*AuthManager) Penalize

func (auth *AuthManager) Penalize(user account.AccountID, lastRule account.Rule, extraDetails string) error

Penalize closes the user's account, unbooks all of their orders, and notifies them of this action while citing the provided rule that corresponds to their most recent infraction.

func (*AuthManager) PreimageSuccess

func (auth *AuthManager) PreimageSuccess(user account.AccountID, epochEnd time.Time, oid order.OrderID)

PreimageSuccess registers an accepted preimage for the user.

func (*AuthManager) RecordCancel

func (auth *AuthManager) RecordCancel(user account.AccountID, oid, target order.OrderID, t time.Time)

RecordCancel records a user's executed cancel order, including the canceled order ID, and the time when the cancel was executed.

func (*AuthManager) RecordCompletedOrder

func (auth *AuthManager) RecordCompletedOrder(user account.AccountID, oid order.OrderID, t time.Time)

RecordCompletedOrder records a user's completed order, where completed means a swap involving the order was successfully completed and the order is no longer on the books if it ever was.

func (*AuthManager) Request

func (auth *AuthManager) Request(user account.AccountID, msg *msgjson.Message, f func(comms.Link, *msgjson.Message)) error

Request sends the Request-type msgjson.Message to the client identified by the specified account ID. The user must respond within DefaultRequestTimeout of the request. Late responses are not handled.

func (*AuthManager) RequestWithTimeout

func (auth *AuthManager) RequestWithTimeout(user account.AccountID, msg *msgjson.Message, f func(comms.Link, *msgjson.Message),
	expireTimeout time.Duration, expire func()) error

RequestWithTimeout sends the Request-type msgjson.Message to the client identified by the specified account ID. If the user responds within expireTime of the request, the response handler is called, otherwise the expire function is called. If the response handler is called, it is guaranteed that the request Message.ID is equal to the response Message.ID (see handleResponse).

func (*AuthManager) Route

func (auth *AuthManager) Route(route string, handler func(account.AccountID, *msgjson.Message) *msgjson.Error)

Route wraps the comms.Route function, storing the response handler with the associated clientInfo, and sending the message on the current comms.Link for the client.

func (*AuthManager) Run

func (auth *AuthManager) Run(ctx context.Context)

Run runs the AuthManager until the context is canceled. Satisfies the dex.Runner interface.

func (*AuthManager) Send

func (auth *AuthManager) Send(user account.AccountID, msg *msgjson.Message) error

Send sends the non-Request-type msgjson.Message to the client identified by the specified account ID. The message is sent asynchronously, so an error is only generated if the specified user is not connected and authorized, if the message fails marshalling, or if the link is in a failing state. See dex/ws.(*WSLink).Send for more information.

func (*AuthManager) Sign

func (auth *AuthManager) Sign(signables ...msgjson.Signable) error

Sign signs the msgjson.Signables with the DEX private key.

func (*AuthManager) Suspended

func (auth *AuthManager) Suspended(user account.AccountID) (found, suspended bool)

Suspended indicates the the user exists (is presently connected) and is suspended. This does not access the persistent storage.

func (*AuthManager) SwapSuccess

func (auth *AuthManager) SwapSuccess(user account.AccountID, mmid db.MarketMatchID, value uint64, redeemTime time.Time)

SwapSuccess registers the successful completion of a swap by the given user. TODO: provide lots instead of value, or convert to lots somehow. But, Swapper has no clue about lot size, and neither does DB!

func (*AuthManager) Unban

func (auth *AuthManager) Unban(user account.AccountID) error

Unban forgives a user, allowing them to resume trading if their score permits it. This is primarily useful for reversing a manual ban. Use ForgiveMatchFail to forgive specific match negotiation failures.

func (*AuthManager) UserOrderLimitAdjustment

func (auth *AuthManager) UserOrderLimitAdjustment(user account.AccountID, base, quote uint32) int64

UserOrderLimitAdjustment returns a delta in units of the base asset to the user's allowed order quantity. This should be added to the market's base order size limit.

type Config

type Config struct {
	// Storage is an interface for storing and retrieving account-related info.
	Storage Storage
	// Signer is an interface that signs messages. In practice, Signer is
	// satisfied by a secp256k1.PrivateKey.
	Signer Signer
	// RegistrationFee is the DEX registration fee, in atoms DCR
	RegistrationFee uint64
	// FeeConfs is the number of confirmations required on the registration fee
	// before registration can be completed with notifyfee.
	FeeConfs int64
	// FeeChecker is a method for getting the registration fee output info.
	FeeChecker FeeChecker
	// UserUnbooker is a function for unbooking all of a user's orders.
	UserUnbooker func(account.AccountID)
	// MiaUserTimeout is how long after a user disconnects until UserUnbooker is
	// called for that user.
	MiaUserTimeout time.Duration

	CancelThreshold float64
	Anarchy         bool
	FreeCancels     bool
	// BanScore defines the penalty score when an account gets closed.
	BanScore uint32
}

Config is the configuration settings for the AuthManager, and the only argument to its constructor.

type FeeChecker

type FeeChecker func(coinID []byte) (addr string, val uint64, confs int64, err error)

FeeChecker is a function for retrieving the details for a fee payment. It is satisfied by (dcr.Backend).FeeCoin.

type NoActionStep

type NoActionStep uint8

NoActionStep is the action that the user failed to take. This is used to define valid inputs to the Inaction method.

const (
	SwapSuccess NoActionStep = iota // success included for accounting purposes
	NoSwapAsMaker
	NoSwapAsTaker
	NoRedeemAsMaker
	NoRedeemAsTaker
)

func (NoActionStep) String

func (step NoActionStep) String() string

String returns the description of the NoActionStep's corresponding Violation.

func (NoActionStep) Violation

func (step NoActionStep) Violation() Violation

Violation returns the corresponding Violation for the misstep represented by the NoActionStep.

type Signer

type Signer interface {
	Sign(hash []byte) *ecdsa.Signature
	PubKey() *secp256k1.PublicKey
}

Signer signs messages. It is likely a secp256k1.PrivateKey.

type Storage

type Storage interface {
	// CloseAccount closes the account for violation of the specified rule.
	CloseAccount(account.AccountID, account.Rule) error
	// RestoreAccount opens an account that was closed by CloseAccount.
	RestoreAccount(account.AccountID) error
	ForgiveMatchFail(mid order.MatchID) (bool, error)
	// Account retrieves account info for the specified account ID.
	Account(account.AccountID) (acct *account.Account, paid, open bool)
	UserOrderStatuses(aid account.AccountID, base, quote uint32, oids []order.OrderID) ([]*db.OrderStatus, error)
	ActiveUserOrderStatuses(aid account.AccountID) ([]*db.OrderStatus, error)
	CompletedUserOrders(aid account.AccountID, N int) (oids []order.OrderID, compTimes []int64, err error)
	ExecutedCancelsForUser(aid account.AccountID, N int) (oids, targets []order.OrderID, execTimes []int64, err error)
	CompletedAndAtFaultMatchStats(aid account.AccountID, lastN int) ([]*db.MatchOutcome, error)
	PreimageStats(user account.AccountID, lastN int) ([]*db.PreimageResult, error)
	AllActiveUserMatches(aid account.AccountID) ([]*db.MatchData, error)
	MatchStatuses(aid account.AccountID, base, quote uint32, matchIDs []order.MatchID) ([]*db.MatchStatus, error)
	CreateAccount(*account.Account) (string, error)
	AccountRegAddr(account.AccountID) (string, error)
	PayAccount(account.AccountID, []byte) error
}

Storage updates and fetches account-related data from what is presumably a database.

type SwapAmounts

type SwapAmounts struct {
	Swapped    int64
	StuckLong  int64
	StuckShort int64
	Spoofed    int64
}

SwapAmounts breaks down the quantities of completed swaps in four rough categories: successfully swapped (Swapped), failed with counterparty funds locked for the long/maker lock time (StuckLong), failed with counterparty funds locked for the short/taker lock time (StuckShort), and failed to initiate swap following match with no funds locked in contracts (Spoofed).

type Violation

type Violation int32

Violation represents a specific infraction. For example, not broadcasting a swap contract transaction by the deadline as the maker.

const (
	ViolationInvalid Violation = iota - 2
	ViolationForgiven
	ViolationSwapSuccess
	ViolationPreimageMiss
	ViolationNoSwapAsMaker
	ViolationNoSwapAsTaker
	ViolationNoRedeemAsMaker
	ViolationNoRedeemAsTaker
)

func (Violation) Score

func (v Violation) Score() int32

Score returns the Violation's score, which is a representation of the relative severity of the infraction.

func (Violation) String

func (v Violation) String() string

String returns a description of the Violation.