ttxdb

README

Token Transactions DB

The Token Transactions DB is a database of audited records. It is used to track the history of audited events. In particular, it is used to track payments, holdings, and transactions of any business party identified by a unique enrollment ID.

Getting Started

Each Token Transactions DB is bound to a wallet to be uniquely identifiable. To get the instance of the Token Transactions DB bound to a given wallet, use the following:

   ttxDB := ttxdb.Get(context, wallet)

Append Token Requests

A Token Request describes a set of token operations in a backend agnostic language. A Token Request can be assembled directly using the Token API or by using service packages like ttx.

Once a Token Request is assembled, it can be appended to the Token Transactions DB as follows:

	if err := ttxDB.Append(tokenRequest); err != nil {
		return errors.WithMessagef(err, "failed appending audit records for tx [%s]", tx.ID())
	}

The above code will extract the movement records and the transaction records from the Token Request and append them to the Token Transactions DB.

It is also possible to append just the transaction records corresponding to a given Token Request as follows:

	if err := ttxDB.AppendTransactionRecord(tokenRequest); err != nil {
		return errors.WithMessagef(err, "failed appending audit records for tx [%s]", tx.ID())
	}

Payments

To get a list of payments filtered by given criteria, one must first obtain a query executor like this:

    qe := ttxDB.NewQueryExecutor()
    defer aqe.Done() // Don't forget to close the query executor

Now, we are ready to perform payment queries. The following example shows how to retrieve the total amount of last 10 payments made by a given business party, identified by the corresponding enrollment ID, for a given token type.

    filter := qe.NewPaymentsFilter()
    filter, err = filter.ByEnrollmentId(eID).ByType(tokenType).Last(10).Execute()
    if err != nil {
        return errors.WithMessagef(err, "failed getting payments for enrollment id [%s] and token type [%s]", eID, tokenType)
    }
    sumLastPayments := filter.Sum()

Holdings

The following example shows how to retrieve the current holding of a given token type for a given business party. Recall that the current holding is equal to the difference between inbound and outbound transactions over the entire history.

    filter := qe.NewHoldingsFilter()
    filter, err = filter.ByEnrollmentId(eID).ByType(tokenType).Execute()
    if err != nil {
        return errors.WithMessagef(err, "failed getting holdings for enrollment id [%s] and token type [%s]", eID, tokenType)
    }
    holding := filter.Sum()

Transaction Records

The following example shows how to retrieve the total amount of transactions for a given business party,

	it, err := qe.Transactions(ttxdb.QueryTransactionsParams{From: p.From, To: p.To})
	if err != nil {
		return errors.WithMessagef(err, "failed getting transactions for enrollment id [%s]", eID)
	}
	defer it.Close()

	for {
		tx, err := it.Next()
		if err != nil {
			return errors.WithMessagef(err, "failed getting transactions for enrollment id [%s]", eID)
        }
		if tx == nil {
			break
		}
		fmt.Printf("Transaction: %s\n", tx.ID())
	}

Documentation

Index

• Constants
• func Drivers() []string
• func Register(name string, driver driver.Driver)
• type ActionType
• type DB
  • func Get(sp view2.ServiceProvider, w Wallet) *DB
  • func (db *DB) AcquireLocks(anchor string, eIDs ...string) error
  • func (db *DB) Append(req *token.Request) error
  • func (db *DB) AppendTransactionRecord(req *token.Request) error
  • func (db *DB) NewQueryExecutor() *QueryExecutor
  • func (db *DB) ReleaseLocks(anchor string)
  • func (db *DB) SetStatus(txID string, status TxStatus) error
• type HoldingsFilter
  • func (f *HoldingsFilter) ByEnrollmentId(id string) *HoldingsFilter
  • func (f *HoldingsFilter) ByType(tokenType string) *HoldingsFilter
  • func (f *HoldingsFilter) Execute() (*HoldingsFilter, error)
  • func (f *HoldingsFilter) Sum() *big.Int
• type Manager
  • func NewManager(sp view2.ServiceProvider, driver string) *Manager
  • func (cm *Manager) DB(w Wallet) (*DB, error)
• type MovementRecord
• type PaymentsFilter
  • func (f *PaymentsFilter) ByEnrollmentId(id string) *PaymentsFilter
  • func (f *PaymentsFilter) ByType(tokenType string) *PaymentsFilter
  • func (f *PaymentsFilter) Execute() (*PaymentsFilter, error)
  • func (f *PaymentsFilter) Last(num int) *PaymentsFilter
  • func (f *PaymentsFilter) Sum() *big.Int
• type QueryExecutor
  • func (qe *QueryExecutor) Done()
  • func (qe *QueryExecutor) NewHoldingsFilter() *HoldingsFilter
  • func (qe *QueryExecutor) NewPaymentsFilter() *PaymentsFilter
  • func (qe *QueryExecutor) Transactions(params QueryTransactionsParams) (*TransactionIterator, error)
• type QueryTransactionsParams
• type TransactionIterator
  • func (t *TransactionIterator) Close()
  • func (t *TransactionIterator) Next() (*TransactionRecord, error)
• type TransactionRecord
• type TxStatus
• type Wallet

Constants

const (
	// PersistenceTypeConfigKey is the key for the persistence type in the config.
	PersistenceTypeConfigKey = "token.ttxdb.persistence.type"
)

Functions

func Drivers

func Drivers() []string

Drivers returns a sorted list of the names of the registered drivers.

func Register

func Register(name string, driver driver.Driver)

Register makes a DB driver available by the provided name. If Register is called twice with the same name or if driver is nil, it panics.

Types

type ActionType

type ActionType = driver.ActionType

ActionType is the type of action performed by a transaction.

