Skip to content

Commit b1c36de

Browse files
PantaniPantani
authored
chore: add cosmos packages docs (#4888)
* add cosmos client docs * add chain cmd runner pkg docs * add chain registry pkg docs * add cosmos faucet pkg docs * add cosmos account pkg docs * add missing packages * missing simples pkgs * organize docs by type * rollback versioned docs * update generic docs * add more description * remove unused docs * improve docs titles * remoce unecessary docs * rollback cosmostxcollector
1 parent 1ce7b8e commit b1c36de

12 files changed

Lines changed: 487 additions & 25 deletions

File tree

‎docs/docs/02-guide/08-state.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ In blockchain applications, state refers to the current data stored on the block
99

1010
## Collections Package
1111

12-
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.
12+
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.
1313

1414
### Key Features of Collections
1515

‎docs/docs/07-packages/chaincmd.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
sidebar_position: 7
3+
title: Chain Command Builder (chaincmd)
4+
slug: /packages/chaincmd
5+
---
6+
7+
# Chain Command Builder (chaincmd)
8+
9+
The `chaincmd` package builds `step.Option` command definitions for Cosmos SDK daemon binaries (`simd`, `gaiad`, and others). It does not execute commands directly.
10+
11+
For full API details, see the
12+
[`chaincmd` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/chaincmd).
13+
14+
## When to use
15+
16+
- Build consistent daemon command lines from typed options.
17+
- Reuse command composition across services and tests.
18+
- Keep chain binary-specific flags centralized.
19+
20+
## Key APIs
21+
22+
- `New(appCmd string, options ...Option) ChainCmd`
23+
- `WithHome(home string) Option`
24+
- `WithChainID(chainID string) Option`
25+
- `InitCommand(moniker string, options ...string) step.Option`
26+
- `BankSendCommand(fromAddress, toAddress, amount string, options ...BankSendOption) step.Option`
27+
28+
## Example
29+
30+
```go
31+
package main
32+
33+
import (
34+
"fmt"
35+
36+
"github.com/ignite/cli/v29/ignite/pkg/chaincmd"
37+
"github.com/ignite/cli/v29/ignite/pkg/cmdrunner/step"
38+
)
39+
40+
func main() {
41+
cmd := chaincmd.New(
42+
"simd",
43+
chaincmd.WithHome("./.simapp"),
44+
chaincmd.WithChainID("demo-1"),
45+
)
46+
47+
initStep := step.New(cmd.InitCommand("validator"))
48+
fmt.Println(initStep.Exec.Command)
49+
fmt.Println(initStep.Exec.Args)
50+
}
51+
```

‎docs/docs/07-packages/chaincmdrunner.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
sidebar_position: 4
3+
title: Chain Command Runner (chaincmd/runner)
4+
slug: /packages/chaincmdrunner
5+
---
6+
7+
# Chain Command Runner (chaincmd/runner)
8+
9+
The `chaincmdrunner` package wraps chain binary commands into typed, higher-level operations (accounts, genesis setup, tx queries, node control).
10+
11+
For full API details, see the
12+
[`chaincmdrunner` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/chaincmd/runner).
13+
14+
## When to use
15+
16+
- Execute chain lifecycle commands without manually assembling CLI arguments.
17+
- Manage accounts and genesis setup from automation/test flows.
18+
- Query transaction events using typed selectors instead of raw command output parsing.
19+
20+
## Key APIs
21+
22+
- `New(ctx context.Context, chainCmd chaincmd.ChainCmd, options ...Option) (Runner, error)`
23+
- `(Runner) Init(ctx context.Context, moniker string, args ...string) error`
24+
- `(Runner) Start(ctx context.Context, args ...string) error`
25+
- `(Runner) AddAccount(ctx context.Context, name, mnemonic, coinType, accountNumber, addressIndex string) (Account, error)`
26+
- `(Runner) AddGenesisAccount(ctx context.Context, address, coins string) error`
27+
- `(Runner) QueryTxByEvents(ctx context.Context, selectors ...EventSelector) ([]Event, error)`
28+
- `(Runner) WaitTx(ctx context.Context, txHash string, retryDelay time.Duration, maxRetry int) error`
29+
30+
## Common Tasks
31+
32+
- Build a `Runner` from a configured `chaincmd.ChainCmd` and then call `Init`/`Start` for local node workflows.
33+
- Use `AddAccount`, `ListAccounts`, and `ShowAccount` to manage keyring state in scripted flows.
34+
- Query and filter tx events with `NewEventSelector` plus `QueryTxByEvents`.
35+
36+
## Basic import
37+
38+
```go
39+
import chaincmdrunner "github.com/ignite/cli/v29/ignite/pkg/chaincmd/runner"
40+
```

‎docs/docs/07-packages/chainregistry.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
sidebar_position: 3
3+
title: Chain Registry Types (chainregistry)
4+
slug: /packages/chainregistry
5+
---
6+
7+
# Chain Registry Types (chainregistry)
8+
9+
The `chainregistry` package defines strongly-typed Go structs for Cosmos chain-registry data (`chain.json` and `assetlist.json`).
10+
11+
For full API details, see the
12+
[`chainregistry` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/chainregistry).
13+
14+
## When to use
15+
16+
- Parse chain-registry JSON into typed values.
17+
- Build tooling that reads chain metadata (APIs, fees, staking tokens, assets).
18+
- Validate or transform registry documents before writing them back.
19+
20+
## Key APIs
21+
22+
- `type Chain struct{ ... }`
23+
- `type APIs struct{ ... }`
24+
- `type APIProvider struct{ ... }`
25+
- `type AssetList struct{ ... }`
26+
- `type Asset struct{ ... }`
27+
- `type Fees struct{ ... }`
28+
- `type Staking struct{ ... }`
29+
- `type Codebase struct{ ... }`
30+
- `type ChainStatus string`
31+
- `type ChainType string`
32+
33+
## Common Tasks
34+
35+
- Decode `chain.json` data into a `Chain` value and inspect RPC/REST metadata.
36+
- Decode `assetlist.json` into `AssetList` to access denom units and logo URIs.
37+
- Use enum-like types (`ChainStatus`, `NetworkType`, `ChainType`) to keep metadata checks explicit.
38+
39+
## Basic import
40+
41+
```go
42+
import "github.com/ignite/cli/v29/ignite/pkg/chainregistry"
43+
```

‎docs/docs/07-packages/cosmosaccount.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
sidebar_position: 2
3+
title: Account Registry (cosmosaccount)
4+
slug: /packages/cosmosaccount
5+
---
6+
7+
# Account Registry (cosmosaccount)
8+
9+
The `cosmosaccount` package manages Cosmos keyring accounts (create/import/export/list/delete) with configurable backend and Bech32 settings.
10+
11+
For full API details, see the
12+
[`cosmosaccount` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/cosmosaccount).
13+
14+
## When to use
15+
16+
- Manage CLI account keys in Ignite services and commands.
17+
- Switch between `test`, `os`, and `memory` keyring backends.
18+
- Resolve addresses/public keys from named keyring entries.
19+
20+
## Key APIs
21+
22+
- `New(options ...Option) (Registry, error)`
23+
- `NewInMemory(options ...Option) (Registry, error)`
24+
- `WithKeyringBackend(backend KeyringBackend) Option`
25+
- `WithHome(path string) Option`
26+
- `(Registry) Create(name string) (Account, mnemonic string, err error)`
27+
- `(Registry) Import(name, secret, passphrase string) (Account, error)`
28+
- `(Registry) Export(name, passphrase string) (key string, err error)`
29+
- `(Registry) GetByName(name string) (Account, error)`
30+
- `(Registry) List() ([]Account, error)`
31+
- `(Account) Address(accPrefix string) (string, error)`
32+
33+
## Common Tasks
34+
35+
- Instantiate one `Registry` with backend/home options and reuse it for all key operations.
36+
- Call `EnsureDefaultAccount` in setup paths that require a predictable signer account.
37+
- Resolve addresses with `Account.Address(prefix)` when your app uses non-default Bech32 prefixes.
38+
39+
## Basic import
40+
41+
```go
42+
import "github.com/ignite/cli/v29/ignite/pkg/cosmosaccount"
43+
```

‎docs/docs/07-packages/cosmosanalysis.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
sidebar_position: 13
3+
title: Cosmos Source Analysis (cosmosanalysis)
4+
slug: /packages/cosmosanalysis
5+
---
6+
7+
# Cosmos Source Analysis (cosmosanalysis)
8+
9+
The `cosmosanalysis` package provides static analysis helpers for Cosmos SDK-based projects, especially for app structure and interface/embed discovery.
10+
11+
For full API details, see the
12+
[`cosmosanalysis` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/cosmosanalysis).
13+
14+
## When to use
15+
16+
- Validate that a directory is a Cosmos chain project before running codegen.
17+
- Locate key app files and embedded types in Cosmos app sources.
18+
- Detect interface implementations across module files.
19+
20+
## Key APIs
21+
22+
- `IsChainPath(path string) error`
23+
- `FindAppFilePath(chainRoot string) (path string, err error)`
24+
- `ValidateGoMod(module *modfile.File) error`
25+
- `FindImplementation(modulePath string, interfaceList []string) (found []string, err error)`
26+
- `DeepFindImplementation(modulePath string, interfaceList []string) (found []string, err error)`
27+
- `FindEmbed(modulePath string, targetEmbeddedTypes []string) (found []string, err error)`
28+
- `FindEmbedInFile(n ast.Node, targetEmbeddedTypes []string) (found []string)`
29+
30+
## Common Tasks
31+
32+
- Call `IsChainPath` early to fail fast on unsupported project layouts.
33+
- Use `FindAppFilePath` before AST transformations that require the chain app entrypoint.
34+
- Use `FindImplementation`/`DeepFindImplementation` to verify generated modules are wired as expected.
35+
36+
## Basic import
37+
38+
```go
39+
import "github.com/ignite/cli/v29/ignite/pkg/cosmosanalysis"
40+
```

‎docs/docs/07-packages/cosmosbuf.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
sidebar_position: 14
3+
title: Buf Integration (cosmosbuf)
4+
slug: /packages/cosmosbuf
5+
---
6+
7+
# Buf Integration (cosmosbuf)
8+
9+
The `cosmosbuf` package wraps Buf workflows (`generate`, `export`, `format`, `migrate`, `dep update`) used by Ignite's protobuf pipelines.
10+
11+
For full API details, see the
12+
[`cosmosbuf` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/cosmosbuf).
13+
14+
## When to use
15+
16+
- Trigger Buf code generation from Go services.
17+
- Keep Buf invocation flags and error handling consistent.
18+
- Reuse cache-aware generation behavior.
19+
20+
## Key APIs
21+
22+
- `New(cacheStorage cache.Storage, goModPath string) (Buf, error)`
23+
- `(Buf) Generate(ctx, protoPath, output, template, options...)`
24+
- `(Buf) Format(ctx, path)`
25+
- `(Buf) Export(ctx, protoDir, output)`
26+
- `Version(ctx context.Context) (string, error)`
27+
28+
## Example
29+
30+
```go
31+
package main
32+
33+
import (
34+
"context"
35+
"log"
36+
"os"
37+
"path/filepath"
38+
39+
"github.com/ignite/cli/v29/ignite/pkg/cache"
40+
"github.com/ignite/cli/v29/ignite/pkg/cosmosbuf"
41+
)
42+
43+
func main() {
44+
storage, err := cache.NewStorage(filepath.Join(os.TempDir(), "ignite-cache.db"))
45+
if err != nil {
46+
log.Fatal(err)
47+
}
48+
49+
buf, err := cosmosbuf.New(storage, "github.com/acme/my-chain")
50+
if err != nil {
51+
log.Fatal(err)
52+
}
53+
54+
if err := buf.Format(context.Background(), "./proto"); err != nil {
55+
log.Fatal(err)
56+
}
57+
}
58+
```

‎docs/docs/07-packages/cosmosclient.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
sidebar_position: 1
3+
title: Blockchain Client (cosmosclient)
4+
slug: /packages/cosmosclient
5+
---
6+
7+
# Blockchain Client (cosmosclient)
8+
9+
The `cosmosclient` package provides a high-level client for querying Cosmos SDK chains and building/signing/broadcasting transactions.
10+
11+
For full API details, see the
12+
[`cosmosclient` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/cosmosclient).
13+
14+
## When to use
15+
16+
- Connect Ignite tooling to a running node for status and block queries.
17+
- Build and broadcast SDK messages with shared gas/fees/keyring settings.
18+
- Wait for transaction inclusion and inspect block transactions/events.
19+
20+
## Key APIs
21+
22+
- `New(ctx context.Context, options ...Option) (Client, error)`
23+
- `WithNodeAddress(addr string) Option`
24+
- `WithHome(path string) Option`
25+
- `WithKeyringBackend(backend cosmosaccount.KeyringBackend) Option`
26+
- `WithGas(gas string) Option`
27+
- `WithGasPrices(gasPrices string) Option`
28+
- `(Client) BroadcastTx(ctx, account, msgs...) (Response, error)`
29+
- `(Client) WaitForTx(ctx context.Context, hash string) (*ctypes.ResultTx, error)`
30+
- `(Client) Status(ctx context.Context) (*ctypes.ResultStatus, error)`
31+
- `(Client) LatestBlockHeight(ctx context.Context) (int64, error)`
32+
33+
## Common Tasks
34+
35+
- Initialize one `Client` instance with node and keyring options, then reuse it across operations.
36+
- Call `CreateTxWithOptions` or `BroadcastTx` depending on whether you need fine-grained tx overrides.
37+
- Use `WaitForTx`, `WaitForNextBlock`, or `WaitForBlockHeight` for deterministic flows in tests/automation.
38+
39+
## Basic import
40+
41+
```go
42+
import "github.com/ignite/cli/v29/ignite/pkg/cosmosclient"
43+
```

‎docs/docs/07-packages/cosmosfaucet.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
sidebar_position: 5
3+
title: Token Faucet (cosmosfaucet)
4+
slug: /packages/cosmosfaucet
5+
---
6+
7+
# Token Faucet (cosmosfaucet)
8+
9+
The `cosmosfaucet` package provides a local faucet service and client helpers to fund Cosmos accounts during development and tests.
10+
11+
For full API details, see the
12+
[`cosmosfaucet` Go package documentation](https://pkg.go.dev/github.com/ignite/cli/v29/ignite/pkg/cosmosfaucet).
13+
14+
## When to use
15+
16+
- Automatically fund accounts in local/devnet environments.
17+
- Expose a faucet HTTP endpoint backed by a chain key.
18+
- Request funds from an existing faucet endpoint from automation code.
19+
20+
## Key APIs
21+
22+
- `New(ctx context.Context, ccr chaincmdrunner.Runner, options ...Option) (Faucet, error)`
23+
- `TryRetrieve(ctx context.Context, chainID, rpcAddress, faucetAddress, accountAddress string) (string, error)`
24+
- `OpenAPI(apiAddress string) Option`
25+
- `Coin(amount, maxAmount sdkmath.Int, denom string) Option`
26+
- `FeeAmount(amount sdkmath.Int, denom string) Option`
27+
- `RefreshWindow(refreshWindow time.Duration) Option`
28+
- `NewTransferRequest(accountAddress string, coins []string) TransferRequest`
29+
30+
## Common Tasks
31+
32+
- Construct a `Faucet` with chain runner + options, then expose transfer endpoints for local users.
33+
- Use `TryRetrieve` in tests before broadcasting txs to ensure accounts have spendable balance.
34+
- Tune coin amount, max amount, and refresh window to limit faucet abuse.
35+
36+
## Basic import
37+
38+
```go
39+
import "github.com/ignite/cli/v29/ignite/pkg/cosmosfaucet"
40+
```

0 commit comments

Comments
 (0)