penumbra

package
v8.7.1 Latest Latest
Warning

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

 Go to latest Published: Sep 18, 2024 License: Apache-2.0 Imports: 42 Imported by: 0

Documentation

Overview

Package penumbra provides an implementation of ibc.Chain for the Penumbra blockchain.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type GenesisFile 

type GenesisFile struct {
	Validators []GenesisValidators `json:"validators"`
}

type GenesisValidatorPubKey 

type GenesisValidatorPubKey struct {
	Type  string `json:"type"`
	Value string `json:"value"`
}

type GenesisValidators 

type GenesisValidators struct {
	Address string                 `json:"address"`
	Name    string                 `json:"name"`
	Power   string                 `json:"power"`
	PubKey  GenesisValidatorPubKey `json:"pub_key"`
}

type PcliConfig added in v8.6.0 

type PcliConfig struct {
	GrpcURL        string `toml:"grpc_url"`
	FullViewingKey string `toml:"full_viewing_key"`
	Custody        struct {
		Backend  string `toml:"backend"`
		SpendKey string `toml:"spend_key"`
	} `toml:"custody"`
}

PcliConfig represents the config.toml file associated with an instance of pcli.

type PenumbraAppNode 

type PenumbraAppNode struct {
	Index        int
	VolumeName   string
	Chain        *PenumbraChain
	TestName     string
	NetworkID    string
	DockerClient *client.Client
	Image        ibc.DockerImage
	// contains filtered or unexported fields
}

PenumbraAppNode represents an instance of pcli.

func NewPenumbraAppNode 

func NewPenumbraAppNode(
	ctx context.Context,
	log *zap.Logger,
	chain *PenumbraChain,
	index int,
	testName string,
	dockerClient *dockerclient.Client,
	networkID string,
	image ibc.DockerImage,
) (*PenumbraAppNode, error)

NewPenumbraAppNode creates a new instance of PenumbraAppNode with the provided parameters. It initializes the PenumbraAppNode struct, sets the logger, index, chain, Docker client, network ID, test name, and Docker image. It also creates a container lifecycle instance with the provided logger, Docker client, and node name before creating a Docker volume with labels for cleanup and owner identification. Finally, the created PenumbraAppNode instance is returned along with a nil error, or a nil PenumbraAppNode and a non-nil error if any step in the process fails.

func (*PenumbraAppNode) AllocationsInputFileContainer 

func (p *PenumbraAppNode) AllocationsInputFileContainer() string

AllocationsInputFileContainer returns the path to the allocations.csv file that should be used to generate the genesis file before spinning up the network from a fresh genesis.

func (*PenumbraAppNode) Bind 

func (p *PenumbraAppNode) Bind() []string

Bind returns the home folder bind point for running the node.

func (*PenumbraAppNode) CreateKey 

func (p *PenumbraAppNode) CreateKey(ctx context.Context, keyName string) error

CreateKey attempts to initialize a new pcli config file with a newly generated FullViewingKey and CustodyKey.

func (*PenumbraAppNode) CreateNodeContainer 

func (p *PenumbraAppNode) CreateNodeContainer(ctx context.Context, tendermintAddress string) error

CreateNodeContainer creates a container for the PenumbraAppNode. It starts the PenumbraAppNode process with the specified tendermintAddress. The method returns any errors encountered during the container creation process.

func (*PenumbraAppNode) Exec 

func (p *PenumbraAppNode) Exec(ctx context.Context, cmd []string, env []string) ([]byte, []byte, error)

Exec run a container for a specific job and blocks until the container exits.

func (*PenumbraAppNode) FullViewingKey 

func (p *PenumbraAppNode) FullViewingKey(ctx context.Context, keyName string) (string, error)

FullViewingKey attempts to read the FullViewingKey from the config.toml file associated with this instance of pcli.

func (*PenumbraAppNode) GenerateGenesisFile 

func (p *PenumbraAppNode) GenerateGenesisFile(
	ctx context.Context,
	chainID string,
	validators []PenumbraValidatorDefinition,
	allocations []PenumbraGenesisAppStateAllocation,
) error

