storj/satellite/payments/tokens.go
paul cannon a16aecfa96 satellite/payments: specialized type for monetary amounts
Why: big.Float is not an ideal type for dealing with monetary amounts,
because no matter how high the precision, some non-integer decimal
values can not be represented exactly in base-2 floating point. Also,
storing gob-encoded big.Float values in the database makes it very hard
to use those values in meaningful queries, making it difficult to do
any sort of analysis on billing.

For better accuracy, then, we can just represent monetary values as
integers (in whatever base units are appropriate for the currency). For
example, STORJ tokens or Bitcoins can not be split into pieces smaller
than 10^-8, so we can store amounts of STORJ or BTC with precision
simply by moving the decimal point 8 digits to the right. For USD values
(assuming we don't want to deal with fractional cents), we can move the
decimal point 2 digits to the right.

To make it easier and less error-prone to deal with the math involved, I
introduce here a new type, monetary.Amount, instances of which have an
associated value _and_ a currency.

Change-Id: I03395d52f0e2473cf301361f6033722b54640265
2021-09-28 23:27:44 +00:00

89 lines
2.6 KiB
Go

// Copyright (C) 2019 Storj Labs, Inc.
// See LICENSE for copying information.
package payments
import (
"context"
"time"
"github.com/shopspring/decimal"
"storj.io/common/uuid"
"storj.io/storj/satellite/payments/monetary"
)
// StorjTokens defines all payments STORJ token related functionality.
//
// architecture: Service
type StorjTokens interface {
// Deposit creates deposit transaction for specified amount in cents.
Deposit(ctx context.Context, userID uuid.UUID, amount int64) (*Transaction, error)
// ListTransactionInfos returns all transactions associated with user.
ListTransactionInfos(ctx context.Context, userID uuid.UUID) ([]TransactionInfo, error)
// ListDepositBonuses returns all deposit bonuses associated with user.
ListDepositBonuses(ctx context.Context, userID uuid.UUID) ([]DepositBonus, error)
}
// TransactionStatus defines allowed statuses
// for deposit transactions.
type TransactionStatus string
// String returns string representation of transaction status.
func (status TransactionStatus) String() string {
return string(status)
}
const (
// TransactionStatusPaid is a transaction which successfully received required funds.
TransactionStatusPaid TransactionStatus = "paid"
// TransactionStatusPending is a transaction which accepts funds.
TransactionStatusPending TransactionStatus = "pending"
// TransactionStatusCancelled is a transaction that is cancelled and no longer accepting new funds.
TransactionStatusCancelled TransactionStatus = "cancelled"
)
// TransactionID is a transaction ID type.
type TransactionID []byte
// String returns string representation of transaction id.
func (id TransactionID) String() string {
return string(id)
}
// Transaction defines deposit transaction which
// accepts user funds on a specific wallet address.
type Transaction struct {
ID TransactionID
Amount monetary.Amount
Rate decimal.Decimal
Address string
Status TransactionStatus
Timeout time.Duration
Link string
CreatedAt time.Time
}
// TransactionInfo holds transaction data with additional information
// such as links and expiration time.
type TransactionInfo struct {
ID TransactionID
Amount monetary.Amount
Received monetary.Amount
AmountCents int64
ReceivedCents int64
Address string
Status TransactionStatus
Link string
ExpiresAt time.Time
CreatedAt time.Time
}
// DepositBonus defines a bonus received for depositing tokens.
type DepositBonus struct {
TransactionID TransactionID
AmountCents int64
Percentage int64
CreatedAt time.Time
}