payments

package
v0.6.2 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package payments provides the payment management service for Filecoin Onchain Cloud.

It handles USDFC token operations including deposits, withdrawals, balance queries, approval management, and payment rail creation via the Filecoin Pay contract. AccountSummary is the recommended entry point for payment account state; TotalAccountFixedLockup reports fixed lockup held across payer rails. Both methods pin every read to one block and include terminated rails awaiting final settlement. Rail details require the chain's Multicall3 contract. Options.MaxMulticallCalls bounds each detail batch (zero uses 64). Transient RPC failures receive bounded retries within the caller's context; contract and decoding errors are not retried. Any failure returns a nil result.

The root synapse Client wires payments together with the other write-capable services so transaction nonce allocation is coordinated for a shared signer. It also wires Fund approval lockup periods from the warmstorage PriceList. Standalone services create their own nonce coordinator when constructed with write dependencies and use the legacy Fund lockup-period fallback unless an ApprovalLockupPeriod reader is supplied.

Rail pagination

GetRailsAsPayer and GetRailsAsPayee require types.ListOptions with Limit > 0. A zero limit returns both ErrInvalidArgument and types.ErrInvalidListOptions. The limit bounds the slots examined; finalized slots are skipped, so a page can be short or empty even when NextOffset < Total indicates more slots. Total counts underlying rail slots, not just the returned rails.

Use IterateAllRailsAsPayer or IterateAllRailsAsPayee to read every page without accumulating all rails in memory. Pages may observe different blocks; neither manual pagination nor iteration provides an atomic snapshot.

Manual offsets in types.ListOptions are uint64. NextOffset retains the contract's uint256 width: check IsUint64 before converting it to a manual offset, and reject out-of-range values rather than truncating them. The IterateAllRails methods carry the full-width continuation automatically.

Example

Example shows reading an account balance via payments.Service. In practice a Service is obtained from synapse.Client.Payments. 

package main

import (
	"context"
	"fmt"
	"log"
	"math/big"

	"github.com/ethereum/go-ethereum/common"
	"github.com/strahe/synapse-go/payments"
)

func main() {
	var svc *payments.Service // obtained from synapse.Client.Payments()

	ctx := context.Background()
	usdfc := common.HexToAddress("0x...")
	owner := common.HexToAddress("0x...")

	bal, err := svc.Balance(ctx, usdfc, owner)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(new(big.Int).Set(bal))
}

Index

Examples

Constants

View Source 
const PermitDeadlineDuration = time.Hour

PermitDeadlineDuration is the default validity window appended to the current wall-clock time when the caller does not provide an explicit permit deadline.

Variables

View Source 
var ErrClosed = lifecycle.ErrClosed

ErrClosed is returned when a method is called after the owning Client has been closed. It aliases the shared closed-client sentinel, so errors.Is(err, payments.ErrClosed) matches either sentinel.

View Source 
var ErrInsufficientAllowance = errors.New("payments: insufficient allowance")

ErrInsufficientAllowance is returned when an ERC20 allowance is lower than the amount required for a deposit.

View Source 
var ErrInsufficientBalance = errors.New("payments: insufficient balance")

ErrInsufficientBalance is returned when the on-chain balance is lower than the requested amount for a withdrawal or transfer.

View Source 
var ErrInvalidArgument = errors.New("payments: invalid argument")

ErrInvalidArgument is returned, wrapped via fmt.Errorf with %w, when a caller passes an argument that violates a precondition (nil pointer, zero address, invalid chain ID). Match with errors.Is(err, payments.ErrInvalidArgument).

Business-domain sentinels such as ErrInsufficientBalance or ErrInsufficientAllowance live alongside this file and cover runtime preconditions that are independent of caller-supplied arguments.

View Source 
var ErrInvalidRailPage = errors.New("payments: invalid rail page")

ErrInvalidRailPage is returned by AccountSummary, TotalAccountFixedLockup, and IterateAllRailsAsPayer/Payee when a rail page cannot be safely traversed. Match with errors.Is.

View Source 
var ErrNothingToFund = errors.New("payments: nothing to fund (already approved and amount is 0)")