GenerateGenesisFile attempts to create the validators.json file and the allocations.csv file, write the files to the Docker filesystem, and then generate the directory structure containing necessary files to create a new testnet from genesis via an instance of pd.

func (*PenumbraAppNode) GetAddress 

func (p *PenumbraAppNode) GetAddress(ctx context.Context, keyName string) ([]byte, error)

GetAddress attempts to return a Penumbra address associated with a specified key name.

func (*PenumbraAppNode) GetAddressBech32m 

func (p *PenumbraAppNode) GetAddressBech32m(ctx context.Context, keyName string) (string, error)

GetAddressBech32m retrieves the address associated with the specified key name. It executes the 'pcli' command and parses the output to find the desired address. The function returns the retrieved address as a string and an error if any occurred.

func (*PenumbraAppNode) GetBalance 

func (p *PenumbraAppNode) GetBalance(ctx context.Context, keyName string) (int64, error)

GetBalance attempts to query the token balances for a specified key name via an instance of pcli. TODO we need to change the func sig to take a denom then filter out the target denom bal from stdout

func (*PenumbraAppNode) HomeDir 

func (p *PenumbraAppNode) HomeDir() string

HomeDir returns the home directory location in the Docker filesystem.

func (*PenumbraAppNode) HostName 

func (p *PenumbraAppNode) HostName() string

HostName returns the hostname of the test node container.

func (*PenumbraAppNode) InitValidatorFile 

func (p *PenumbraAppNode) InitValidatorFile(ctx context.Context, valKeyName string) error

InitValidatorFile initializes validator definition template file, wallet must be generated first.

func (*PenumbraAppNode) Name 

func (p *PenumbraAppNode) Name() string

Name of the test node container.

func (*PenumbraAppNode) ReadFile added in v8.6.0 

func (p *PenumbraAppNode) ReadFile(ctx context.Context, relPath string) ([]byte, error)

ReadFile attempts to read a file from the Docker filesystem at the specified path. relPath describes the location of the file in the Docker volume relative to the home directory.

func (*PenumbraAppNode) RecoverKey 

func (p *PenumbraAppNode) RecoverKey(ctx context.Context, keyName, mnemonic string) error

RecoverKey restores a key from a given mnemonic.

func (*PenumbraAppNode) SendIBCTransfer added in v8.1.0 

func (p *PenumbraAppNode) SendIBCTransfer(ctx context.Context, channelID, keyName string, amount ibc.WalletAmount, opts ibc.TransferOptions) (ibc.Tx, error)

SendIBCTransfer sends an IBC transfer from the specified address to some destination address on a specified channel.

func (*PenumbraAppNode) StartContainer 

func (p *PenumbraAppNode) StartContainer(ctx context.Context) error

StartContainer starts the test node container, if an error occurs it is returned. The obtained host ports are assigned to the hostRPCPort and hostGRPCPort fields of the PenumbraAppNode struct. Finally, nil is returned if everything is successful.

func (*PenumbraAppNode) StopContainer 

func (p *PenumbraAppNode) StopContainer(ctx context.Context) error

StopContainer stops the running container for the PenumbraAppNode.

func (*PenumbraAppNode) ValidatorDefinitionTemplateFilePathContainer 

func (p *PenumbraAppNode) ValidatorDefinitionTemplateFilePathContainer() string

ValidatorDefinitionTemplateFilePathContainer returns the path to the validator.toml file associated with this instance of pcli.

func (*PenumbraAppNode) ValidatorsInputFileContainer 

func (p *PenumbraAppNode) ValidatorsInputFileContainer() string

ValidatorsInputFileContainer returns the path to the validators.json file associated with this instance of pcli.

type PenumbraChain 

type PenumbraChain struct {
	PenumbraNodes PenumbraNodes
	// contains filtered or unexported fields
}

func NewPenumbraChain 

func NewPenumbraChain(log *zap.Logger, testName string, chainConfig ibc.ChainConfig, numValidators int, numFullNodes int) *PenumbraChain