const (
	// Issue is the action type for issuing tokens.
	Issue ActionType = iota
	// Transfer is the action type for transferring tokens.
	Transfer
	// Redeem is the action type for redeeming tokens.
	Redeem
)

type DB

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

DB is a database that stores token transactions related information

func Get

func Get(sp view2.ServiceProvider, w Wallet) *DB

Get returns the DB for the given wallet. Nil might be returned if the wallet is not found or an error occurred.

func (*DB) AcquireLocks

func (db *DB) AcquireLocks(anchor string, eIDs ...string) error

AcquireLocks acquires locks for the passed anchor and enrollment ids. This can be used to prevent concurrent read/write access to the audit records of the passed enrollment ids.

func (*DB) Append

func (db *DB) Append(req *token.Request) error

Append appends send and receive movements, and transaction records corresponding to the passed token request

func (*DB) AppendTransactionRecord

func (db *DB) AppendTransactionRecord(req *token.Request) error

AppendTransactionRecord appends the transaction records corresponding to the passed token request.

func (*DB) NewQueryExecutor

func (db *DB) NewQueryExecutor() *QueryExecutor

NewQueryExecutor returns a new query executor

func (*DB) ReleaseLocks

func (db *DB) ReleaseLocks(anchor string)

ReleaseLocks releases the locks associated to the passed anchor

func (*DB) SetStatus

func (db *DB) SetStatus(txID string, status TxStatus) error

SetStatus sets the status of the audit records with the passed transaction id to the passed status

type HoldingsFilter

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

func (*HoldingsFilter) ByEnrollmentId

func (f *HoldingsFilter) ByEnrollmentId(id string) *HoldingsFilter

func (*HoldingsFilter) ByType

func (f *HoldingsFilter) ByType(tokenType string) *HoldingsFilter

func (*HoldingsFilter) Execute

func (f *HoldingsFilter) Execute() (*HoldingsFilter, error)

func (*HoldingsFilter) Sum

func (f *HoldingsFilter) Sum() *big.Int

type Manager

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

Manager handles the databases

func NewManager

func NewManager(sp view2.ServiceProvider, driver string) *Manager

NewManager creates a new DB manager. The driver is the name of the driver to use. If the driver is not supported, an error is returned. If the driver is not specified, the driver is taken from the configuration. If the configuration is not specified, the default driver is used.

func (*Manager) DB

func (cm *Manager) DB(w Wallet) (*DB, error)

DB returns a DB for the given wallet

type MovementRecord

type MovementRecord = driver.MovementRecord

MovementRecord is a record of a movement of assets. Given a Token Transaction, a movement record is created for each enrollment ID that participated in the transaction and each token type that was transferred. The movement record contains the total amount of the token type that was transferred to/from the enrollment ID in a given token transaction.

type PaymentsFilter

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

PaymentsFilter is a filter for payments.

func (*PaymentsFilter) ByEnrollmentId

func (f *PaymentsFilter) ByEnrollmentId(id string) *PaymentsFilter

ByEnrollmentId add an enrollment id to the filter.

func (*PaymentsFilter) ByType

func (f *PaymentsFilter) ByType(tokenType string) *PaymentsFilter

func (*PaymentsFilter) Execute

func (f *PaymentsFilter) Execute() (*PaymentsFilter, error)

func (*PaymentsFilter) Last

func (f *PaymentsFilter) Last(num int) *PaymentsFilter

func (*PaymentsFilter) Sum

func (f *PaymentsFilter) Sum() *big.Int

type QueryExecutor

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

QueryExecutor executors queries against the DB

func (*QueryExecutor) Done

func (qe *QueryExecutor) Done()

Done closes the query executor. It must be called when the query executor is no longer needed.s

func (*QueryExecutor) NewHoldingsFilter

func (qe *QueryExecutor) NewHoldingsFilter() *HoldingsFilter

NewHoldingsFilter returns a programmable filter over the holdings owned by enrollment IDs.

func (*QueryExecutor) NewPaymentsFilter

func (qe *QueryExecutor) NewPaymentsFilter() *PaymentsFilter

NewPaymentsFilter returns a programmable filter over the payments sent or received by enrollment IDs.

func (*QueryExecutor) Transactions

func (qe *QueryExecutor) Transactions(params QueryTransactionsParams) (*TransactionIterator, error)

Transactions returns an iterators of transaction records in the given time internal.

type QueryTransactionsParams

type QueryTransactionsParams = driver.QueryTransactionsParams

QueryTransactionsParams defines the parameters for querying movements

type TransactionIterator

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

TransactionIterator is an iterator over transaction records

func (*TransactionIterator) Close

func (t *TransactionIterator) Close()

Close closes the iterator. It must be called when done with the iterator.

func (*TransactionIterator) Next

func (t *TransactionIterator) Next() (*TransactionRecord, error)

Next returns the next transaction record, if any. It returns nil, nil if there are no more records.

type TransactionRecord

type TransactionRecord = driver.TransactionRecord

TransactionRecord is a more finer-grained version of a movement record. Given a Token Transaction, for each token action in the Token Request, a transaction record is created for each unique enrollment ID found in the outputs. The transaction record contains the total amount of the token type that was transferred to/from that enrollment ID in that action.

type TxStatus

type TxStatus = driver.TxStatus

TxStatus is the status of a transaction

const (
	// Pending is the status of a transaction that has been submitted to the ledger
	Pending TxStatus = "Pending"
	// Confirmed is the status of a transaction that has been confirmed by the ledger
	Confirmed TxStatus = "Confirmed"
	// Deleted is the status of a transaction that has been deleted due to a failure to commit
	Deleted TxStatus = "Deleted"
)

type Wallet

type Wallet interface {
	// ID returns the wallet ID
	ID() string
	// TMS returns the TMS of the wallet
	TMS() *token.ManagementService
}

Wallet models a wallet