feemanager

README

FeeManager

The FeeManager is a way for developers building on top of Sia to charge a fee for the use of their product. The FeeManager is structured in a way that one siad instance can support fees from multiple applications running on top of it.

An application can request that the user be charged a fixed amount once. Applications can use this as a setup fee or can charge the user for various actions as the application is used.

Fees can be marked as recurring to indicate to the user that the fee will be charged every month. The application that is extracting the fee is still expected to register the fee each month, siad will not charge users for applications that the user is no longer using.

Subsystems

The following subsystems help the FeeManager module execute its responsibilities:

• FeeManager Subsystem
• Persistence Subsystem
• Process Fee Subsystem
• Watchdog Subsystem

FeeManager Subsystem

Key Files

• feemanager.go

The FeeManager subsystem handles the creation and shutdown of the FeeManager. Additionally this subsystem handles providing information about the FeeManager's state, such as the current fees being managed.

The FeeManager subsystem has a main FeeManager type as well as a feeManagerCommon type. The feeManagerCommon type is a share struct between the other subsystems and contains references to the other subsystems as well as the common dependencies.

Exports

• New creates a new FeeManager with default dependencies
• NewCustomFeeManager creates a new FeeManager with custom dependencies
• AddFee adds a fee to the FeeManager
• CancelFee cancels a fee
• Close closes the FeeManager
• PaidFees returns a list of fees that have been paid out by the FeeManager
• PayoutHeight returns the PayoutHeight of the FeeManager
• PendingFees returns a list of pending fees being managed by the FeeManager

Outbound Complexities

• The persist subsystem's callInitPersist method is called from NewCustomFeeManager to initialize the persistence files and/or load the persistence from disk
• The persist subsystem's callPersistFeeCancelation method is called from CancelFee to remove the fee from the FeeManager and persist the change on disk
• The persist subsystem's callPersistNewFee method is called from AddFee to add the fee to the FeeManager and persist the change on disk
• The watchdog subsystem's callFeeTracked method is called from CancelFee as a check to see if a fee can be canceled

Persistence Subsystem

Key Files

• persist.go
• persistentries.go

The persistence subsystem handles actions that update the state of the FeeManager and the ACID disk interactions for the feemanager module. To ensure disk interactions are ACID, the persistence subsystem uses an append only model with the size of data stored in the persist file header.

The persistence subsystem has two main components, the persistSubsystem and the syncCoordinator. The persistSubsystem contains the state of the FeeManager persistence and handles the inbound complexity. The syncCoordinator is solely responsible for handling the concurrent requests to sync the persist file and update the persist file header.

Inbound Complexities

• The feemanager subsystem's NewCustomFeeManager calls callInitPersist to initialize the persistence by creating or loading a persist file and initializing the logger
• The feemanager subsystem's CancelFee method calls callPersistFeeCancelation to remove a fee from the FeeManager and persists the change on disk
• The feemanager subsystem's AddFee method calls callPersistNewFee to add a fee to the FeeManager and persists the change on disk
• The process fees subsystem's threadedProcessFess method calls callPersistFeeUpdate to persist a change to a Fee's PayoutHeight on disk
• The process fees subsystem's createdAndPersistTransaction method calls callPersistTxnCreated to persist the link between feeUIDs and the transaction ID
• The watchdog subsystem's managedConfirmTransaction method calls callPersistTxnConfirmed to persist that the transaction was confirmed
• The watchdog subsystem's managedDropTransaction method calls callPersistTxnDropped to persist that the transaction was dropped

Outbound Complexities

• The watchdog subsystems's callTransactionTracked is called from applyEntryTransaction to check if a transaction is already in the watchdog
• The watchdog subsystems's callMonitorTransaction is called from applyEntryTransaction to add a transaction to the watchdog
• The watchdog subsystems's callClearTransaction is called from applyEntryTxnConfirmed to clear a transaction from the watchdog
• The watchdog subsystems's callAddFeesToTransaction is called from applyEntryTxnCreated to add fees to a transaction being monitored by the watchdog
• The watchdog subsystems's callDropTransaction is called from applyEntryTxnDropped to remove a transaction from the watchdog

Process Fees Subsystem

Key Files

• processfees.go

The process fees subsystem handles processing fees for each payout period and ensuring that the PayoutHeight's are updated. Fees are processed by creating a transaction and then submitting the transaction to the watchdog.

Outbound Complexities

• The persist subsystem's callPersistFeeUpdate method is called from threadedProcessFees to update the PayoutHeight for a fee
• The persist subsystem's callPersistTxnCreatedmethod is call from createdAndPersistTransaction to link FeeUIDs and a TxnID
• The watchdog subsystem's callMonitorTransaction method is called by createdAndPersistTransaction to add a transaction for the watchdog to monitor

Watchdog Subsystem

Key Files

• watchdog.go
• watchdogpersist.go

The watchdog subsystem handles tracking the transactions created for Fees and marking them as paid once the transactions are confirmed. The watchdog will continue to rebroadcast the transaction until the transaction is confirmed. Once a transaction is confirmed the watchdog updates the fees' PaymentComplete flag.