NewPenumbraChain returns a new instance of PenumbraChain.

func (*PenumbraChain) Acknowledgements 

func (c *PenumbraChain) Acknowledgements(ctx context.Context, height int64) ([]ibc.PacketAcknowledgement, error)

Acknowledgements implements Chain interface.

func (*PenumbraChain) BuildRelayerWallet 

func (c *PenumbraChain) BuildRelayerWallet(ctx context.Context, keyName string) (ibc.Wallet, error)

BuildRelayerWallet will return a Penumbra wallet populated with the mnemonic so that the wallet can be restored in the relayer node using the mnemonic. After it is built, that address is included in genesis with some funds.

func (*PenumbraChain) BuildWallet 

func (c *PenumbraChain) BuildWallet(ctx context.Context, keyName string, mnemonic string) (ibc.Wallet, error)

BuildWallet will return a Penumbra wallet. If mnemonic != "", it will restore using that mnemonic. If mnemonic == "", it will create a new key.

func (*PenumbraChain) Config 

func (c *PenumbraChain) Config() ibc.ChainConfig

Config returns the Chain's ChainConfig.

func (*PenumbraChain) CreateClientNode 

func (c *PenumbraChain) CreateClientNode(
	ctx context.Context,
	keyName string,
) error

CreateClientNode initializes a new instance of pclientd, with the FullViewingKey and CustodyKey, associated with the specified keyName.

func (*PenumbraChain) CreateKey 

func (c *PenumbraChain) CreateKey(ctx context.Context, keyName string) error

CreateKey derives a new key with the given keyName.

func (*PenumbraChain) Exec 

func (c *PenumbraChain) Exec(ctx context.Context, cmd []string, env []string) (stdout, stderr []byte, err error)

Exec attempts to execute an arbitrary cmd with specified env variables and returns the output returned to both stdout and stderr.

func (*PenumbraChain) ExportState 

func (c *PenumbraChain) ExportState(context.Context, int64) (string, error)

ExportState implements Chain interface.

func (*PenumbraChain) GetAddress 

func (c *PenumbraChain) GetAddress(ctx context.Context, keyName string) ([]byte, error)

GetAddress returns the byte representation of an address for the specified keyName.

func (*PenumbraChain) GetBalance 

func (c *PenumbraChain) GetBalance(ctx context.Context, keyName string, denom string) (math.Int, error)

GetBalance attempts to make a balance request for the specified denom and the account associated with the specified keyName.

func (*PenumbraChain) GetGRPCAddress 

func (c *PenumbraChain) GetGRPCAddress() string

GetGRPCAddress returns the GRPC address associated with an underlying node's Tendermint host name.

func (*PenumbraChain) GetGasFeesInNativeDenom 

func (c *PenumbraChain) GetGasFeesInNativeDenom(gasPaid int64) int64

GetGasFeesInNativeDenom returns the fees used to pay for some compute with the local token denom, where fees = gasPaid * gasPrice.

func (*PenumbraChain) GetHostGRPCAddress 

func (c *PenumbraChain) GetHostGRPCAddress() string

GetHostGRPCAddress returns the address of the gRPC server accessible by the host. This will not return a valid address until the chain has been started.

func (*PenumbraChain) GetHostPeerAddress added in v8.1.0 

func (c *PenumbraChain) GetHostPeerAddress() string

Implements Chain interface

func (*PenumbraChain) GetHostRPCAddress 

func (c *PenumbraChain) GetHostRPCAddress() string

GetHostRPCAddress returns the address of the RPC server accessible by the host. This will not return a valid address until the chain has been started.

func (*PenumbraChain) GetRPCAddress 

func (c *PenumbraChain) GetRPCAddress() string

GetRPCAddress returns the RPC address associated with an underlying node's Tendermint host name.

func (*PenumbraChain) Height 

func (c *PenumbraChain) Height(ctx context.Context) (int64, error)

Height returns the current chain block height.

func (*PenumbraChain) HomeDir 

func (c *PenumbraChain) HomeDir() string

HomeDir returns the PenumbraAppNode's home directory in the Docker filesystem.

