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

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 := ttxDB.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 := ttxDB.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
• Variables
• type ActionType
• type Cache
• type DB
  • func GetByTMSId(sp token.ServiceProvider, tmsID token.TMSID) (*DB, error)
  • func (d *DB) AddTransactionEndorsementAck(txID string, id token.Identity, sigma []byte) error
  • func (d *DB) AppendTransactionRecord(req *token.Request) error
  • func (d *DB) AppendValidationRecord(txID string, tokenRequest []byte, meta map[string][]byte, ...) error
  • func (d *DB) GetStatus(txID string) (TxStatus, string, error)
  • func (d *DB) GetTokenRequest(txID string) ([]byte, error)
  • func (d *DB) GetTransactionEndorsementAcks(txID string) (map[string][]byte, error)
  • func (d *DB) SetStatus(ctx context.Context, txID string, status driver.TxStatus, message string) error
  • func (d *DB) TokenRequests(params QueryTokenRequestsParams) (driver.TokenRequestIterator, error)
  • func (d *DB) Transactions(params QueryTransactionsParams) (driver.TransactionIterator, error)
  • func (d *DB) ValidationRecords(params QueryValidationRecordsParams) (*ValidationRecordsIterator, error)
• type Holder
  • func NewHolder(drivers []db.NamedDriver[driver.TTXDBDriver]) *Holder
• type Manager
• type MovementRecord
  • func Movements(record *token.AuditRecord, created time.Time) (mv []MovementRecord, err error)
• type QueryTokenRequestsParams
• type QueryTransactionsParams
• type QueryValidationRecordsParams
• type TransactionIterator
  • func (t *TransactionIterator) Close()
  • func (t *TransactionIterator) Next() (*TransactionRecord, error)
• type TransactionRecord
  • func TransactionRecords(record *token.AuditRecord, timestamp time.Time) (txs []TransactionRecord, err error)
• type TxStatus
• type ValidationRecord
• type ValidationRecordsIterator
  • func (t *ValidationRecordsIterator) Close()
  • func (t *ValidationRecordsIterator) Next() (*ValidationRecord, error)
• type Wallet

Constants

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
)

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

Variables

var TxStatusMessage = driver.TxStatusMessage

TxStatusMessage maps TxStatus to string

Types

type ActionType

type ActionType = driver.ActionType

ActionType is the type of action performed by a transaction.

type Cache

type Cache interface {
	Get(key string) ([]byte, bool)
	Add(key string, value []byte)
	Delete(key string)
}

type DB

type DB struct {
	*common.StatusSupport
	// contains filtered or unexported fields
}

DB is a database that stores token transactions related information

func GetByTMSId

func GetByTMSId(sp token.ServiceProvider, tmsID token.TMSID) (*DB, error)

func (*DB) AddTransactionEndorsementAck

func (d *DB) AddTransactionEndorsementAck(txID string, id token.Identity, sigma []byte) error

AddTransactionEndorsementAck records the signature of a given endorser for a given transaction

func (*DB) AppendTransactionRecord

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

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

func (*DB) AppendValidationRecord

func (d *DB) AppendValidationRecord(txID string, tokenRequest []byte, meta map[string][]byte, ppHash driver2.PPHash) error

AppendValidationRecord appends the given validation metadata related to the given transaction id

func (*DB) GetStatus

func (d *DB) GetStatus(txID string) (TxStatus, string, 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

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

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

func (*DB) GetTransactionEndorsementAcks

func (d *DB) GetTransactionEndorsementAcks(txID string) (map[string][]byte, error)

GetTransactionEndorsementAcks returns the endorsement signatures for the given transaction id

func (*DB) SetStatus

func (d *DB) SetStatus(ctx context.Context, txID string, status driver.TxStatus, message string) error

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

func (*DB) TokenRequests

func (d *DB) TokenRequests(params QueryTokenRequestsParams) (driver.TokenRequestIterator, error)

TokenRequests returns an iterator over the token requests matching the passed params

func (*DB) Transactions

func (d *DB) Transactions(params QueryTransactionsParams) (driver.TransactionIterator, error)

Transactions returns an iterators of transaction records filtered by the given params.

func (*DB) ValidationRecords

func (d *DB) ValidationRecords(params QueryValidationRecordsParams) (*ValidationRecordsIterator, error)

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

type Holder

type Holder = db.DriverHolder[*DB, driver.TokenTransactionDB, driver.TTXDBDriver]

func NewHolder

func NewHolder(drivers []db.NamedDriver[driver.TTXDBDriver]) *Holder

type Manager

type Manager = db.Manager[*DB, driver.TokenTransactionDB, driver.TTXDBDriver]

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.

func Movements

func Movements(record *token.AuditRecord, created time.Time) (mv []MovementRecord, err error)

Movements converts an AuditRecord to MovementRecords for storage in the database. A positive movement Amount means incoming tokens, and negative means outgoing tokens from the enrollment ID.

type QueryTokenRequestsParams

type QueryTokenRequestsParams = driver.QueryTokenRequestsParams

QueryTokenRequestsParams defines the parameters for querying token requests

type QueryTransactionsParams

type QueryTransactionsParams = driver.QueryTransactionsParams

QueryTransactionsParams defines the parameters for querying movements

type QueryValidationRecordsParams

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.

func TransactionRecords

func TransactionRecords(record *token.AuditRecord, timestamp time.Time) (txs []TransactionRecord, err error)

TransactionRecords is a pure function that converts an AuditRecord for storage in the database.

type TxStatus

type TxStatus = driver.TxStatus

TxStatus is the status of a transaction

type ValidationRecord

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

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

ValidationRecordsIterator is an iterator over validation records

func (*ValidationRecordsIterator) Close

func (t *ValidationRecordsIterator) Close()

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

func (*ValidationRecordsIterator) Next

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