compensation

package
v1.110.1 Latest Latest
Warning

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

 Go to latest Published: Aug 6, 2024 License: AGPL-3.0 Imports: 13 Imported by: 1

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// DefaultWithheldPercents contains the standard withholding schedule.
	DefaultWithheldPercents = []int{75, 75, 75, 50, 50, 50, 25, 25, 25}

	// DefaultRates contains the standard operation rates.
	DefaultRates = Rates{
		AtRestGBHours: RequireRateFromString("0.00000205"),
		GetTB:         RequireRateFromString("20.00"),
		PutTB:         RequireRateFromString("0.00"),
		GetRepairTB:   RequireRateFromString("10.00"),
		PutRepairTB:   RequireRateFromString("0.00"),
		GetAuditTB:    RequireRateFromString("10.0"),
	}
)
View Source 
var (
	// Error wraps common errors from this package.
	Error = errs.Class("compensation")
)

Functions

func NodeWithheldPercent 

func NodeWithheldPercent(withheldPercents []int, nodeCreatedAt, endDate time.Time) (int, bool)

NodeWithheldPercent returns the percentage that should be withheld and if the node is still in the withholding period based on its creation date.

func PercentOf 

func PercentOf(v, percent decimal.Decimal) decimal.Decimal

PercentOf sets v to a percentage of itself. For example if v was 200 and percent was 20, v would be set to 40.

func WriteInvoices 

func WriteInvoices(w io.Writer, invoices []Invoice) error

WriteInvoices writes a collection of Invoice values in CSV form.

func WritePayments 

func WritePayments(w io.Writer, payments []Payment) error

WritePayments writes a collection of payments in CSV form.

Types

type Code 

type Code string

Code is an enumeration of states some billing entry could be in. 

const (
	// Disqualified is included if the node is disqualified.
	Disqualified Code = "D"

	// Sanctioned is included if payment is withheld because the node is in
	// a sanctioned country.
	Sanctioned Code = "S"

	// No1099 is included if payment is withheld because the node has not
	// filed a 1099 and payment would put it over limits.
	No1099 Code = "T"

	// InWithholding is included if the node is in the initial held amount
	// period.
	InWithholding Code = "E"

	// GracefulExit is included if the node has gracefully exited.
	GracefulExit Code = "X"

	// Offline is included if the node's last contact success is before the starting
	// period.
	Offline Code = "O"

	// Bonus is included if the node has qualified for special bonus circumstances,
	// chosen month by month by the crypthopper-go accountant prepare step.
	Bonus Code = "B"
)

func CodeFromString 

func CodeFromString(s string) (Code, error)

CodeFromString parses the string into a Code.

type Codes 

type Codes []Code

Codes represents a collection of Code values.

func CodesFromString 

func CodesFromString(s string) (codes Codes, err error)

CodesFromString parses the list of codes into a Codes.

func (Codes) MarshalCSV 

func (codes Codes) MarshalCSV() (string, error)

MarshalCSV does the custom marshaling of Codes.

func (Codes) String 

func (codes Codes) String() string

String serializes the Codes into a colon separated list.

func (*Codes) UnmarshalCSV 

func (codes *Codes) UnmarshalCSV(s string) error

UnmarshalCSV does the custom unmarshaling of Codes.

type Config 

type Config struct {
	Rates struct {
		AtRestGBHours Rate `user:"true" help:"rate for data at rest per GB/hour" default:"0.00000208"`
		GetTB         Rate `user:"true" help:"rate for egress bandwidth per TB" default:"20.00"`
		PutTB         Rate `user:"true" help:"rate for ingress bandwidth per TB" default:"0"`
		GetRepairTB   Rate `user:"true" help:"rate for repair egress bandwidth per TB" default:"10.00"`
		PutRepairTB   Rate `user:"true" help:"rate for repair ingress bandwidth per TB" default:"0"`
		GetAuditTB    Rate `user:"true" help:"rate for audit egress bandwidth per TB" default:"10.00"`
	}
	WithheldPercents Percents `user:"true" help:"comma separated monthly withheld percentage rates" default:"75,75,75,50,50,50,25,25,25,0,0,0,0,0,0"`
	DisposePercent   int      `user:"true" help:"percent of held amount disposed to node after leaving withheld" default:"50"`
}

Config contains configuration for the calculations this package performs.

type DB 

type DB interface {
	// QueryTotalAmounts queries the WithheldAmounts for the given nodeID.
	QueryTotalAmounts(ctx context.Context, nodeID storj.NodeID) (TotalAmounts, error)

	// RecordPeriod records a set of paystubs and payments for some time period.
	RecordPeriod(ctx context.Context, paystubs []Paystub, payments []Payment) error

	// RecordPayments records one off individual payments.
	RecordPayments(ctx context.Context, payments []Payment) error
}