func (*PenumbraChain) Initialize 

func (c *PenumbraChain) Initialize(ctx context.Context, testName string, cli *client.Client, networkID string) error

Initialize creates the test node objects required for bootstrapping tests.

func (*PenumbraChain) RecoverKey 

func (c *PenumbraChain) RecoverKey(ctx context.Context, name, mnemonic string) error

RecoverKey restores an existing key with the given mnemonic and associates it with the specified key name in the keyring.

func (*PenumbraChain) SendFunds 

func (c *PenumbraChain) SendFunds(ctx context.Context, keyName string, amount ibc.WalletAmount) error

SendFunds will initiate a local transfer from the account associated with the specified keyName, amount, token denom, and recipient are specified in the amount.

func (*PenumbraChain) SendFundsWithNote added in v8.7.0 

func (c *PenumbraChain) SendFundsWithNote(ctx context.Context, keyName string, amount ibc.WalletAmount, note string) (string, error)

SendFundsWithNote will initiate a local transfer from the account associated with the specified keyName, amount, token denom, and recipient are specified in the amount and attach a note/memo

func (*PenumbraChain) SendIBCTransfer 

func (c *PenumbraChain) SendIBCTransfer(
	ctx context.Context,
	channelID string,
	keyName string,
	amount ibc.WalletAmount,
	options ibc.TransferOptions,
) (ibc.Tx, error)

SendIBCTransfer attempts to send a fungible token transfer via IBC from the specified account on the source chain to the specified account on the counterparty chain.

func (*PenumbraChain) Start 

func (c *PenumbraChain) Start(_ string, ctx context.Context, additionalGenesisWallets ...ibc.WalletAmount) error

Start sets up everything needed, (validators, gentx, fullnodes, peering, additional accounts), for the chain to start from genesis.

func (*PenumbraChain) Timeouts 

func (c *PenumbraChain) Timeouts(ctx context.Context, height int64) ([]ibc.PacketTimeout, error)

Timeouts implements Chain interface.

type PenumbraClientNode 

type PenumbraClientNode struct {
	KeyName      string
	Index        int
	VolumeName   string
	Chain        ibc.Chain
	TestName     string
	NetworkID    string
	DockerClient *client.Client
	Image        ibc.DockerImage

	GRPCConn *grpc.ClientConn
	// contains filtered or unexported fields
}

PenumbraClientNode represents an instance of pclientd.

func NewClientNode 

func NewClientNode(
	ctx context.Context,
	log *zap.Logger,
	chain *PenumbraChain,
	keyName string,
	index int,
	testName string,
	image ibc.DockerImage,
	dockerClient *client.Client,
	networkID string,
	address []byte,
	addrString string,
) (*PenumbraClientNode, error)

NewClientNode attempts to initialize a new instance of pclientd. It then attempts to create the Docker container lifecycle and the Docker volume before setting the volume owner.

func (*PenumbraClientNode) Bind 

func (p *PenumbraClientNode) Bind() []string

Bind returns the home folder bind point for running the node.

func (*PenumbraClientNode) CreateNodeContainer 

func (p *PenumbraClientNode) CreateNodeContainer(ctx context.Context) error

CreateNodeContainer creates a container for the Penumbra client node.

func (*PenumbraClientNode) Exec 

func (p *PenumbraClientNode) Exec(ctx context.Context, cmd []string, env []string) ([]byte, []byte, error)

Exec runs a container for a specific job and blocks until the container exits.

func (*PenumbraClientNode) GetAddress 

func (p *PenumbraClientNode) GetAddress(ctx context.Context) ([]byte, error)

GetAddress returns the Bech32m encoded string of the inner bytes as a slice of bytes.

func (*PenumbraClientNode) GetBalance 

func (p *PenumbraClientNode) GetBalance(ctx context.Context, denom string) (math.Int, error)

GetBalance retrieves the balance of a specific denom for the PenumbraClientNode.