ErrNothingToFund is returned by Fund / FundSync when the account is already fully approved for WarmStorage and the caller requested a zero deposit amount, meaning there is no work to do.

View Source 
var ErrPermitUnsupported = errors.New("payments: token contract does not support EIP-2612 permit")

ErrPermitUnsupported is returned by DepositWithPermit and DepositWithPermitAndApproveOperator when the token contract does not expose the EIP-2612 permit ABI (name / version / nonces probes fail). Callers can branch on this with errors.Is to fall back to Approve + Deposit instead of surfacing a generic precondition error.

View Source 
var ErrTxFailed = types.ErrTxFailed

ErrTxFailed reports that a transaction was mined but reverted on-chain. Use errors.Is to match errors returned by state-changing calls.

This is a convenience re-export of [types.ErrTxFailed]; the two values are the same sentinel and can be matched interchangeably.

View Source 
var ErrUninitialized = errors.New("payments: service not initialized; use payments.New")

ErrUninitialized is returned when a method is invoked on a zero-value Service (one that was not constructed via New). Match with errors.Is(err, payments.ErrUninitialized).

View Source 
var ErrZeroAddress = errors.New("payments: zero address")

ErrZeroAddress is returned when a caller passes common.Address{} for an argument that must be a real token or account address. Public service methods wrap it together with ErrInvalidArgument so callers can match either the specific zero-address sentinel or the generic invalid-argument sentinel.

View Source 
var ZeroAddress = common.Address{}

ZeroAddress is a convenience alias for common.Address{} used to indicate native FIL in WalletBalance queries.

Functions

This section is empty.

Types

type AccountState 

type AccountState struct {
	Funds               *big.Int
	LockupCurrent       *big.Int
	LockupRate          *big.Int
	LockupLastSettledAt *big.Int
	// FundedUntilEpoch is the forward-looking epoch at which the account's
	// available funds will be exhausted at the current lockup rate.
	// Sourced from getAccountInfoIfSettled(); zero when LockupRate is zero.
	FundedUntilEpoch *big.Int
	// contains filtered or unexported fields
}

AccountState mirrors FilPay.accounts(token, owner). All values are in base units of the payment token.

func (*AccountState) AvailableFunds 

func (a *AccountState) AvailableFunds() *big.Int

AvailableFunds returns Funds - LockupCurrent (never negative). A nil AccountState returns nil.

func (*AccountState) DebtAt added in v0.3.1 

func (a *AccountState) DebtAt(epoch *big.Int) *big.Int

DebtAt returns the outstanding amount owed beyond Funds at epoch.

func (*AccountState) ResolveAt added in v0.3.1 

func (a *AccountState) ResolveAt(epoch *big.Int) AccountStateResolution

ResolveAt projects the raw account fields to epoch. It ignores AccountInfo's cached available funds so each projection uses the same source fields.

Rate lockup is projected through epoch even after Funds are exhausted, so an account in deficit reports zero AvailableFunds and AccountState.DebtAt reports the full shortfall; no funds are counted as both available and applied to debt.

type AccountStateResolution added in v0.3.1 

type AccountStateResolution struct {
	// AvailableFunds is the balance available for withdrawal or new
	// commitments at the resolved epoch.
	AvailableFunds *big.Int
	// RunwayInEpochs is the number of epochs until the account enters deficit,
	// and zero once it is in deficit. With a zero LockupRate it is maxUint256
	// unless LockupCurrent already exceeds Funds.
	RunwayInEpochs *big.Int
	// GrossCoverageInEpochs is Funds / LockupRate, ignoring reserved lockup.
	// It is maxUint256 when LockupRate is zero.
	GrossCoverageInEpochs *big.Int
}

AccountStateResolution is an account state projected to a specific epoch.

type AccountSummary added in v0.3.0 

