ttxdb

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2023 License: Apache-2.0 Imports: 11 Imported by: 2

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

View Source 
const (
	// Unknown is the status of a transaction that is unknown
	Unknown = driver.Unknown
	// Pending is the status of a transaction that has been submitted to the ledger
	Pending = driver.Pending
	// Confirmed is the status of a transaction that has been confirmed by the ledger
	Confirmed = driver.Confirmed
	// Deleted is the status of a transaction that has been deleted due to a failure to commit
	Deleted = driver.Deleted
)
View Source 
const (
	// PersistenceTypeConfigKey is the key for the persistence type in the config.
	PersistenceTypeConfigKey = "token.ttxdb.persistence.type"
)

Variables

This section is empty.

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 view.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) AppendValidationRecord added in v0.3.0 

func (db *DB) AppendValidationRecord(txID string, tr []byte, meta map[string][]byte) error

AppendValidationRecord appends the given validation metadata related to the given token request and transaction id

func (*DB) GetStatus added in v0.3.0 

func (db *DB) GetStatus(txID string) (TxStatus, error)

GetStatus return the status of the given transaction id. It returns an error if no transaction with that id is found

func (*DB) GetTokenRequest added in v0.3.0 

func (db *DB) GetTokenRequest(txID string) ([]byte, error)

GetTokenRequest returns the token request bound to the passed transaction id, if available.

func (*DB) NewQueryExecutor 

func (db *DB) NewQueryExecutor() *QueryExecutor

NewQueryExecutor returns a new query executor

func (*DB) ReleaseLocks added in v0.2.0 

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 view.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 filtered by the given params.

func (*QueryExecutor) ValidationRecords added in v0.3.0 

func (qe *QueryExecutor) ValidationRecords(params QueryValidationRecordsParams) (*ValidationRecordsIterator, error)

ValidationRecords returns an iterators of validation records filtered by the given params.

type QueryTransactionsParams 

type QueryTransactionsParams = driver.QueryTransactionsParams

QueryTransactionsParams defines the parameters for querying movements

type QueryValidationRecordsParams added in v0.3.0 

type QueryValidationRecordsParams = driver.QueryValidationRecordsParams

QueryValidationRecordsParams 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

type ValidationRecord added in v0.3.0 

type ValidationRecord = driver.ValidationRecord

ValidationRecord 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 ValidationRecordsIterator added in v0.3.0 

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

ValidationRecordsIterator is an iterator over validation records

func (*ValidationRecordsIterator) Close added in v0.3.0 

func (t *ValidationRecordsIterator) Close()

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

func (*ValidationRecordsIterator) Next added in v0.3.0 

func (t *ValidationRecordsIterator) Next() (*ValidationRecord, error)

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

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

Source Files

View all Source files

Directories

Path Synopsis
db
badger
badger/keys
memory

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.