diff --git a/docs/docs/02-guide/08-state.md b/docs/docs/02-guide/08-state.md index 1acaaeeb0a..44cf08ae36 100644 --- a/docs/docs/02-guide/08-state.md +++ b/docs/docs/02-guide/08-state.md @@ -9,7 +9,7 @@ In blockchain applications, state refers to the current data stored on the block ## Collections Package -IGNITE® scaffolds using the [`collections`](http://pkg.go.dev/cosmossdk.io/collections) package for module code. This package provides a type-safe and efficient way to set and query values from the module store. +IGNITE® scaffolds using the [`collections`](https://pkg.go.dev/cosmossdk.io/collections) package for module code. This package provides a type-safe and efficient way to set and query values from the module store. ### Key Features of Collections diff --git a/docs/docs/07-packages/chaincmd.md b/docs/docs/07-packages/chaincmd.md new file mode 100644 index 0000000000..e209a75cf1 --- /dev/null +++ b/docs/docs/07-packages/chaincmd.md @@ -0,0 +1,51 @@ +--- +sidebar_position: 7 +title: Chain Command Builder (chaincmd) +slug: /packages/chaincmd +--- + +# Chain Command Builder (chaincmd) + +The `chaincmd` package builds `step.Option` command definitions for Cosmos SDK daemon binaries (`simd`, `gaiad`, and others). It does not execute commands directly. + +For full API details, see the +[`chaincmd` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/chaincmd). + +## When to use + +- Build consistent daemon command lines from typed options. +- Reuse command composition across services and tests. +- Keep chain binary-specific flags centralized. + +## Key APIs + +- `New(appCmd string, options ...Option) ChainCmd` +- `WithHome(home string) Option` +- `WithChainID(chainID string) Option` +- `InitCommand(moniker string, options ...string) step.Option` +- `BankSendCommand(fromAddress, toAddress, amount string, options ...BankSendOption) step.Option` + +## Example + +```go +package main + +import ( + "fmt" + + "github.com/ignite/cli/v29/ignite/pkg/chaincmd" + "github.com/ignite/cli/v29/ignite/pkg/cmdrunner/step" +) + +func main() { + cmd := chaincmd.New( + "simd", + chaincmd.WithHome("./.simapp"), + chaincmd.WithChainID("demo-1"), + ) + + initStep := step.New(cmd.InitCommand("validator")) + fmt.Println(initStep.Exec.Command) + fmt.Println(initStep.Exec.Args) +} +``` diff --git a/docs/docs/07-packages/chaincmdrunner.md b/docs/docs/07-packages/chaincmdrunner.md new file mode 100644 index 0000000000..2661a068e0 --- /dev/null +++ b/docs/docs/07-packages/chaincmdrunner.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 4 +title: Chain Command Runner (chaincmd/runner) +slug: /packages/chaincmdrunner +--- + +# Chain Command Runner (chaincmd/runner) + +The `chaincmdrunner` package wraps chain binary commands into typed, higher-level operations (accounts, genesis setup, tx queries, node control). + +For full API details, see the +[`chaincmdrunner` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/chaincmd/runner). + +## When to use + +- Execute chain lifecycle commands without manually assembling CLI arguments. +- Manage accounts and genesis setup from automation/test flows. +- Query transaction events using typed selectors instead of raw command output parsing. + +## Key APIs + +- `New(ctx context.Context, chainCmd chaincmd.ChainCmd, options ...Option) (Runner, error)` +- `(Runner) Init(ctx context.Context, moniker string, args ...string) error` +- `(Runner) Start(ctx context.Context, args ...string) error` +- `(Runner) AddAccount(ctx context.Context, name, mnemonic, coinType, accountNumber, addressIndex string) (Account, error)` +- `(Runner) AddGenesisAccount(ctx context.Context, address, coins string) error` +- `(Runner) QueryTxByEvents(ctx context.Context, selectors ...EventSelector) ([]Event, error)` +- `(Runner) WaitTx(ctx context.Context, txHash string, retryDelay time.Duration, maxRetry int) error` + +## Common Tasks + +- Build a `Runner` from a configured `chaincmd.ChainCmd` and then call `Init`/`Start` for local node workflows. +- Use `AddAccount`, `ListAccounts`, and `ShowAccount` to manage keyring state in scripted flows. +- Query and filter tx events with `NewEventSelector` plus `QueryTxByEvents`. + +## Basic import + +```go +import chaincmdrunner "github.com/ignite/cli/v29/ignite/pkg/chaincmd/runner" +``` diff --git a/docs/docs/07-packages/chainregistry.md b/docs/docs/07-packages/chainregistry.md new file mode 100644 index 0000000000..980f73cd08 --- /dev/null +++ b/docs/docs/07-packages/chainregistry.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 3 +title: Chain Registry Types (chainregistry) +slug: /packages/chainregistry +--- + +# Chain Registry Types (chainregistry) + +The `chainregistry` package defines strongly-typed Go structs for Cosmos chain-registry data (`chain.json` and `assetlist.json`). + +For full API details, see the +[`chainregistry` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/chainregistry). + +## When to use + +- Parse chain-registry JSON into typed values. +- Build tooling that reads chain metadata (APIs, fees, staking tokens, assets). +- Validate or transform registry documents before writing them back. + +## Key APIs + +- `type Chain struct{ ... }` +- `type APIs struct{ ... }` +- `type APIProvider struct{ ... }` +- `type AssetList struct{ ... }` +- `type Asset struct{ ... }` +- `type Fees struct{ ... }` +- `type Staking struct{ ... }` +- `type Codebase struct{ ... }` +- `type ChainStatus string` +- `type ChainType string` + +## Common Tasks + +- Decode `chain.json` data into a `Chain` value and inspect RPC/REST metadata. +- Decode `assetlist.json` into `AssetList` to access denom units and logo URIs. +- Use enum-like types (`ChainStatus`, `NetworkType`, `ChainType`) to keep metadata checks explicit. + +## Basic import + +```go +import "github.com/ignite/cli/v29/ignite/pkg/chainregistry" +``` diff --git a/docs/docs/07-packages/cosmosaccount.md b/docs/docs/07-packages/cosmosaccount.md new file mode 100644 index 0000000000..f0acd75199 --- /dev/null +++ b/docs/docs/07-packages/cosmosaccount.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 2 +title: Account Registry (cosmosaccount) +slug: /packages/cosmosaccount +--- + +# Account Registry (cosmosaccount) + +The `cosmosaccount` package manages Cosmos keyring accounts (create/import/export/list/delete) with configurable backend and Bech32 settings. + +For full API details, see the +[`cosmosaccount` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/cosmosaccount). + +## When to use + +- Manage CLI account keys in Ignite services and commands. +- Switch between `test`, `os`, and `memory` keyring backends. +- Resolve addresses/public keys from named keyring entries. + +## Key APIs + +- `New(options ...Option) (Registry, error)` +- `NewInMemory(options ...Option) (Registry, error)` +- `WithKeyringBackend(backend KeyringBackend) Option` +- `WithHome(path string) Option` +- `(Registry) Create(name string) (Account, mnemonic string, err error)` +- `(Registry) Import(name, secret, passphrase string) (Account, error)` +- `(Registry) Export(name, passphrase string) (key string, err error)` +- `(Registry) GetByName(name string) (Account, error)` +- `(Registry) List() ([]Account, error)` +- `(Account) Address(accPrefix string) (string, error)` + +## Common Tasks + +- Instantiate one `Registry` with backend/home options and reuse it for all key operations. +- Call `EnsureDefaultAccount` in setup paths that require a predictable signer account. +- Resolve addresses with `Account.Address(prefix)` when your app uses non-default Bech32 prefixes. + +## Basic import + +```go +import "github.com/ignite/cli/v29/ignite/pkg/cosmosaccount" +``` diff --git a/docs/docs/07-packages/cosmosanalysis.md b/docs/docs/07-packages/cosmosanalysis.md new file mode 100644 index 0000000000..9b5286a5e7 --- /dev/null +++ b/docs/docs/07-packages/cosmosanalysis.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 13 +title: Cosmos Source Analysis (cosmosanalysis) +slug: /packages/cosmosanalysis +--- + +# Cosmos Source Analysis (cosmosanalysis) + +The `cosmosanalysis` package provides static analysis helpers for Cosmos SDK-based projects, especially for app structure and interface/embed discovery. + +For full API details, see the +[`cosmosanalysis` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/cosmosanalysis). + +## When to use + +- Validate that a directory is a Cosmos chain project before running codegen. +- Locate key app files and embedded types in Cosmos app sources. +- Detect interface implementations across module files. + +## Key APIs + +- `IsChainPath(path string) error` +- `FindAppFilePath(chainRoot string) (path string, err error)` +- `ValidateGoMod(module *modfile.File) error` +- `FindImplementation(modulePath string, interfaceList []string) (found []string, err error)` +- `DeepFindImplementation(modulePath string, interfaceList []string) (found []string, err error)` +- `FindEmbed(modulePath string, targetEmbeddedTypes []string) (found []string, err error)` +- `FindEmbedInFile(n ast.Node, targetEmbeddedTypes []string) (found []string)` + +## Common Tasks + +- Call `IsChainPath` early to fail fast on unsupported project layouts. +- Use `FindAppFilePath` before AST transformations that require the chain app entrypoint. +- Use `FindImplementation`/`DeepFindImplementation` to verify generated modules are wired as expected. + +## Basic import + +```go +import "github.com/ignite/cli/v29/ignite/pkg/cosmosanalysis" +``` diff --git a/docs/docs/07-packages/cosmosbuf.md b/docs/docs/07-packages/cosmosbuf.md new file mode 100644 index 0000000000..70bc9ea77a --- /dev/null +++ b/docs/docs/07-packages/cosmosbuf.md @@ -0,0 +1,58 @@ +--- +sidebar_position: 14 +title: Buf Integration (cosmosbuf) +slug: /packages/cosmosbuf +--- + +# Buf Integration (cosmosbuf) + +The `cosmosbuf` package wraps Buf workflows (`generate`, `export`, `format`, `migrate`, `dep update`) used by Ignite's protobuf pipelines. + +For full API details, see the +[`cosmosbuf` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/cosmosbuf). + +## When to use + +- Trigger Buf code generation from Go services. +- Keep Buf invocation flags and error handling consistent. +- Reuse cache-aware generation behavior. + +## Key APIs + +- `New(cacheStorage cache.Storage, goModPath string) (Buf, error)` +- `(Buf) Generate(ctx, protoPath, output, template, options...)` +- `(Buf) Format(ctx, path)` +- `(Buf) Export(ctx, protoDir, output)` +- `Version(ctx context.Context) (string, error)` + +## Example + +```go +package main + +import ( + "context" + "log" + "os" + "path/filepath" + + "github.com/ignite/cli/v29/ignite/pkg/cache" + "github.com/ignite/cli/v29/ignite/pkg/cosmosbuf" +) + +func main() { + storage, err := cache.NewStorage(filepath.Join(os.TempDir(), "ignite-cache.db")) + if err != nil { + log.Fatal(err) + } + + buf, err := cosmosbuf.New(storage, "github.com/acme/my-chain") + if err != nil { + log.Fatal(err) + } + + if err := buf.Format(context.Background(), "./proto"); err != nil { + log.Fatal(err) + } +} +``` diff --git a/docs/docs/07-packages/cosmosclient.md b/docs/docs/07-packages/cosmosclient.md new file mode 100644 index 0000000000..c7728ef2f1 --- /dev/null +++ b/docs/docs/07-packages/cosmosclient.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 1 +title: Blockchain Client (cosmosclient) +slug: /packages/cosmosclient +--- + +# Blockchain Client (cosmosclient) + +The `cosmosclient` package provides a high-level client for querying Cosmos SDK chains and building/signing/broadcasting transactions. + +For full API details, see the +[`cosmosclient` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/cosmosclient). + +## When to use + +- Connect Ignite tooling to a running node for status and block queries. +- Build and broadcast SDK messages with shared gas/fees/keyring settings. +- Wait for transaction inclusion and inspect block transactions/events. + +## Key APIs + +- `New(ctx context.Context, options ...Option) (Client, error)` +- `WithNodeAddress(addr string) Option` +- `WithHome(path string) Option` +- `WithKeyringBackend(backend cosmosaccount.KeyringBackend) Option` +- `WithGas(gas string) Option` +- `WithGasPrices(gasPrices string) Option` +- `(Client) BroadcastTx(ctx, account, msgs...) (Response, error)` +- `(Client) WaitForTx(ctx context.Context, hash string) (*ctypes.ResultTx, error)` +- `(Client) Status(ctx context.Context) (*ctypes.ResultStatus, error)` +- `(Client) LatestBlockHeight(ctx context.Context) (int64, error)` + +## Common Tasks + +- Initialize one `Client` instance with node and keyring options, then reuse it across operations. +- Call `CreateTxWithOptions` or `BroadcastTx` depending on whether you need fine-grained tx overrides. +- Use `WaitForTx`, `WaitForNextBlock`, or `WaitForBlockHeight` for deterministic flows in tests/automation. + +## Basic import + +```go +import "github.com/ignite/cli/v29/ignite/pkg/cosmosclient" +``` diff --git a/docs/docs/07-packages/cosmosfaucet.md b/docs/docs/07-packages/cosmosfaucet.md new file mode 100644 index 0000000000..4927fba06d --- /dev/null +++ b/docs/docs/07-packages/cosmosfaucet.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 5 +title: Token Faucet (cosmosfaucet) +slug: /packages/cosmosfaucet +--- + +# Token Faucet (cosmosfaucet) + +The `cosmosfaucet` package provides a local faucet service and client helpers to fund Cosmos accounts during development and tests. + +For full API details, see the +[`cosmosfaucet` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/cosmosfaucet). + +## When to use + +- Automatically fund accounts in local/devnet environments. +- Expose a faucet HTTP endpoint backed by a chain key. +- Request funds from an existing faucet endpoint from automation code. + +## Key APIs + +- `New(ctx context.Context, ccr chaincmdrunner.Runner, options ...Option) (Faucet, error)` +- `TryRetrieve(ctx context.Context, chainID, rpcAddress, faucetAddress, accountAddress string) (string, error)` +- `OpenAPI(apiAddress string) Option` +- `Coin(amount, maxAmount sdkmath.Int, denom string) Option` +- `FeeAmount(amount sdkmath.Int, denom string) Option` +- `RefreshWindow(refreshWindow time.Duration) Option` +- `NewTransferRequest(accountAddress string, coins []string) TransferRequest` + +## Common Tasks + +- Construct a `Faucet` with chain runner + options, then expose transfer endpoints for local users. +- Use `TryRetrieve` in tests before broadcasting txs to ensure accounts have spendable balance. +- Tune coin amount, max amount, and refresh window to limit faucet abuse. + +## Basic import + +```go +import "github.com/ignite/cli/v29/ignite/pkg/cosmosfaucet" +``` diff --git a/docs/docs/07-packages/cosmosgen.md b/docs/docs/07-packages/cosmosgen.md new file mode 100644 index 0000000000..2315833fb2 --- /dev/null +++ b/docs/docs/07-packages/cosmosgen.md @@ -0,0 +1,63 @@ +--- +sidebar_position: 15 +title: Code Generation (cosmosgen) +slug: /packages/cosmosgen +--- + +# Code Generation (cosmosgen) + +The `cosmosgen` package orchestrates multi-target code generation from protobuf sources, including Go code, TS clients, composables, and OpenAPI output. + +For full API details, see the +[`cosmosgen` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/cosmosgen). + +## When to use + +- Run full generation pipelines from application services. +- Configure selective outputs (Go only, TS only, OpenAPI only, etc.). +- Check tool availability and maintain buf-related configuration. + +## Key APIs + +- `Generate(ctx, cacheStorage, appPath, protoDir, goModPath, frontendPath, options...)` +- `WithGoGeneration()` +- `WithTSClientGeneration(out, tsClientRootPath, useCache)` +- `WithOpenAPIGeneration(out, excludeList)` +- `DepTools() []string` + +## Example + +```go +package main + +import ( + "context" + "log" + "os" + "path/filepath" + + "github.com/ignite/cli/v29/ignite/pkg/cache" + "github.com/ignite/cli/v29/ignite/pkg/cosmosgen" +) + +func main() { + storage, err := cache.NewStorage(filepath.Join(os.TempDir(), "ignite-cache.db")) + if err != nil { + log.Fatal(err) + } + + err = cosmosgen.Generate( + context.Background(), + storage, + ".", + "proto", + "github.com/acme/my-chain", + "./web", + cosmosgen.WithGoGeneration(), + cosmosgen.WithOpenAPIGeneration("./api/openapi.yml", nil), + ) + if err != nil { + log.Fatal(err) + } +} +``` diff --git a/docs/docs/07-packages/cosmosver.md b/docs/docs/07-packages/cosmosver.md new file mode 100644 index 0000000000..abb76098f2 --- /dev/null +++ b/docs/docs/07-packages/cosmosver.md @@ -0,0 +1,41 @@ +--- +sidebar_position: 11 +title: Cosmos SDK Versions (cosmosver) +slug: /packages/cosmosver +--- + +# Cosmos SDK Versions (cosmosver) + +The `cosmosver` package parses, compares, and detects Cosmos SDK versions used by a chain project. + +For full API details, see the +[`cosmosver` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/cosmosver). + +## When to use + +- Detect the Cosmos SDK version from a project before scaffolding or migrations. +- Compare versions to enable/disable version-specific features. +- Access Ignite's known SDK version set and latest supported baseline. + +## Key APIs + +- `Detect(appPath string) (version Version, err error)` +- `Parse(version string) (v Version, err error)` +- `var Versions = []Version{ ... }` +- `var Latest = Versions[len(Versions)-1]` +- `(Version) Is(version Version) bool` +- `(Version) LT(version Version) bool` +- `(Version) LTE(version Version) bool` +- `(Version) GTE(version Version) bool` + +## Common Tasks + +- Use `Detect` against a chain root to gate generation paths by SDK version. +- Parse user-provided versions with `Parse` before comparisons. +- Branch behavior with `LT`/`GTE` checks against well-known constants. + +## Basic import + +```go +import "github.com/ignite/cli/v29/ignite/pkg/cosmosver" +``` diff --git a/integration/plugin/testdata/example-plugin/go.mod b/integration/plugin/testdata/example-plugin/go.mod index 1979feb583..b00aff32ac 100644 --- a/integration/plugin/testdata/example-plugin/go.mod +++ b/integration/plugin/testdata/example-plugin/go.mod @@ -1,6 +1,6 @@ module example-plugin -go 1.24.1 +go 1.25.4 replace github.com/ignite/cli/v29 => ../../../../ @@ -12,26 +12,26 @@ require ( require ( dario.cat/mergo v1.0.1 // indirect github.com/Microsoft/go-winio v0.6.2 // indirect - github.com/ProtonMail/go-crypto v1.1.5 // indirect + github.com/ProtonMail/go-crypto v1.1.6 // indirect github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect github.com/aymerick/douceur v0.2.0 // indirect github.com/blang/semver/v4 v4.0.0 // indirect - github.com/charmbracelet/lipgloss v1.0.0 // indirect + github.com/charmbracelet/lipgloss v1.1.0 // indirect github.com/charmbracelet/x/ansi v0.8.0 // indirect - github.com/cloudflare/circl v1.3.7 // indirect - github.com/cockroachdb/errors v1.11.3 // indirect - github.com/cockroachdb/logtags v0.0.0-20230118201751-21c54148d20b // indirect + github.com/cloudflare/circl v1.6.3 // indirect + github.com/cockroachdb/errors v1.12.0 // indirect + github.com/cockroachdb/logtags v0.0.0-20241215232642-bb51bb14a506 // indirect github.com/cockroachdb/redact v1.1.6 // indirect github.com/cosmos/btcutil v1.0.5 // indirect - github.com/cosmos/cosmos-sdk v0.53.0 // indirect - github.com/cyphar/filepath-securejoin v0.3.6 // indirect + github.com/cosmos/cosmos-sdk v0.53.6 // indirect + github.com/cyphar/filepath-securejoin v0.4.1 // indirect github.com/emirpasic/gods v1.18.1 // indirect github.com/fatih/color v1.18.0 // indirect github.com/fatih/structs v1.1.0 // indirect - github.com/getsentry/sentry-go v0.31.1 // indirect + github.com/getsentry/sentry-go v0.35.0 // indirect github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 // indirect github.com/go-git/go-billy/v5 v5.6.2 // indirect - github.com/go-git/go-git/v5 v5.13.2 // indirect + github.com/go-git/go-git/v5 v5.16.5 // indirect github.com/gobuffalo/flect v0.3.0 // indirect github.com/gobuffalo/genny/v2 v2.1.0 // indirect github.com/gobuffalo/github_flavored_markdown v1.1.4 // indirect @@ -64,7 +64,7 @@ require ( github.com/microcosm-cc/bluemonday v1.0.23 // indirect github.com/mitchellh/mapstructure v1.5.0 // indirect github.com/muesli/reflow v0.3.0 // indirect - github.com/muesli/termenv v0.15.2 // indirect + github.com/muesli/termenv v0.16.0 // indirect github.com/oklog/run v1.1.0 // indirect github.com/otiai10/copy v1.14.1 // indirect github.com/otiai10/mint v1.6.3 // indirect @@ -74,23 +74,23 @@ require ( github.com/rogpeppe/go-internal v1.14.1 // indirect github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 // indirect github.com/sirupsen/logrus v1.9.3 // indirect - github.com/skeema/knownhosts v1.3.0 // indirect + github.com/skeema/knownhosts v1.3.1 // indirect github.com/sourcegraph/annotate v0.0.0-20160123013949-f4cad6c6324d // indirect github.com/sourcegraph/syntaxhighlight v0.0.0-20170531221838-bd320f5d308e // indirect - github.com/spf13/cobra v1.9.1 // indirect - github.com/spf13/pflag v1.0.6 // indirect + github.com/spf13/cobra v1.10.1 // indirect + github.com/spf13/pflag v1.0.10 // indirect github.com/xanzy/ssh-agent v0.3.3 // indirect go.etcd.io/bbolt v1.4.0 // indirect - golang.org/x/crypto v0.37.0 // indirect - golang.org/x/mod v0.24.0 // indirect - golang.org/x/net v0.39.0 // indirect - golang.org/x/sync v0.13.0 // indirect - golang.org/x/sys v0.32.0 // indirect - golang.org/x/term v0.31.0 // indirect - golang.org/x/text v0.24.0 // indirect - google.golang.org/genproto/googleapis/rpc v0.0.0-20250422160041-2d3770c4ea7f // indirect - google.golang.org/grpc v1.72.0 // indirect - google.golang.org/protobuf v1.36.6 // indirect + golang.org/x/crypto v0.45.0 // indirect + golang.org/x/mod v0.29.0 // indirect + golang.org/x/net v0.47.0 // indirect + golang.org/x/sync v0.18.0 // indirect + golang.org/x/sys v0.38.0 // indirect + golang.org/x/term v0.37.0 // indirect + golang.org/x/text v0.31.0 // indirect + google.golang.org/genproto/googleapis/rpc v0.0.0-20250818200422-3122310a409c // indirect + google.golang.org/grpc v1.75.0 // indirect + google.golang.org/protobuf v1.36.10 // indirect gopkg.in/warnings.v0 v0.1.2 // indirect gopkg.in/yaml.v3 v3.0.1 // indirect )