outcome

Documentation

Overview

Package outcome defines the data structures for expressing how channel funds are to be distributed on-chain. It includes functions for manipulating those structures according to the nitro operations "transfer" and "claim".

Index

• Variables
• func ComputeTransferEffectsAndInteractions(initialHoldings big.Int, allocations Allocations, indices []uint) (newAllocations Allocations, exitAllocations Allocations)
• type Allocation
  • func (a Allocation) Clone() Allocation
  • func (a Allocation) Equal(b Allocation) bool
• type AllocationType
• type Allocations
  • func (a Allocations) Affords(given Allocation, funding *big.Int) bool
  • func (a Allocations) Clone() Allocations
  • func (a Allocations) DivertToGuarantee(leftDestination types.Destination, rightDestination types.Destination, ...) (Allocations, error)
  • func (a Allocations) Equal(b Allocations) bool
  • func (a Allocations) Total() *big.Int
  • func (a Allocations) TotalFor(dest types.Destination) *big.Int
• type AssetMetadata
• type AssetType
• type Exit
  • func Decode(data types.Bytes) (Exit, error)
  • func (e Exit) Affords(allocationMap map[common.Address]Allocation, funding types.Funds) bool
  • func (e Exit) Clone() Exit
  • func (e Exit) DepositSafetyThreshold(interest types.Destination) types.Funds
  • func (e Exit) DivertToGuarantee(leftDestination types.Destination, rightDestination types.Destination, ...) (Exit, error)
  • func (e *Exit) Encode() (types.Bytes, error)
  • func (a Exit) Equal(b Exit) bool
  • func (e *Exit) Hash() (types.Bytes32, error)
  • func (e Exit) TotalAllocated() types.Funds
  • func (e Exit) TotalAllocatedFor(dest types.Destination) types.Funds
• type GuaranteeMetadata
  • func DecodeIntoGuaranteeMetadata(m []byte) (GuaranteeMetadata, error)
  • func (m GuaranteeMetadata) Encode() (types.Bytes, error)
• type SingleAssetExit
  • func (s SingleAssetExit) Clone() SingleAssetExit
  • func (s SingleAssetExit) DepositSafetyThreshold(interest types.Destination) *big.Int
  • func (s SingleAssetExit) Equal(r SingleAssetExit) bool
  • func (sae SingleAssetExit) TotalAllocated() *big.Int
  • func (sae SingleAssetExit) TotalAllocatedFor(dest types.Destination) *big.Int

Variables

var ExitTy, _ = abi.NewType("tuple[]", "struct ExitFormat.SingleAssetExit[]", []abi.ArgumentMarshaling{
	{Name: "asset", Type: "address"},
	assetMetadataTy,
	allocationsTy,
})

ExitTy describes the shape of Exit such that github.com/ethereum/go-ethereum/accounts/abi can parse it

Functions

func ComputeTransferEffectsAndInteractions

func ComputeTransferEffectsAndInteractions(initialHoldings big.Int, allocations Allocations, indices []uint) (newAllocations Allocations, exitAllocations Allocations)

ComputeTransferEffectsAndInteractions computes the effects and interactions that will be executed on-chain when "transfer" is called.

Types

type Allocation

type Allocation struct {
	Destination    types.Destination // Either an ethereum address or an application-specific identifier
	Amount         *types.Uint256    // An amount of a particular asset
	AllocationType AllocationType    // Directs calling code on how to interpret the allocation
	Metadata       []byte            // Custom metadata (optional field, can be zero bytes). This can be used flexibly by different protocols.
}

Allocation declares an Amount to be paid to a Destination.

func (Allocation) Clone

func (a Allocation) Clone() Allocation

Clone returns a deep copy of the receiver.

func (Allocation) Equal

func (a Allocation) Equal(b Allocation) bool

Equal returns true if the supplied Allocation matches the receiver Allocation, and false otherwise. Fields are compared with ==, except for big.Ints which are compared using Cmp

type AllocationType

type AllocationType uint8

const (
	NormalAllocationType AllocationType = iota
	GuaranteeAllocationType
)

type Allocations

type Allocations []Allocation

Allocations is an array of type Allocation

func (Allocations) Affords

func (a Allocations) Affords(given Allocation, funding *big.Int) bool

Affords returns true if the allocations can afford the given allocation given the input funding, false otherwise.

To afford the given allocation, the allocations must include something equal-in-value to it, as well as having sufficient funds left over for it after reserving funds from the input funding for all allocations with higher priority. Note that "equal-in-value" implies the same allocation type and metadata (if any).

func (Allocations) Clone

func (a Allocations) Clone() Allocations

Clone returns a deep copy of the receiver

func (Allocations) DivertToGuarantee

func (a Allocations) DivertToGuarantee(
	leftDestination types.Destination,
	rightDestination types.Destination,
	leftAmount *big.Int,
	rightAmount *big.Int,
	guaranteeDestination types.Destination,
) (Allocations, error)

DivertToGuarantee returns a new Allocations, identical to the receiver but with the leftDestination's amount reduced by leftAmount, the rightDestination's amount reduced by rightAmount, and a Guarantee appended for the guaranteeDestination

func (Allocations) Equal