Inbound Complexities

• The process fees subsystem's createdAndPersistTransaction calls callMonitorTransaction to add a transaction for the watchdog to monitor
• The persistence subsystem's applyEntryTransaction calls callTransactionTracked to check if a transaction is already in the watchdog
• The persistence subsystem's applyEntryTransaction calls callMonitorTransaction to add a transaction to the watchdog
• The persistence subsystem's applyEntryTxnConfirmed calls callClearTransaction to clear a transaction from the watchdog
• The persistence subsystem's applyEntryTxnCreated calls callAddFeesToTransaction to add fees to a transaction being monitored by the watchdog
• The persistence subsystem's applyEntryTxnDropped calls callDropTransaction to remove a transaction from the watchdog
• The feemanager subsystem's CancelFee method calls callFeeTracked as a check to see if a fee can be canceled

Outbound Complexities

• The persist subsystem's callPersistTxnConfirmed method is called by managedConfirmTransaction to persist that the transaction was confirmed
• The persist subsystem's callPersistTxnDropped method is called by managedDropTransaction to persist that the transaction was dropped

Documentation

Index

• Variables
• type FeeManager
  • func New(cs modules.ConsensusSet, tp modules.TransactionPool, w modules.Wallet, ...) (*FeeManager, error)
  • func NewCustomFeeManager(cs modules.ConsensusSet, tp modules.TransactionPool, w modules.Wallet, ...) (*FeeManager, error)
  • func (fm *FeeManager) AddFee(address types.UnlockHash, amount types.Currency, appUID modules.AppUID, ...) (modules.FeeUID, error)
  • func (fm *FeeManager) CancelFee(feeUID modules.FeeUID) error
  • func (fm *FeeManager) Close() error
  • func (fm *FeeManager) PaidFees() ([]modules.AppFee, error)
  • func (fm *FeeManager) PayoutHeight() (types.BlockHeight, error)
  • func (fm *FeeManager) PendingFees() ([]modules.AppFee, error)
• type PersistHeader

Variables

var (

	// PersistFilename is the filename to be used when persisting FeeManager
	// information on disk
	PersistFilename = "feemanager.dat"

	// MetadataHeader defines the header for the persist file.
	MetadataHeader = "Fee Manager\n"

	// MetadataVersion defines the version for the persist file.
	MetadataVersion = "v1.4.9\n"
)

var (
	// ErrFeeNotFound is returned if a fee is not found in the FeeManager
	ErrFeeNotFound = errors.New("fee not found")
)

var (
	// PayoutInterval is the interval at which the payoutheight is set in the
	// future
	PayoutInterval = build.Select(build.Var{
		Standard: types.BlocksPerMonth,
		Dev:      types.BlocksPerDay,
		Testing:  types.BlocksPerHour,
	}).(types.BlockHeight)
)

Types

type FeeManager

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

FeeManager is responsible for tracking any application fees that are being charged to this siad instance

func New

func New(cs modules.ConsensusSet, tp modules.TransactionPool, w modules.Wallet, persistDir string) (*FeeManager, error)

New creates a new FeeManager.

func NewCustomFeeManager

func NewCustomFeeManager(cs modules.ConsensusSet, tp modules.TransactionPool, w modules.Wallet, persistDir string, deps modules.Dependencies) (*FeeManager, error)

NewCustomFeeManager creates a new FeeManager using custom dependencies.

func (*FeeManager) AddFee

func (fm *FeeManager) AddFee(address types.UnlockHash, amount types.Currency, appUID modules.AppUID, recurring bool) (modules.FeeUID, error)

AddFee adds a fee to the fee manager.

func (*FeeManager) CancelFee

func (fm *FeeManager) CancelFee(feeUID modules.FeeUID) error

CancelFee cancels a fee by removing it from the FeeManager's map

func (*FeeManager) Close

func (fm *FeeManager) Close() error

Close closes the FeeManager

func (*FeeManager) PaidFees

func (fm *FeeManager) PaidFees() ([]modules.AppFee, error)

PaidFees returns all the paid fees that are being tracked by the FeeManager

func (*FeeManager) PayoutHeight

func (fm *FeeManager) PayoutHeight() (types.BlockHeight, error)

PayoutHeight returns the nextPayoutHeight of the FeeManager

func (*FeeManager) PendingFees

func (fm *FeeManager) PendingFees() ([]modules.AppFee, error)

PendingFees returns all the pending fees that are being tracked by the FeeManager

type PersistHeader

type PersistHeader struct {
	// Metadata contains the persist metadata identifying the type and
	// version of the file.
	persist.Metadata

	// NextPayoutHeight is the height at which the next fee payout happens.
	NextPayoutHeight types.BlockHeight

	// LatestSyncedOffest is the latest offset that has a confirmed fsync,
	// data up to and including this point should be reliable.
	LatestSyncedOffset uint64
}

PersistHeader defines the data that goes at the head of the persist file.