primary

package
v1.17.8 Latest Latest
Warning

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

 Go to latest Published: Jun 7, 2026 License: BSD-3-Clause Imports: 30 Imported by: 4

Documentation

Overview

Package primary provides primary network wallet operations.

Index

Constants

View Source 
const (
	MainnetAPIURI = "https://api.lux.network"
	TestnetAPIURI = "https://api.lux-test.network"
	LocalAPIURI   = "http://localhost:9630"
)

Variables

This section is empty.

Functions

func AddAllUTXOs 

func AddAllUTXOs(
	ctx context.Context,
	utxos walletcommon.UTXOs,
	client UTXOClient,
	unmarshaler UTXOUnmarshaler,
	sourceChainID ids.ID,
	destinationChainID ids.ID,
	addrs []ids.ShortID,
) error

AddAllUTXOs fetches all the UTXOs referenced by [addresses] that were sent from [sourceChainID] to [destinationChainID] from the [client]. It then uses [unmarshaler] to parse the returned UTXOs and it adds them into [utxos]. If [ctx] expires, then the returned error will be immediately reported.

[unmarshaler] is the chain's UTXO decoder. Today this is the upstream proto/{p,x}/txs codec satisfying UTXOUnmarshaler implicitly; once the upstream ZAP-native API ships (LP-023/LP-184), callers pass a typed ZAP UTXO accessor instead.

func NewChainUTXOs 

func NewChainUTXOs(chainID ids.ID, utxos UTXOs) common.ChainUTXOs

Types

type EthState 

type EthState struct {
	Client   *ethclient.Client
	Accounts map[gethcommon.Address]*c.Account
}

func FetchEthState 

func FetchEthState(
	ctx context.Context,
	uri string,
	addrs set.Set[gethcommon.Address],
) (*EthState, error)

type KeychainAdapter 

type KeychainAdapter struct {
	*secp256k1fx.Keychain
}

KeychainAdapter adapts secp256k1fx.Keychain to BOTH wallet/keychain.Keychain (UTXO-side) and c.EVMKeychain (EVM-side).

func NewKeychainAdapter 

func NewKeychainAdapter(kc *secp256k1fx.Keychain) *KeychainAdapter

NewKeychainAdapter creates a KeychainAdapter from a secp256k1fx.Keychain

func (*KeychainAdapter) Addresses 

func (kc *KeychainAdapter) Addresses() set.Set[ids.ShortID]

Addresses implements wallet/keychain.Keychain (UTXO-side).

func (*KeychainAdapter) EVMAddresses added in v1.16.62 

func (kc *KeychainAdapter) EVMAddresses() set.Set[gethcommon.Address]

EVMAddresses implements c.EVMKeychain (EVM-side address set).

func (*KeychainAdapter) Get 

func (kc *KeychainAdapter) Get(addr ids.ShortID) (keychain.Signer, bool)

Get implements keychain.Keychain (UTXO-side lookup by ShortID).

func (*KeychainAdapter) GetByEVM added in v1.16.62 

func (kc *KeychainAdapter) GetByEVM(addr gethcommon.Address) (keychain.Signer, bool)

GetByEVM implements c.EVMKeychain (EVM-side lookup by 20-byte addr).

type LUXState 

type LUXState struct {
	PClient *platformvm.Client
	PCTX    *pbuilder.Context
	// X-Chain: opt-in via AttachXChain. Nil if not attached or not registered on this network.
	XClient *XClient
	XCTX    *xbuilder.Context
	// C-Chain: opt-in via AttachCChain. EVM, fundamentally different from
	// UTXO P/X — uses ethclient. Nil if not attached or not registered.
	// CCTX would live in ./chain/c (EthClient + ChainID + GasPrice) — not
	// a UTXOCtx. Wired through FetchEthState today.
	UTXOs walletcommon.UTXOs
	// contains filtered or unexported fields
}

func FetchPState added in v1.17.8 

func FetchPState(
	ctx context.Context,
	uri string,
	addrs set.Set[ids.ShortID],
) (*LUXState, error)

FetchPState fetches ONLY the P-Chain client + context + UTXOs.

This is the canonical entry point. P-Chain is the only required chain for sovereign-L1 spawn (CreateChainTx), validator ops, primary network transactions. X-Chain (UTXO asset transfers) and C-Chain (EVM smart contracts) are opt-in — call AttachXChain / AttachCChain on the returned state if you need them.

Liquidity / sovereign-L1 callers: this is the function you want. Don't call FetchState (it tries to pull X + C, which is wasteful when they're not needed and breaks against P-only Quasar networks if not fail-softed correctly).

func FetchState 

func FetchState(
	ctx context.Context,
	uri string,
	addrs set.Set[ids.ShortID],
) (*LUXState, error)

FetchState is the P+X convenience that pre-fetches P (required) and X (opt-in via AttachXChain). Kept for back-compat. New callers should use FetchPState + AttachXChain / AttachCChain explicitly so the dependency graph is visible at the call site.

func (*LUXState) AttachXChain added in v1.17.8 

func (s *LUXState) AttachXChain(ctx context.Context) error