func (a Allocations) Equal(b Allocations) bool

Equal returns true if each of the supplied Allocations matches the receiver Allocation in the same position, and false otherwise.

func (Allocations) Total

func (a Allocations) Total() *big.Int

Total returns the toal amount allocated, summed across all destinations (regardless of AllocationType)

func (Allocations) TotalFor

func (a Allocations) TotalFor(dest types.Destination) *big.Int

TotalFor returns the total amount allocated to the given dest (regardless of AllocationType)

type AssetMetadata

type AssetMetadata struct {
	AssetType AssetType
	Metadata  []byte
}

type AssetType

type AssetType uint8

type Exit

type Exit []SingleAssetExit

Exit is an ordered list of SingleAssetExits

func Decode

func Decode(data types.Bytes) (Exit, error)

Decode returns an Exit from an abi encoding

func (Exit) Affords

func (e Exit) Affords(
	allocationMap map[common.Address]Allocation,
	funding types.Funds,
) bool

Affords returns true if every allocation in the allocationMap can be afforded by the Exit, given the funds

Both arguments are maps keyed by the same assets

func (Exit) Clone

func (e Exit) Clone() Exit

Clone returns a deep clone of the receiver.

func (Exit) DepositSafetyThreshold

func (e Exit) DepositSafetyThreshold(interest types.Destination) types.Funds

DepositSafetyThreshold returns the Funds that a user with the specified interest must see on-chain before the safe recoverability of their deposits is guaranteed

func (Exit) DivertToGuarantee

func (e Exit) DivertToGuarantee(
	leftDestination types.Destination,
	rightDestination types.Destination,
	leftFunds types.Funds,
	rightFunds types.Funds,
	guaranteeDestination types.Destination,
) (Exit, error)

DivertToGuarantee returns a new Exit, identical to the receiver but with (for each asset of the Exit) the leftDestination's amount reduced by leftFunds[asset], the rightDestination's amount reduced by rightAmount[asset], and a Guarantee appended for the guaranteeDestination. Where an asset is missing from leftFunds or rightFunds, it is treated as if the corresponding amount is zero.

func (*Exit) Encode

func (e *Exit) Encode() (types.Bytes, error)

Encode returns the abi encoded Exit

func (Exit) Equal

func (a Exit) Equal(b Exit) bool

Equal returns true if the supplied Exit is deeply equal to the receiver.

func (*Exit) Hash

func (e *Exit) Hash() (types.Bytes32, error)

Hash returns the keccak256 hash of the Exit

func (Exit) TotalAllocated

func (e Exit) TotalAllocated() types.Funds

TotalAllocated returns the sum of all Funds that are allocated by the outcome.

NOTE that these Funds are potentially different from a channel's capacity to pay out a given set of allocations, which is limited by the channel's holdings

func (Exit) TotalAllocatedFor

func (e Exit) TotalAllocatedFor(dest types.Destination) types.Funds

TotalAllocatedFor returns the total amount allocated to the given dest (regardless of AllocationType)

type GuaranteeMetadata

type GuaranteeMetadata struct {
	// The peer who plays the role of Alice (peer 0)
	Left types.Destination
	// The peer who plays the role of Bob (peer n+1, where n=len(intermediaries)
	Right types.Destination
}

A Guarantee is an Allocation with AllocationType == GuaranteeAllocationType and Metadata = encode(GuaranteeMetaData)

func DecodeIntoGuaranteeMetadata

func DecodeIntoGuaranteeMetadata(m []byte) (GuaranteeMetadata, error)

Decode returns a GuaranteeMetaData from an abi encoding

func (GuaranteeMetadata) Encode

func (m GuaranteeMetadata) Encode() (types.Bytes, error)

Encode returns the abi.encoded GuaranteeMetadata (suitable for packing in an Allocation.Metadata field)

type SingleAssetExit

type SingleAssetExit struct {
	Asset         types.Address // Either the zero address (implying the native token) or the address of an ERC20 contract
	AssetMetadata AssetMetadata // Can be used to encode arbitrary additional information that applies to all allocations.
	Allocations   Allocations
}

SingleAssetExit declares an ordered list of Allocations for a single asset.

func (SingleAssetExit) Clone

func (s SingleAssetExit) Clone() SingleAssetExit

Clone returns a deep clone of the receiver.

func (SingleAssetExit) DepositSafetyThreshold

func (s SingleAssetExit) DepositSafetyThreshold(interest types.Destination) *big.Int

DepositSafetyThreshold returns the amount of this asset that a user with the specified interest must see on-chain before the safe recoverability of their own deposits is guaranteed

func (SingleAssetExit) Equal

func (s SingleAssetExit) Equal(r SingleAssetExit) bool

Equal returns true if the supplied SingleAssetExit is deeply equal to the receiver.

func (SingleAssetExit) TotalAllocated

func (sae SingleAssetExit) TotalAllocated() *big.Int

TotalAllocated returns the toal amount allocated, summed across all destinations (regardless of AllocationType)

func (SingleAssetExit) TotalAllocatedFor

func (sae SingleAssetExit) TotalAllocatedFor(dest types.Destination) *big.Int

TotalAllocatedFor returns the total amount allocated for the specific destination