It creates a client for the ViewProtocolService and constructs a BalancesRequest with an AccountFilter and AssetIdFilter. A Balances stream response is obtained from the server. The balances are collected in a slice until the stream is done, or an error occurs. Otherwise, the first balance in the slice is used to construct a math.Int value and returned. Returns: - math.Int: The balance of the specified denom. - error: An error if any occurred during the balance retrieval.

func (*PenumbraClientNode) GetDenomMetadata 

func (p *PenumbraClientNode) GetDenomMetadata(ctx context.Context, assetId *asset.AssetId) (*asset.Metadata, error)

GetDenomMetadata invokes a gRPC request to obtain the DenomMetadata for a specified asset ID.

func (*PenumbraClientNode) HomeDir 

func (p *PenumbraClientNode) HomeDir() string

HomeDir returns the home directory for this instance of pclientd in the Docker filesystem.

func (*PenumbraClientNode) HostName 

func (p *PenumbraClientNode) HostName() string

HostName returns the hostname of the test node container.

func (*PenumbraClientNode) Initialize 

func (p *PenumbraClientNode) Initialize(ctx context.Context, pdAddress, spendKey, fullViewingKey string) error

Initialize loads the view and spend keys into the pclientd config.

func (*PenumbraClientNode) Name 

func (p *PenumbraClientNode) Name() string

Name of the test node container.

func (*PenumbraClientNode) SendFunds 

func (p *PenumbraClientNode) SendFunds(ctx context.Context, amount ibc.WalletAmount) error

SendFunds sends funds from the PenumbraClientNode to a specified address. It generates a transaction plan, gets authorization data for the transaction, builds and signs the transaction, and broadcasts it. Returns an error if any step of the process fails.

func (*PenumbraClientNode) SendIBCTransfer 

func (p *PenumbraClientNode) SendIBCTransfer(
	ctx context.Context,
	channelID string,
	amount ibc.WalletAmount,
	options ibc.TransferOptions,
) (ibc.Tx, error)

SendIBCTransfer sends an IBC transfer from the current PenumbraClientNode to a specified destination address on a specified channel. The function validates the address string on the current PenumbraClientNode instance. If the address string is empty, it returns an error. It translates the amount to a big integer and creates an `ibcv1.Ics20Withdrawal` with the amount, denom, destination address, return address, timeout height, timeout timestamp

func (*PenumbraClientNode) StartContainer 

func (p *PenumbraClientNode) StartContainer(ctx context.Context) error

StartContainer starts the test node container.

func (*PenumbraClientNode) StopContainer 

func (p *PenumbraClientNode) StopContainer(ctx context.Context) error

StopContainer stops the container associated with the PenumbraClientNode.

func (*PenumbraClientNode) WriteFile 

func (p *PenumbraClientNode) WriteFile(ctx context.Context, content []byte, relPath string) error

WriteFile accepts file contents in a byte slice and writes the contents to the Docker filesystem. relPath describes the location of the file in the Docker volume relative to the home directory.

type PenumbraConsensusKey 

type PenumbraConsensusKey struct {
	Type  string `json:"type" toml:"type"`
	Value string `json:"value" toml:"value"`
}

type PenumbraCustodyKey 

type PenumbraCustodyKey struct {
	SpendKey string `json:"spend_key"`
}

type PenumbraGenesisAppStateAllocation 

type PenumbraGenesisAppStateAllocation struct {
	Amount  math.Int `json:"amount"`
	Denom   string   `json:"denom"`
	Address string   `json:"address"`
}

type PenumbraNode 

type PenumbraNode struct {
	TendermintNode      *tendermint.TendermintNode
	PenumbraAppNode     *PenumbraAppNode
	PenumbraClientNodes map[string]*PenumbraClientNode
	// contains filtered or unexported fields
}

PenumbraNode reporesents a node in the Penumbra network which consists of one instance of Tendermint, an instance of pcli, and zero or more instances of pclientd.

func NewPenumbraNode 

func NewPenumbraNode(
	ctx context.Context,
	i int,
	c *PenumbraChain,
	dockerClient *dockerclient.Client,
	networkID string,
	testName string,
	tendermintImage ibc.DockerImage,
	penumbraImage ibc.DockerImage,
) (PenumbraNode, error)