type AccountSummary struct {
	// Funds is the total deposited balance in base units of the configured
	// USDFC token.
	Funds *big.Int
	// AvailableFunds is the balance available for withdrawal or new
	// commitments at CurrentEpoch, in base units of the configured USDFC token.
	AvailableFunds *big.Int
	// Debt is the outstanding amount owed beyond Funds, in base units of the
	// configured USDFC token.
	Debt *big.Int
	// LockupRatePerEpoch is the aggregate payment lockup rate in base units of
	// the configured USDFC token per Filecoin epoch.
	LockupRatePerEpoch *big.Int
	// LockupRatePerMonth is LockupRatePerEpoch multiplied by the SDK's
	// Filecoin epochs-per-month constant.
	LockupRatePerMonth *big.Int
	// TotalLockup is the effective locked amount at CurrentEpoch in base units
	// of the configured USDFC token.
	TotalLockup *big.Int
	// TotalFixedLockup is the sum of fixed lockup across payer rails, including
	// terminated-but-not-finalized rails, in base units of the configured USDFC
	// token.
	TotalFixedLockup *big.Int
	// TotalRateBasedLockup is TotalLockup minus TotalFixedLockup, floored at
	// zero, in base units of the configured USDFC token.
	TotalRateBasedLockup *big.Int
	// RunwayInEpochs is the number of epochs from CurrentEpoch until the
	// account enters deficit, and zero once it is in deficit. With a zero
	// LockupRatePerEpoch it is maxUint256 unless the account is already in
	// deficit.
	RunwayInEpochs *big.Int
	// GrossCoverageInEpochs is Funds / LockupRatePerEpoch, ignoring reserved
	// lockup. It is maxUint256 when LockupRatePerEpoch is zero.
	GrossCoverageInEpochs *big.Int
	// CurrentEpoch is the Filecoin epoch used for this snapshot's calculations.
	CurrentEpoch *big.Int
}

AccountSummary is a payment account health snapshot for the configured USDFC token.

type ApprovalLockupPeriodReader added in v0.4.0 

type ApprovalLockupPeriodReader interface {
	ApprovalLockupPeriod(ctx context.Context) (*big.Int, error)
}

ApprovalLockupPeriodReader returns the maximum lockup period Fund should grant to the WarmStorage operator. The root Client supplies a WarmStorage adapter.

type Backend 

type Backend interface {
	bind.ContractBackend
	BalanceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (*big.Int, error)
	TransactionReceipt(ctx context.Context, txHash common.Hash) (*types.Receipt, error)
	BlockNumber(ctx context.Context) (uint64, error)
}

Backend provides the Ethereum RPC methods used by Service. The root Client supplies its configured Ethereum client.

type NonceManager added in v0.5.0 

type NonceManager interface {
	Acquire(ctx context.Context) (nonce uint64, release func(), err error)
}

NonceManager serializes transaction-nonce acquisition for one signing address. The root Client supplies a shared coordinator. On success, Acquire must return the next pending nonce and a non-nil, idempotent release function. Callers may invoke release more than once, but must invoke it after broadcasting or abandoning the transaction.

type OperatorApproval 

type OperatorApproval struct {
	IsApproved      bool
	RateAllowance   *big.Int // maximum per-epoch rate the operator may charge
	LockupAllowance *big.Int // maximum lockup the operator may hold
	RateUsage       *big.Int // current per-epoch rate in use by the operator
	LockupUsage     *big.Int // current lockup held by the operator
	MaxLockupPeriod *big.Int // maximum lockup period allowed (in epochs)
}

OperatorApproval mirrors FilPay.operatorApprovals(token, client, operator).

type Options 

