Documentation
¶
Overview ¶
Package balance provides utilities for fetching a Flipcash user's balance from the OCP server.
Index ¶
- Variables
- type Client
- func (c *Client) GetMintHoldingsForUsers(ctx context.Context, currency currency_lib.Code, mint *commonpb.PublicKey, ...) (map[string]MintHolding, error)
- func (c *Client) GetMintQuarksForUsers(ctx context.Context, mint *commonpb.PublicKey, userIDs ...*commonpb.UserId) (map[string]uint64, error)
- func (c *Client) GetTotalFiatValue(ctx context.Context, userID *commonpb.UserId, currency currency_lib.Code, ...) (float64, error)
- func (c *Client) GetTotalUsdfBalance(ctx context.Context, userID *commonpb.UserId, mints ...*commonpb.PublicKey) (uint64, error)
- type MintHolding
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotFound indicates the user has no account bound to a public key, so // there's no owner account to fetch a balance for. ErrNotFound = errors.New("no owner account found for user") // ErrDenied indicates the OCP server refused to disclose the balance of an // owner account. ErrDenied = errors.New("denied access to balance") // ErrAmbiguousOwner indicates the user has more than one public key bound, // so there is no single owner account to fetch a balance for. Nothing // binds a second key today; a user in this state is a bug, not a case. ErrAmbiguousOwner = errors.New("more than one owner account found for user") // ErrUnsupportedCurrency indicates the OCP server could not value a balance // in the requested fiat currency: it answered the owner, but with no value // for that currency code. OCP is the authority on which currencies it can // price, so this is how a code it does not know — or cannot quote right // now — surfaces; no list of supported codes is kept here. ErrUnsupportedCurrency = errors.New("unsupported balance currency") )
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client fetches user balances from the OCP server.
func NewClient ¶
func NewClient( log *zap.Logger, accounts account.Store, ocpBalance ocp_balancepb.BalanceClient, ) *Client
NewClient returns a Client backed by the OCP Balance service. The parent application is responsible for constructing ocpBalance against the OCP server's gRPC endpoint.
func (*Client) GetMintHoldingsForUsers ¶ added in v1.35.0
func (c *Client) GetMintHoldingsForUsers(ctx context.Context, currency currency_lib.Code, mint *commonpb.PublicKey, userIDs ...*commonpb.UserId) (map[string]MintHolding, error)
GetMintHoldingsForUsers returns what each of the given users holds of mint, in the mint's quarks and valued in currency, keyed by string(userID.Value): GetTotalFiatValue for many users and one mint, plus the quarks behind each value, at as few OCP calls as its batch limit allows (maxOwnersPerGetBalances owners each). Calls beyond the first are made one after another, so a large batch is not one instant's balances: holdings that move between users during the read can be seen in both.
A user who holds nothing of mint, or who has not opened OCP accounts yet, is absent, and so is a user with no bound key, or more than one (see ErrAmbiguousOwner, logged here): there is no single owner to read for them, and one such user must not hold up everyone else's balance. A currency OCP cannot price is ErrUnsupportedCurrency, as for GetTotalFiatValue.
func (*Client) GetMintQuarksForUsers ¶ added in v1.35.0
func (c *Client) GetMintQuarksForUsers(ctx context.Context, mint *commonpb.PublicKey, userIDs ...*commonpb.UserId) (map[string]uint64, error)
GetMintQuarksForUsers returns what each of the given users holds of mint, in the mint's own quarks, keyed by string(userID.Value): the quarks of GetMintHoldingsForUsers with no valuation asked for, so the answer never depends on a rate and no currency can be unsupported. It is for a caller that sums or ranks holdings of one mint, where quarks are exact and a value adds nothing. Who is left out, and how the read is batched, is as for GetMintHoldingsForUsers.
func (*Client) GetTotalFiatValue ¶ added in v1.32.0
func (c *Client) GetTotalFiatValue(ctx context.Context, userID *commonpb.UserId, currency currency_lib.Code, mints ...*commonpb.PublicKey) (float64, error)
GetTotalFiatValue returns a user's total balance valued in a fiat currency, in that currency's major units — the same holdings GetTotalUsdfBalance totals, and the same mint filter, but as OCP values them at its current exchange rate rather than in quarks. The value is a quoted rate applied to a quark total, so a comparison against it should allow rounding slack.
The currency is any ISO 4217 code OCP can price. One it cannot is ErrUnsupportedCurrency, never a zero: a caller gating on the value must not mistake "no answer" for "holds nothing". A user that hasn't opened OCP accounts yet holds nothing in any currency, and ErrNotFound is returned when the user has no public key bound at all.
func (*Client) GetTotalUsdfBalance ¶
func (c *Client) GetTotalUsdfBalance(ctx context.Context, userID *commonpb.UserId, mints ...*commonpb.PublicKey) (uint64, error)
GetTotalUsdfBalance returns a user's total balance in USDF quarks.
The value is what OCP reports as the owner account's core mint value, which is USDF for Flipcash. It spans every mint the user holds, with non-core mint holdings valued in USDF, so it is the user's total balance and not just the quarks sitting in their USDF accounts. Given mints, it spans only the holdings in those mints, still valued in USDF; a mint the user holds nothing of contributes nothing.
No fiat valuation is asked for, so the answer never depends on an exchange rate: a USD comparison against it is exact, in quarks.
A user that hasn't opened OCP accounts yet has a zero balance. ErrNotFound is returned when the user has no public key bound at all.
type MintHolding ¶ added in v1.35.0
type MintHolding struct {
// Quarks is the amount held, in the mint's own quarks.
Quarks uint64
// FiatValue is the holding valued in the requested currency, in that
// currency's major units, as OCP values it at its current exchange rate.
FiatValue float64
}
MintHolding is what one user holds of one mint.
Source Files