DB is the interface we need to source the data to calculate compensation.

type Invoice 

type Invoice struct {
	Period             Period             `csv:"period"`               // The payment period
	NodeID             NodeID             `csv:"node-id"`              // The node ID
	NodeCreatedAt      UTCDate            `csv:"node-created-at"`      // When the node was created
	NodeDisqualified   *UTCDate           `csv:"node-disqualified"`    // When and if the node was disqualified
	NodeGracefulExit   *UTCDate           `csv:"node-gracefulexit"`    // When and if the node finished a graceful exit
	NodeWallet         string             `csv:"node-wallet"`          // The node's wallet address
	NodeWalletFeatures WalletFeatures     `csv:"node-wallet-features"` // The node's wallet features
	NodeAddress        string             `csv:"node-address"`         // The node's TODO
	NodeLastIP         string             `csv:"node-last-ip"`         // The last known ip the node had
	Codes              Codes              `csv:"codes"`                // Any codes providing context to the invoice
	UsageAtRest        float64            `csv:"usage-at-rest"`        // Byte-hours provided during the payment period
	UsageGet           int64              `csv:"usage-get"`            // Number of bytes served in GET requests
	UsagePut           int64              `csv:"usage-put"`            // Number of bytes served in PUT requests
	UsageGetRepair     int64              `csv:"usage-get-repair"`     // Number of bytes served in GET_REPAIR requests
	UsagePutRepair     int64              `csv:"usage-put-repair"`     // Number of bytes served in PUT_REPAIR requests
	UsageGetAudit      int64              `csv:"usage-get-audit"`      // Number of bytes served in GET_AUDIT requests
	CompAtRest         currency.MicroUnit `csv:"comp-at-rest"`         // Compensation for usage-at-rest
	CompGet            currency.MicroUnit `csv:"comp-get"`             // Compensation for usage-get
	CompPut            currency.MicroUnit `csv:"comp-put"`             // Compensation for usage-put
	CompGetRepair      currency.MicroUnit `csv:"comp-get-repair"`      // Compensation for usage-get-repair
	CompPutRepair      currency.MicroUnit `csv:"comp-put-repair"`      // Compensation for usage-put-repair
	CompGetAudit       currency.MicroUnit `csv:"comp-get-audit"`       // Compensation for usage-get-audit
	SurgePercent       int64              `csv:"surge-percent"`        // Surge percent used to calculate compensation, or 0 if no surge
	Owed               currency.MicroUnit `csv:"owed"`                 // Amount we intend to pay to the node (sum(comp-*) - held + disposed)
	Held               currency.MicroUnit `csv:"held"`                 // Amount held from sum(comp-*) for this period
	Disposed           currency.MicroUnit `csv:"disposed"`             // Amount of owed that is due to graceful-exit or held period ending
	TotalHeld          currency.MicroUnit `csv:"total-held"`           // Total amount ever held from the node
	TotalDisposed      currency.MicroUnit `csv:"total-disposed"`       // Total amount ever disposed to the node
	TotalPaid          currency.MicroUnit `csv:"total-paid"`           // Total amount ever paid to the node (but not necessarily dispensed)
	TotalDistributed   currency.MicroUnit `csv:"total-distributed"`    // Total amount ever distributed to the node (always less than or equal to paid)
}

Invoice holds the calculations for the amount required to pay to a node for a given pay period.

func ReadInvoices 

func ReadInvoices(r io.Reader) ([]Invoice, error)

ReadInvoices reads a collection of Invoice values in CSV form.

func (*Invoice) MergeNodeInfo 

func (invoice *Invoice) MergeNodeInfo(nodeInfo NodeInfo) error

MergeNodeInfo updates the fields representing the node information into the invoice.

func (*Invoice) MergeStatement 

func (invoice *Invoice) MergeStatement(statement Statement) error

MergeStatement updates the fields representing the calculation of the payment amounts into the invoice.

type NodeID 

type NodeID storj.NodeID

NodeID is a wrapper type around storj.NodeID that implements CSV helpers.

func (NodeID) Bytes 

func (nodeID NodeID) Bytes() []byte

Bytes calls the underlying type's Bytes function.

func (NodeID) MarshalCSV 

func (nodeID NodeID) MarshalCSV() (string, error)

MarshalCSV writes the storj.NodeID into a CSV entry.

func (NodeID) String 

func (nodeID NodeID) String() string

String calls the underlying type's String function.

func (*NodeID) UnmarshalCSV 

func (nodeID *NodeID) UnmarshalCSV(s string) error

UnmarshalCSV reads the csv entry into a storj.NodeID.

type NodeInfo 