type Options struct {
	// Backend is the Ethereum RPC client. Required.
	Backend Backend
	// ChainID of the target FEVM chain. Required; must be > 0.
	ChainID sdktypes.ChainID
	// FilPayAddress is the Filecoin Pay contract address. Required.
	FilPayAddress common.Address
	// WarmStorageAddress is the FilecoinWarmStorageService contract address.
	// Optional; required for Fund / FundSync smart-route helpers because
	// they route through WarmStorage operator approval state. When zero
	// Fund / FundSync return ErrInvalidArgument.
	WarmStorageAddress common.Address
	// USDFCTokenAddress is the USDFC (or other ERC-2612) token address
	// used as the default for Fund / FundSync and for permit operations
	// that do not receive an explicit token argument. Optional; callers
	// may always pass a token explicitly to DepositWithPermit.
	USDFCTokenAddress common.Address
	// MaxMulticallCalls limits rail detail calls per Multicall3 request in
	// AccountSummary and TotalAccountFixedLockup. Zero uses 64; negative values
	// return ErrInvalidArgument.
	MaxMulticallCalls int
	// Signer is used to sign transactions. Required for write methods;
	// may be nil when the Service is used for reads only.
	Signer signer.EVMSigner
	// ApprovalLockupPeriod reads the default WarmStorage approval lockup
	// period. Optional; Fund falls back to one Filecoin month when omitted.
	ApprovalLockupPeriod ApprovalLockupPeriodReader
	// Logger is optional. When nil, logging is disabled.
	Logger *slog.Logger
	// NonceManager is optional. The root synapse Client injects a shared
	// coordinator across all write-capable services; standalone callers may
	// leave this nil to create one for this Service. A typed-nil value is treated
	// as nil.
	NonceManager NonceManager
	// ReceiptWait overrides the default receipt polling timeout used by
	// WithConfirmations when the call waits for a receipt but does not
	// provide a more specific WithWait(timeout). Zero uses the default receipt
	// polling configuration.
	ReceiptWait time.Duration
	// Lifecycle is checked before service operations that can touch configured
	// backends. Any error returned by CheckClosed is returned without touching
	// those backends. The root synapse Client injects a shared checker whose
	// closed error matches ErrClosed. Nil is allowed for standalone use. A
	// typed-nil value is treated as nil.
	Lifecycle interface{ CheckClosed() error }
}

Options bundles the dependencies for constructing a Service.

type RailListItem 

type RailListItem struct {
	RailID       sdktypes.BigInt
	IsTerminated bool
	EndEpoch     *big.Int
}

RailListItem is a single entry returned by GetRailsAsPayer / GetRailsAsPayee; it corresponds to `FilecoinPayV1RailInfo` on the contract side.

type RailPage 

type RailPage struct {
	Rails []RailListItem
	// NextOffset is the continuation offset returned by the contract.
	// There are more slots when NextOffset < Total. Check IsUint64 before
	// converting it to ListOptions.Offset, or use IterateAllRailsAsPayer/Payee.
	NextOffset *big.Int
	// Total is the number of underlying rail slots, including finalized slots.
	Total *big.Int
}

RailPage is one page of rails plus pagination cursors. A page can contain fewer rails than the requested limit because finalized slots are skipped.

type RailView 

type RailView struct {
	Token               common.Address
	From                common.Address
	To                  common.Address
	Operator            common.Address
	Validator           common.Address
	PaymentRate         *big.Int
	LockupPeriod        *big.Int
	LockupFixed         *big.Int
	SettledUpTo         *big.Int
	EndEpoch            *big.Int
	CommissionRateBps   *big.Int
	ServiceFeeRecipient common.Address
}

RailView is the flattened view of FilecoinPayV1RailView from the FilPay contract.

type Service 

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

Service provides read and write access to the Filecoin Pay contract plus convenience wrappers around ERC20 allowance management.

It is safe for concurrent use. All state-changing calls return a sdktypes.WriteResult whose Receipt is only populated when WithWait is supplied.

func New 

func New(opts Options) (*Service, error)

New constructs a Service.

func (*Service) Account 

func (s *Service) Account() common.Address

Account returns the EOA address used for writes, or the zero address when the service was constructed without a signer.

func (*Service) AccountInfo 

func (s *Service) AccountInfo(ctx context.Context, token, owner common.Address) (*AccountState, error)

AccountInfo returns the on-chain account record for (token, owner).

When token is ZeroAddress, native FIL is queried via BalanceAt and returned as AccountState.Funds. All lockup fields are zero because native FIL is not tracked by the FilPay contract.

func (*Service) AccountSummary added in v0.3.0 

func (s *Service) AccountSummary(ctx context.Context, owner common.Address) (*AccountSummary, error)

AccountSummary returns a payment health snapshot for owner using the Service's configured USDFC token. All reads use CurrentEpoch as their block number. Rail details require Multicall3; any read failure returns a nil result.

func (*Service) Address 

func (s *Service) Address() common.Address

Address returns the FilPay contract address.

func (*Service) Allowance 

