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 NewCustomeFeeManager 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

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

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

Watchdog Subsystem

TODO

Documentation

Index

• Variables
• type FeeManager
  • func New(cs modules.ConsensusSet, w modules.Wallet, persistDir string) (*FeeManager, error)
  • func NewCustomFeeManager(cs modules.ConsensusSet, w modules.Wallet, persistDir string, ...) (*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, w modules.Wallet, persistDir string) (*FeeManager, error)

New creates a new FeeManager.

func NewCustomFeeManager

func NewCustomFeeManager(cs modules.ConsensusSet, 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.