type NodeInfo struct {
	ID                 storj.NodeID
	CreatedAt          time.Time
	LastContactSuccess time.Time
	Disqualified       *time.Time
	GracefulExit       *time.Time
	UsageAtRest        float64
	UsageGet           int64
	UsagePut           int64
	UsageGetRepair     int64
	UsagePutRepair     int64
	UsageGetAudit      int64
	TotalHeld          currency.MicroUnit
	TotalDisposed      currency.MicroUnit
	TotalPaid          currency.MicroUnit
	TotalDistributed   currency.MicroUnit
}

NodeInfo contains all of the information about a node and the operations it performed in some period.

type Payment 

type Payment struct {
	Period  Period             `csv:"period"`
	NodeID  NodeID             `csv:"node-id"`
	Amount  currency.MicroUnit `csv:"amount"`
	Receipt *string            `csv:"receipt"`
	Notes   *string            `csv:"notes"`
}

Payment represents an actual payment that happened.

func LoadPayments 

func LoadPayments(path string) ([]Payment, error)

LoadPayments loads a collection of Payments from a file on disk containing them in CSV form.

func ReadPayments 

func ReadPayments(r io.Reader) ([]Payment, error)

ReadPayments reads a collection of Payments in CSV form.

type Paystub 

type Paystub struct {
	Period         Period             `csv:"period"`
	NodeID         NodeID             `csv:"node-id"`
	Codes          Codes              `csv:"codes"`
	UsageAtRest    float64            `csv:"usage-at-rest"`
	UsageGet       int64              `csv:"usage-get"`
	UsagePut       int64              `csv:"usage-put"`
	UsageGetRepair int64              `csv:"usage-get-repair"`
	UsagePutRepair int64              `csv:"usage-put-repair"`
	UsageGetAudit  int64              `csv:"usage-get-audit"`
	CompAtRest     currency.MicroUnit `csv:"comp-at-rest"`
	CompGet        currency.MicroUnit `csv:"comp-get"`
	CompPut        currency.MicroUnit `csv:"comp-put"`
	CompGetRepair  currency.MicroUnit `csv:"comp-get-repair"`
	CompPutRepair  currency.MicroUnit `csv:"comp-put-repair"`
	CompGetAudit   currency.MicroUnit `csv:"comp-get-audit"`
	SurgePercent   int64              `csv:"surge-percent"`
	Owed           currency.MicroUnit `csv:"owed"`
	Held           currency.MicroUnit `csv:"held"`
	Disposed       currency.MicroUnit `csv:"disposed"`
	Paid           currency.MicroUnit `csv:"paid"`
	Distributed    currency.MicroUnit `csv:"distributed"`
}

Paystub contains the basic information about a payment that is to be made.

func LoadPaystubs 

func LoadPaystubs(path string) ([]Paystub, error)

LoadPaystubs loads a collection of Paystubs in CSV form from the provided file.

func ReadPaystubs 

func ReadPaystubs(r io.Reader) ([]Paystub, error)

ReadPaystubs reads a collection of Paystubs in CSV form.

type Percents 

type Percents []int

Percents is used to hold a list of percentages, typically for the withheld schedule.

func (*Percents) Set 

func (percents *Percents) Set(value string) error

Set implements pflag.Value by parsing a comma separated list of percents.

func (Percents) String 

func (percents Percents) String() string

String formats the percentages.

func (Percents) Type 

func (percents Percents) Type() string

Type returns the type of the pflag.Value.

type Period 

type Period struct {
	Year  int
	Month time.Month
}

Period represents a monthly payment period.

func PeriodFromString 

func PeriodFromString(s string) (Period, error)

PeriodFromString parses the YYYY-MM string into a Period.

func PeriodFromTime 

func PeriodFromTime(t time.Time) Period

PeriodFromTime takes a time.Time and returns a Period that contains it.

func (Period) EndDateExclusive 

func (p Period) EndDateExclusive() time.Time

EndDateExclusive returns a time.Time that is greater than any time in the period.

func (Period) MarshalCSV 

func (p Period) MarshalCSV() (string, error)

MarshalCSV returns the CSV form of the Period.

func (Period) StartDate 

func (p Period) StartDate() time.Time

StartDate returns a time.Time that is less than or equal to any time in the period.

func (Period) String 

func (p Period) String() string

String outputs the YYYY-MM form of the payment period.

func (*Period) UnmarshalCSV 

func (p *Period) UnmarshalCSV(s string) error

UnmarshalCSV reads the Period in CSV form.

type PeriodInfo 