func (s *Service) Allowance(ctx context.Context, token, owner, spender common.Address) (*big.Int, error)

Allowance returns the ERC20 allowance of owner towards spender for token.

func (*Service) Approve 

func (s *Service) Approve(ctx context.Context, token, spender common.Address, amount *big.Int, opts ...WriteOption) (*sdktypes.WriteResult, error)

Approve calls ERC20.approve(spender, amount) on the given token.

spender is typically the FilPay contract address; use service.Address() for that convenience.

func (*Service) ApproveService 

func (s *Service) ApproveService(ctx context.Context, token, operator common.Address, rateAllowance, lockupAllowance, maxLockupPeriod *big.Int, opts ...WriteOption) (*sdktypes.WriteResult, error)

ApproveService calls FilPay.setOperatorApproval(token, operator, true, rateAllowance, lockupAllowance, maxLockupPeriod). Use RevokeService to clear the approval.

func (*Service) Balance 

func (s *Service) Balance(ctx context.Context, token, owner common.Address) (*big.Int, error)

Balance is a convenience that returns AccountInfo.AvailableFunds.

func (*Service) ChainID 

func (s *Service) ChainID() sdktypes.ChainID

ChainID returns the configured chain id.

func (*Service) Deposit 

func (s *Service) Deposit(ctx context.Context, token, to common.Address, amount *big.Int, opts ...WriteOption) (*sdktypes.WriteResult, error)

Deposit calls FilPay.deposit(token, to, amount). The caller must have first approved at least `amount` on the token contract for FilPay. When `to` is the zero address the caller's EOA is used.

func (*Service) DepositWithPermit 

func (s *Service) DepositWithPermit(
	ctx context.Context,
	token, to common.Address,
	amount, deadline *big.Int,
	opts ...WriteOption,
) (*sdktypes.WriteResult, error)

DepositWithPermit deposits `amount` of `token` into the Filecoin Pay contract on behalf of the signer in a single on-chain transaction by attaching an ERC-2612 permit signature. No prior ERC20 approval is required.

`to` is the credited depositor; when zero, defaults to the signer EOA. `deadline` is the permit expiry (unix seconds); when nil, now + PermitDeadlineDuration is used. `token` must be an ERC-2612 / ERC20Permit-compliant token (e.g. USDFC).

func (*Service) DepositWithPermitAndApproveOperator 

func (s *Service) DepositWithPermitAndApproveOperator(
	ctx context.Context,
	token, to common.Address,
	amount, deadline *big.Int,
	operator common.Address,
	rateAllowance, lockupAllowance, maxLockupPeriod *big.Int,
	opts ...WriteOption,
) (*sdktypes.WriteResult, error)

DepositWithPermitAndApproveOperator combines DepositWithPermit with a SetOperatorApproval in the same transaction. Use this to onboard a new client: deposit + grant WarmStorage (or another operator) the allowances it needs in a single click.

func (*Service) Fund 

func (s *Service) Fund(ctx context.Context, amount *big.Int, opts ...WriteOption) (*sdktypes.WriteResult, error)

Fund is a smart deposit that auto-detects whether WarmStorage is already approved with sufficient allowances and routes to the correct on-chain call:

  • needs approval + amount > 0 → DepositWithPermitAndApproveOperator
  • needs approval + amount == 0 → ApproveService
  • already approved + amount > 0 → DepositWithPermit
  • already approved + amount == 0 → ErrNothingToFund

Fund requires WarmStorageAddress and USDFCTokenAddress to be set on the Options. Returns ErrInvalidArgument when either is zero.

amount must be non-nil. Callers that want an approval-only flow must pass big.NewInt(0) explicitly so an omitted amount cannot silently broadcast an approval transaction.

Pass WithFundNeedsFwssApproval to reuse a previously computed approval decision instead of re-reading on-chain state.

func (*Service) FundSync 

func (s *Service) FundSync(ctx context.Context, amount *big.Int, opts ...WriteOption) (*sdktypes.WriteResult, error)

FundSync runs Fund and waits for the transaction to be mined. It is equivalent to Fund(..., WithWait(timeout)) with a sensible default timeout when the caller did not supply one.

func (*Service) GetRail 

func (s *Service) GetRail(ctx context.Context, railID sdktypes.BigInt) (*RailView, error)

GetRail returns the full view of a single rail by id.

func (*Service) GetRailsAsPayee 

func (s *Service) GetRailsAsPayee(ctx context.Context, payee, token common.Address, opts sdktypes.ListOptions) (*RailPage, error)

GetRailsAsPayee reads one page of rails paying payee in token. opts.Limit must be > 0 and bounds the slots examined, not the number of returned rails. Use IterateAllRailsAsPayee for unbounded traversal.

func (*Service) GetRailsAsPayer 

func (s *Service) GetRailsAsPayer(ctx context.Context, payer, token common.Address, opts sdktypes.ListOptions) (*RailPage, error)

GetRailsAsPayer reads one page of rails charging payer for token. opts.Limit must be > 0 and bounds the slots examined, not the number of returned rails. Use IterateAllRailsAsPayer for unbounded traversal.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/ethereum/go-ethereum/common"
	"github.com/strahe/synapse-go/payments"
	"github.com/strahe/synapse-go/types"
)

func main() {
	var svc *payments.Service // obtained from synapse.Client.Payments()
	ctx := context.Background()
	payer := common.HexToAddress("0x...")
	token := common.HexToAddress("0x...")
	opts := types.ListOptions{Limit: 100}

	for {
		page, err := svc.GetRailsAsPayer(ctx, payer, token, opts)
		if err != nil {
			log.Fatal(err)
		}
		for _, rail := range page.Rails {
			fmt.Println(rail.RailID)
		}
		if page.NextOffset.Cmp(page.Total) >= 0 {
			break
		}
		if !page.NextOffset.IsUint64() {
			log.Fatal("next rail offset exceeds uint64; use IterateAllRailsAsPayer")
		}
		if page.NextOffset.Uint64() <= opts.Offset {
			log.Fatal("next rail offset must advance")
		}
		opts.Offset = page.NextOffset.Uint64()
	}
}

func (*Service) GetSettlementAmounts 

func (s *Service) GetSettlementAmounts(ctx context.Context, railID sdktypes.BigInt, untilEpoch *big.Int) (*SettlementResult, error)

GetSettlementAmounts simulates FilPay.settleRail via eth_call and decodes the resulting amounts without broadcasting a transaction. Use it to preview how much would be settled to the payee / operator / network.

func (*Service) IterateAllRailsAsPayee added in v0.6.0 

func (s *Service) IterateAllRailsAsPayee(ctx context.Context, payee, token common.Address) iter.Seq2[RailListItem, error]

IterateAllRailsAsPayee yields every rail paying payee in token across all pages. It fetches pages lazily and stops when the consumer stops or ctx is canceled. An error is yielded once, then iteration ends. Pages may observe different blocks; iteration is not an atomic snapshot.

func (*Service) IterateAllRailsAsPayer added in v0.6.0 

func (s *Service) IterateAllRailsAsPayer(ctx context.Context, payer, token common.Address) iter.Seq2[RailListItem, error]

IterateAllRailsAsPayer yields every rail charging payer for token across all pages. It fetches pages lazily and stops when the consumer stops or ctx is canceled. An error is yielded once, then iteration ends. Pages may observe different blocks; iteration is not an atomic snapshot.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/ethereum/go-ethereum/common"
	"github.com/strahe/synapse-go/payments"
)

func main() {
	var svc *payments.Service // obtained from synapse.Client.Payments()
	ctx := context.Background()
	payer := common.HexToAddress("0x...")
	token := common.HexToAddress("0x...")

	for rail, err := range svc.IterateAllRailsAsPayer(ctx, payer, token) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(rail.RailID)
	}
}

func (*Service) RevokeService 

func (s *Service) RevokeService(ctx context.Context, token, operator common.Address, opts ...WriteOption) (*sdktypes.WriteResult, error)

RevokeService clears a prior ApproveService by setting approved=false and all allowances to zero.

func (*Service) ServiceApproval 

func (s *Service) ServiceApproval(ctx context.Context, token, client, operator common.Address) (*OperatorApproval, error)