AttachXChain adds X-Chain client + context to the state. Fail-soft: if X-Chain is not registered on this network (Quasar mainnet is P+C only), returns the state unchanged with no error. Any other RPC error is returned.

type UTXOClient 

type UTXOClient interface {
	GetAtomicUTXOs(
		ctx context.Context,
		addrs []ids.ShortID,
		sourceChain string,
		limit uint32,
		startAddress ids.ShortID,
		startUTXOID ids.ID,
		options ...rpc.Option,
	) ([][]byte, ids.ShortID, ids.ID, error)
}

type UTXOUnmarshaler added in v1.17.1 

type UTXOUnmarshaler interface {
	Unmarshal(bytes []byte, dest interface{}) (uint16, error)
}

UTXOUnmarshaler decodes a UTXO byte buffer into the destination.

This is the minimal surface AddAllUTXOs needs to parse the bytes returned by GetAtomicUTXOs. Concretely satisfied today by github.com/luxfi/codec.Manager (linearcodec underneath), wired in via proto/p/txs.Codec and proto/x/txs.Codec.

TODO(LP-023/LP-184): once proto/p/txs and proto/x/txs expose ZAP-native WrapUTXO(b) accessors per LP-023 / LP-184 the new final Lux network wire, drop this interface and consume the typed Wrap*UTXO API directly. Until then we leave the upstream codec.Manager satisfying this interface so the SDK's only wire dep on luxfi/codec is the implicit interface satisfaction — no direct import.

type UTXOs 

type UTXOs interface {
	AddUTXO(ctx context.Context, sourceChainID, destinationChainID ids.ID, utxo *lux.UTXO) error
	RemoveUTXO(ctx context.Context, sourceChainID, destinationChainID, utxoID ids.ID) error

	UTXOs(ctx context.Context, sourceChainID, destinationChainID ids.ID) ([]*lux.UTXO, error)
	GetUTXO(ctx context.Context, sourceChainID, destinationChainID, utxoID ids.ID) (*lux.UTXO, error)
}

func NewUTXOs 

func NewUTXOs() UTXOs

type Wallet 

type Wallet interface {
	P() p.Wallet
	X() x.Wallet
	C() c.Wallet
}

Wallet provides chain wallets for the primary network.

func MakePChainWallet 

func MakePChainWallet(ctx context.Context, config *WalletConfig) (Wallet, error)

MakePChainWallet returns a wallet that only supports issuing P-chain transactions. This is an alias for MakeWallet for backward compatibility.

func MakeWallet 

func MakeWallet(ctx context.Context, config *WalletConfig) (Wallet, error)

MakeWallet returns a wallet that supports issuing transactions to the chains living in the primary network.

On creation, the wallet attaches to the provided uri and fetches all UTXOs that reference any of the provided keys. If the UTXOs are modified through an external issuance process, such as another instance of the wallet, the UTXOs may become out of sync. The wallet will also fetch all requested P-chain transactions.

The wallet manages all state locally, and performs all tx signing locally.

func NewWallet 

func NewWallet(p p.Wallet, x x.Wallet, c c.Wallet) Wallet

Creates a new default wallet

func NewWalletWithOptions 

func NewWalletWithOptions(w Wallet, options ...common.Option) Wallet

Creates a Wallet with the given set of options

type WalletConfig 

type WalletConfig struct {
	// Base URI to use for all node requests.
	URI string // required
	// Keys to use for signing all transactions.
	LUXKeychain keychain.Keychain // required
	EVMKeychain c.EVMKeychain     // required
	// Set of P-chain transactions that the wallet should know about to be able
	// to generate transactions.
	PChainTxs map[ids.ID]*txs.Tx // optional
	// Set of P-chain transactions that the wallet should fetch to be able to
	// generate transactions.
	PChainTxsToFetch set.Set[ids.ID] // optional
}

type XClient 

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

XClient is a client for interacting with the X-Chain

func NewXClient 

func NewXClient(uri, chainAlias string) *XClient

NewXClient returns a new X-Chain client

func NewXClientWithContext 

func NewXClientWithContext(uri string, networkID uint32, blockchainID ids.ID) *XClient

NewXClientWithContext returns a new X-Chain client with context information required for proper address formatting and UTXO queries. Note: Uses "X" alias for the endpoint (more reliable) but keeps blockchainID for address formatting in UTXO queries.

func (*XClient) GetAtomicUTXOs 

func (c *XClient) GetAtomicUTXOs(
	ctx context.Context,
	addrs []ids.ShortID,
	sourceChain string,
	limit uint32,
	startAddress ids.ShortID,
	startUTXOID ids.ID,
	options ...rpc.Option,
) ([][]byte, ids.ShortID, ids.ID, error)

GetAtomicUTXOs implements UTXOClient. Queries the X-chain for UTXOs controlled by the given addresses.

func (*XClient) SetContext 

func (c *XClient) SetContext(networkID uint32, blockchainID ids.ID)

SetContext sets the network context for address formatting

Source Files

View all Source files

Directories

Path Synopsis
Package common provides common wallet utilities.
 Package common provides common wallet utilities.
utxotest
Package utxotest provides UTXO testing utilities.
 Package utxotest provides UTXO testing utilities.

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.