type PeriodInfo struct {
	// Period is the period.
	Period Period

	// Nodes is usage and other related information for nodes for this period.
	Nodes []NodeInfo

	// Rates is the compensation rates for different operations. If nil, the
	// default rates are used.
	Rates *Rates

	// WithheldPercents is the percent to withhold from the total, after surge
	// adjustments, for each month in the node's lifetime. For example, to
	// withhold 75% in the first month, 50% in the second month, 0% in the third
	// month and to leave withheld thereafter, set to [75,50,0]. If nil,
	// DefaultWithheldPercents is used.
	WithheldPercents []int

	// DisposePercent is the percent to dispose to the node after it has left
	// withholding. The remaining amount is kept until the node performs a graceful
	// exit.
	DisposePercent int

	// SurgePercent is the percent to adjust final amounts owed. For example,
	// to pay 150%, set to 150. Zero means no surge.
	SurgePercent int64
}

PeriodInfo contains configuration about the payment info to generate the statements.

type Rate 

type Rate decimal.Decimal

Rate is a wrapper type around a decimal.Decimal.

func RateFromString 

func RateFromString(value string) (Rate, error)

RateFromString parses the string form of the rate into a Rate.

func RequireRateFromString 

func RequireRateFromString(s string) Rate

RequireRateFromString parses the Rate from the string or panics.

func (*Rate) Set 

func (rate *Rate) Set(s string) error

Set updates the Rate to be equal to the parsed string.

func (Rate) String 

func (rate Rate) String() string

String returns the string form of the Rate.

func (Rate) Type 

func (rate Rate) Type() string

Type returns a unique string representing the type of the Rate.

type Rates 

type Rates struct {
	AtRestGBHours Rate // For data at rest in dollars per gigabyte-hour.
	GetTB         Rate // For data the node has sent for reads in dollars per terabyte.
	PutTB         Rate // For data the node has received for writes in dollars per terabyte.
	GetRepairTB   Rate // For data the node has sent for repairs in dollars per terabyte.
	PutRepairTB   Rate // For data the node has received for repairs in dollars per terabyte.
	GetAuditTB    Rate // For data the node has sent for audits in dollars per terabyte.
}

Rates configures the payment rates for network operations.

type Statement 

type Statement struct {
	NodeID       storj.NodeID
	Codes        Codes
	AtRest       currency.MicroUnit
	Get          currency.MicroUnit
	Put          currency.MicroUnit
	GetRepair    currency.MicroUnit
	PutRepair    currency.MicroUnit
	GetAudit     currency.MicroUnit
	SurgePercent int64
	Owed         currency.MicroUnit
	Held         currency.MicroUnit
	Disposed     currency.MicroUnit
}

Statement is the computed amounts and codes from a node.

func GenerateStatements 

func GenerateStatements(info PeriodInfo) ([]Statement, error)

GenerateStatements generates all of the Statements for the given PeriodInfo.

type TotalAmounts added in v1.21.3 

type TotalAmounts struct {
	TotalHeld        currency.MicroUnit // portion from owed that was held back
	TotalDisposed    currency.MicroUnit // portion from held back that went into paid
	TotalPaid        currency.MicroUnit // earned amount that is available to be distributed
	TotalDistributed currency.MicroUnit // amount actually transferred to the operator
}

TotalAmounts holds the amounts held and disposed.

Invariants: 

TotalHeld >= TotalDisposed
TotalPaid >= TotalDisposed
TotalPaid >= TotalDistributed (we may distribute less due to minimum payout threshold)

type UTCDate 

type UTCDate time.Time

UTCDate is a wrapper type around time.Time that implements CSV helpers.

func (UTCDate) MarshalCSV 

func (date UTCDate) MarshalCSV() (string, error)

MarshalCSV writes out a CSV row containing the YYYY-MM-DD of the time.

func (UTCDate) String 

func (date UTCDate) String() string

String formats the date into YYYY-MM-DD.

func (*UTCDate) UnmarshalCSV 

func (date *UTCDate) UnmarshalCSV(s string) error

UnmarshalCSV reads the YYYY-MM-DD date into the date.

type WalletFeatures added in v1.24.2 

type WalletFeatures []string

WalletFeatures represents wallet features list.

func DecodeWalletFeatures added in v1.24.2 

func DecodeWalletFeatures(s string) (WalletFeatures, error)

DecodeWalletFeatures decodes wallet features list string separated by "|".

func (WalletFeatures) MarshalCSV added in v1.24.2 

func (features WalletFeatures) MarshalCSV() (string, error)

MarshalCSV returns the CSV form of the WalletFeatures.

func (WalletFeatures) String added in v1.24.2 

func (features WalletFeatures) String() string

String outputs .

func (*WalletFeatures) UnmarshalCSV added in v1.24.2 

func (features *WalletFeatures) UnmarshalCSV(s string) error

UnmarshalCSV reads the WalletFeatures in CSV form.

Source Files

View all Source files

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.