ServiceApproval returns the operator approval record for (token, client, operator).

func (*Service) Settle 

func (s *Service) Settle(ctx context.Context, railID sdktypes.BigInt, untilEpoch *big.Int, opts ...WriteOption) (*sdktypes.WriteResult, error)

Settle triggers a rail settlement up to `untilEpoch`. When `untilEpoch` is nil or zero, the current block number is used.

func (*Service) SettleAuto 

func (s *Service) SettleAuto(ctx context.Context, railID sdktypes.BigInt, untilEpoch *big.Int, opts ...WriteOption) (*sdktypes.WriteResult, error)

SettleAuto inspects the rail state and routes to Settle or SettleTerminatedRail automatically — terminated rails (endEpoch > 0) go through the emergency path, active rails through the standard path.

func (*Service) SettleTerminatedRail 

func (s *Service) SettleTerminatedRail(ctx context.Context, railID sdktypes.BigInt, opts ...WriteOption) (*sdktypes.WriteResult, error)

SettleTerminatedRail triggers the emergency-settlement path for a terminated rail. This bypasses the operator validator and pays in full; it can only be called by the client after the max settlement epoch has passed.

func (*Service) TotalAccountFixedLockup added in v0.3.0 

func (s *Service) TotalAccountFixedLockup(ctx context.Context, owner common.Address) (*big.Int, error)

TotalAccountFixedLockup returns the sum of fixed lockup across all payer rails for owner using the Service's configured USDFC token. It includes terminated rails awaiting final settlement. Reads use one block number and Multicall3; any read failure returns a nil result.

func (*Service) WalletBalance 

func (s *Service) WalletBalance(ctx context.Context, token, account common.Address) (*big.Int, error)

WalletBalance returns the EOA balance of token. When token is the zero address the native FIL balance is returned via BalanceAt. Otherwise the ERC20 balanceOf(account) is queried.

func (*Service) Withdraw 

func (s *Service) Withdraw(ctx context.Context, token common.Address, amount *big.Int, opts ...WriteOption) (*sdktypes.WriteResult, error)

Withdraw calls FilPay.withdraw(token, amount). The amount must not exceed AccountInfo.AvailableFunds (pre-check can be disabled via WithSkipPrecheck).

type SettlementResult 

type SettlementResult struct {
	TotalSettledAmount      *big.Int
	TotalNetPayeeAmount     *big.Int
	TotalOperatorCommission *big.Int
	TotalNetworkFee         *big.Int
	FinalSettledEpoch       *big.Int
	Note                    string
}

SettlementResult is the decoded return tuple of FilPay.settleRail.

type WriteOption 

type WriteOption func(*writeConfig)

WriteOption tunes the behaviour of a single state-changing call. Nil options are ignored.

func WithConfirmations 

func WithConfirmations(n uint64) WriteOption

WithConfirmations requires N block confirmations in addition to WithWait. Has no effect unless WithWait is also passed with a positive timeout.

func WithFundApprovalLockupPeriod added in v0.4.0 

func WithFundApprovalLockupPeriod(period *big.Int) WriteOption

WithFundApprovalLockupPeriod overrides the max lockup period used when Fund / FundSync writes or checks FWSS approval.

func WithFundNeedsFwssApproval 

func WithFundNeedsFwssApproval(needs bool) WriteOption

WithFundNeedsFwssApproval overrides Fund / FundSync's approval-state probe. When set, Fund skips isFwssMaxApproved and uses the supplied decision directly so prepare/execute flows can reuse a previously computed result.

func WithSkipPrecheck 

func WithSkipPrecheck() WriteOption

WithSkipPrecheck disables client-side balance / allowance / funds checks before broadcasting. Useful when the caller has already validated state or wants to probe an on-chain revert for diagnostic purposes.

func WithWait 

func WithWait(timeout time.Duration) WriteOption

WithWait makes the call block until the transaction is mined, or the given timeout elapses. Use zero or a negative duration to return as soon as the tx is broadcast (the default).

type WriteResult 

type WriteResult = sdktypes.WriteResult

WriteResult is a convenience re-export of [types.WriteResult]. The two names refer to the same type and are interchangeable.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.