NewPenumbraNode returns a penumbra chain node with tendermint and penumbra nodes, along with docker volumes created.

func (*PenumbraNode) CreateClientNode 

func (p *PenumbraNode) CreateClientNode(
	ctx context.Context,
	log *zap.Logger,
	dockerClient *dockerclient.Client,
	networkID string,
	image ibc.DockerImage,
	testName string,
	index int,
	keyName string,
	spendKey string,
	fullViewingKey string,
) error

CreateClientNode initializes a new instance of pclientd, with the specified FullViewingKey and CustodyKey, before attempting to create and start pclientd in a new Docker container.

type PenumbraNodes 

type PenumbraNodes []*PenumbraNode

PenumbraNodes is a slice of pointers that point to instances of PenumbraNode in memory.

type PenumbraValidatorDefinition 

type PenumbraValidatorDefinition struct {
	SequenceNumber int                              `json:"sequence_number" toml:"sequence_number"`
	Enabled        bool                             `json:"enabled" toml:"enabled"`
	Name           string                           `json:"name" toml:"name"`
	Website        string                           `json:"website" toml:"website"`
	Description    string                           `json:"description" toml:"description"`
	IdentityKey    string                           `json:"identity_key" toml:"identity_key"`
	GovernanceKey  string                           `json:"governance_key" toml:"governance_key"`
	ConsensusKey   PenumbraConsensusKey             `json:"consensus_key" toml:"consensus_key"`
	FundingStreams []PenumbraValidatorFundingStream `json:"funding_streams" toml:"funding_stream"`
}

type PenumbraValidatorFundingStream 

type PenumbraValidatorFundingStream struct {
	Recipient string `json:"address" toml:"recipient"`
	RateBPS   int64  `json:"rate_bps" toml:"rate_bps"`
}

type PenumbraWallet 

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

PenumbraWallet represents a wallet for the Penumbra application.

func NewWallet 

func NewWallet(keyname string, address []byte, mnemonic string, chainCfg ibc.ChainConfig) *PenumbraWallet

NewWallet creates a new instance of PenumbraWallet with the provided parameters

func (*PenumbraWallet) Address 

func (w *PenumbraWallet) Address() []byte

Address returns the slice of bytes representing this PenumbraWallet instance's address.

func (*PenumbraWallet) FormattedAddress 

func (w *PenumbraWallet) FormattedAddress() string

FormattedAddress returns the formatted address associated with a PenumbraWallet instance.

func (*PenumbraWallet) FormattedAddressWithPrefix 

func (w *PenumbraWallet) FormattedAddressWithPrefix(prefix string) string

FormattedAddressWithPrefix returns the formatted address string with a given prefix. The prefix is a string that will be appended to the beginning of the address. It takes the address stored in the PenumbraWallet instance and converts it to a string.

func (*PenumbraWallet) KeyName 

func (w *PenumbraWallet) KeyName() string

KeyName returns the key name associated with a PenumbraWallet instance.

func (*PenumbraWallet) Mnemonic 

func (w *PenumbraWallet) Mnemonic() string

Mnemonic returns the mnemonic associated with a PenumbraWallet instance.

type ValidatorWithIntPower 

type ValidatorWithIntPower struct {
	Address      string
	Power        int64
	PubKeyBase64 string
}

Source Files

View all Source files

Directories

Path Synopsis
cnidarium
v1
core
app/v1
asset/v1
component/auction/v1
component/community_pool/v1
component/compact_block/v1
component/dex/v1
component/distributions/v1
component/fee/v1
component/funding/v1
component/governance/v1
component/ibc/v1
component/sct/v1
component/shielded_pool/v1
component/stake/v1
keys/v1
num/v1
transaction/v1
txhash/v1
crypto
decaf377_fmd/v1
decaf377_frost/v1
decaf377_rdsa/v1
tct/v1
custody
threshold/v1
v1
tools
summoning/v1
util
tendermint_proxy/v1
view
v1

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.