Help us shape the future of Go! Take the 2026 Go Developer Survey

pnl

package
v0.0.8 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: AGPL-3.0 Imports: 4 Imported by: 0

Documentation

Overview

Package pnl computes average-cost positions and profit and loss from the swaps an agent made, in exact rational arithmetic. It does no I/O.

Index

Constants

View Source
const Native = "native"

Native identifies the chain's native asset in Swap and Position.

Variables

This section is empty.

Functions

func Decimal

func Decimal(r *big.Rat, places int) string

Decimal renders r with at most places fraction digits, rounded half away from zero, without trailing zeros. Nil renders as "".

func FromRecords

func FromRecords(records []*journal.OnchainRecord, agent string, nativeAliases ...string) ([]Swap, Skipped)

FromRecords converts an agent's journal swaps (journal.ListOnchainSwaps) to Swaps. A record with a receipt fill uses the measured amount and gas; one without falls back to MinOut and is Approximate.

func Key

func Key(token string, nativeAliases ...string) string

Key normalizes a token for lookups: lower-case, with native aliases mapped to Native.

func Scale

func Scale(r *big.Rat, decimals int) *big.Rat

Scale returns r / 10^decimals.

Types

type Book

type Book struct {
	// contains filtered or unexported fields
}

Book holds every token's position.

func Compute

func Compute(swaps []Swap) *Book

Compute replays swaps in order with the average-cost method. Token keys must already be normalized with Key. Swaps with invalid amounts, or with native or the same token on both sides, are skipped.

func (*Book) Position

func (b *Book) Position(token string) *Position

Position returns token's position, or nil if no swap touched it.

func (*Book) Positions

func (b *Book) Positions() []*Position

Positions returns every non-native position sorted by token.

type Position

type Position struct {
	Token string
	// Held is the tracked quantity: what the agent's own swaps bought and
	// have not sold.
	Held *big.Rat
	// Cost is the remaining cost basis of Held.
	Cost *big.Rat
	// Realized is proceeds minus average cost of every tracked sale, net of
	// the swap gas attributed to this token.
	Realized *big.Rat
	// Gas is the native wei paid by the swaps attributed to this token.
	Gas *big.Int
	// GasUnknown counts attributed swaps whose gas is not recorded.
	GasUnknown int
	Bought     *big.Rat
	Sold       *big.Rat
	// UntrackedSold is sold quantity the agent's swaps never bought (it came
	// from outside the agent). Its proceeds are not in Realized.
	UntrackedSold *big.Rat
	// UntrackedBought is received quantity whose cost is unknown, because a
	// token -> token input had no price and no tracked basis. It is not in Held.
	UntrackedBought *big.Rat
	// Approximate is set when any swap of this token used the slippage floor
	// or an estimated input value.
	Approximate bool
	Swaps       int
}

Position is the running state of one token. Quantities are raw units and values native wei.

func (*Position) AvgCost

func (p *Position) AvgCost() *big.Rat

AvgCost returns native wei per raw unit of Held, or nil when nothing is held.

func (*Position) BasisOf

func (p *Position) BasisOf(size *big.Int) *big.Rat

BasisOf returns the native wei cost of size raw units at the average cost, or nil when nothing is held.

func (*Position) Unrealized

func (p *Position) Unrealized(price *big.Rat) *big.Rat

Unrealized returns Held valued at price (native wei per raw unit) minus Cost. It is nil when price is nil, except that nothing held is worth 0.

type Skipped

type Skipped struct {
	// OtherRecipient swaps delivered their output to an address other than
	// the agent, so they did not change the agent's position.
	OtherRecipient int `json:"other_recipient"`
	// Invalid swaps had unparseable amounts or tokens.
	Invalid int `json:"invalid"`
}

Skipped counts journal swaps FromRecords left out.

type Swap

type Swap struct {
	ID       string
	InToken  string
	OutToken string
	AmountIn *big.Int
	// AmountOut is what the recipient received. Approximate marks a value
	// that is the slippage floor rather than the measured fill.
	AmountOut   *big.Int
	Approximate bool
	// Gas is the native wei paid for the swap's transactions, nil if unknown.
	Gas *big.Int
	// InValue is the native wei value of the input of a token -> token swap
	// at the time of the swap, nil if unknown. It is ignored otherwise.
	InValue *big.Rat
}

Swap is one executed swap. Amounts are raw units of their token (wei for native).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL