Documentation
¶
Index ¶
- Variables
- func NodeWithheldPercent(withheldPercents []int, nodeCreatedAt, endDate time.Time) (int, bool)
- func PercentOf(v, percent decimal.Decimal) decimal.Decimal
- func WriteInvoices(w io.Writer, invoices []Invoice) error
- func WritePayments(w io.Writer, payments []Payment) error
- type Code
- type Codes
- type Config
- type DB
- type Invoice
- type NodeID
- type NodeInfo
- type Payment
- type Paystub
- type Percents
- type Period
- type PeriodInfo
- type Rate
- type Rates
- type Statement
- type TotalAmounts
- type UTCDate
- type WalletFeatures
Constants ¶
This section is empty.
Variables ¶
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"),
}
)
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.
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.
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.