network

type BinarySource struct {
	// Type specifies the source type: "github", "local", "docker"
	Type string `json:"type"`

	// GitHub source configuration
	Owner     string `json:"owner,omitempty"`      // GitHub owner/org
	Repo      string `json:"repo,omitempty"`       // GitHub repository
	AssetName string `json:"asset_name,omitempty"` // Release asset name pattern

	// Local source configuration
	LocalPath string `json:"local_path,omitempty"` // Path to local binary

	// Build configuration
	BuildTags []string `json:"build_tags,omitempty"` // Go build tags (e.g., ["no_dynamic_precompiles"])
}

type BuildConfig struct {
	// Tags are Go build tags passed to the compiler.
	// These enable conditional compilation of code.
	// Examples: ["netgo", "ledger", "osusergo", "no_dynamic_precompiles"]
	Tags []string `json:"tags,omitempty"`

	// LDFlags are linker flags passed to the Go linker.
	// These are used to inject values at compile-time using -X flag.
	// Format: ["-X package.Variable=value", "-w", "-s"]
	// Examples:
	//   - "-X github.com/stablelabs/stable/app.EVMChainID=988" (set EVM chain ID)
	//   - "-w" (omit DWARF symbol table)
	//   - "-s" (omit symbol table and debug information)
	LDFlags []string `json:"ldflags,omitempty"`

	// Env contains environment variables for the build process.
	// These are set before running the build command.
	// Examples:
	//   - {"CGO_ENABLED": "0"} (disable CGO for static binary)
	//   - {"GOOS": "linux", "GOARCH": "amd64"} (cross-compilation)
	Env map[string]string `json:"env,omitempty"`

	// ExtraArgs are additional arguments passed to the build tool (goreleaser).
	// Examples: ["--skip-validate", "--debug", "--clean"]
	ExtraArgs []string `json:"extra_args,omitempty"`
}

type ExportOptions struct {
	// ForZeroHeight resets the chain height to 0 for the exported genesis.
	ForZeroHeight bool `json:"for_zero_height"`

	// JailWhitelist is a list of validator operator addresses that should
	// not be jailed in the exported genesis.
	JailWhitelist []string `json:"jail_whitelist,omitempty"`

	// ModulesToSkip is a list of module names to skip during export.
	ModulesToSkip []string `json:"modules_to_skip,omitempty"`

	// Height specifies a specific height to export from.
	// If 0, exports from the latest height.
	Height int64 `json:"height"`

	// OutputPath is the path to write the exported genesis.
	// If empty, genesis is written to stdout.
	OutputPath string `json:"output_path,omitempty"`
}

type FileBasedGenesisModifier interface {
	// ModifyGenesisFile modifies a genesis file at inputPath and writes to outputPath.
	// This is the file-based equivalent of Module.ModifyGenesis() for large genesis files.
	//
	// Parameters:
	//   - inputPath: Path to the input genesis.json file
	//   - outputPath: Path where the modified genesis should be written
	//   - opts: Genesis modification options (chain_id, validators, etc.)
	//
	// Returns:
	//   - outputSize: Size of the output file in bytes
	//   - error: Any error that occurred during modification
	ModifyGenesisFile(inputPath, outputPath string, opts GenesisOptions) (outputSize int64, err error)
}

type GeneratorConfig struct {
	NumValidators    int    `json:"num_validators"`
	NumAccounts      int    `json:"num_accounts"`
	AccountBalance   string `json:"account_balance"`   // JSON encoded coins
	ValidatorBalance string `json:"validator_balance"` // JSON encoded coins
	ValidatorStake   string `json:"validator_stake"`   // JSON encoded amount
	OutputDir        string `json:"output_dir"`
	ChainID          string `json:"chain_id"`
}

type GenesisConfig struct {
	// Chain identity
	ChainIDPattern string `json:"chain_id_pattern"` // e.g., "stable_{evmid}-1"
	EVMChainID     int64  `json:"evm_chain_id"`     // EVM chain ID

	// Token configuration
	BaseDenom     string `json:"base_denom"`     // e.g., "ustable"
	DenomExponent int    `json:"denom_exponent"` // Decimal places (typically 18)
	DisplayDenom  string `json:"display_denom"`  // Human-readable (e.g., "STABLE")

	// Staking parameters
	BondDenom         string        `json:"bond_denom"`
	MinSelfDelegation string        `json:"min_self_delegation"`
	UnbondingTime     time.Duration `json:"unbonding_time"`
	MaxValidators     uint32        `json:"max_validators"`

	// Governance parameters
	MinDeposit       string        `json:"min_deposit"`
	VotingPeriod     time.Duration `json:"voting_period"`
	MaxDepositPeriod time.Duration `json:"max_deposit_period"`

	// Distribution
	CommunityTax string `json:"community_tax"`
}

type GenesisOptions struct {
	ChainID       string          `json:"chain_id,omitempty"`
	NumValidators int             `json:"num_validators,omitempty"`
	Validators    []ValidatorInfo `json:"validators,omitempty"`
}

type Module interface {

	// Name returns the unique identifier for this network.
	// This should be lowercase, alphanumeric with hyphens only.
	// Examples: "stable", "ault", "osmosis", "cosmos-hub"
	Name() string

	// DisplayName returns a human-readable name for the network.
	// Examples: "Stable Network", "Osmosis DEX", "Cosmos Hub"
	DisplayName() string

	// Version returns the module version (semantic versioning recommended).
	// Example: "1.0.0"
	Version() string

	// BinaryName returns the name of the network's CLI binary.
	// Examples: "stabled", "osmosisd", "gaiad"
	BinaryName() string

	// BinarySource returns configuration for acquiring the binary.
	BinarySource() BinarySource

	// DefaultBinaryVersion returns the default version to build/use.
	// Examples: "v1.1.3", "latest", "main"
	DefaultBinaryVersion() string

	// GetBuildConfig returns network-specific build configuration for binary compilation.
	// This method enables plugins to customize build tags, linker flags, and environment
	// variables for different network types (mainnet, testnet, devnet).
	//
	// Parameters:
	//   - networkType: Target network type ("mainnet", "testnet", "devnet", etc.)
	//
	// Returns:
	//   - BuildConfig with custom build configuration
	//   - error if network type is not supported
	//
	// Example:
	//   cfg, err := module.GetBuildConfig("testnet")
	//   if err != nil {
	//       return err
	//   }
	//   // cfg.LDFlags might contain: ["-X github.com/example/app.EVMChainID=2201"]
	//
	// If the plugin doesn't need network-specific build configuration, it should
	// return an empty BuildConfig{} (not nil) to indicate no custom configuration.
	//
	// This is called during binary building to inject network-specific values
	// (like chain IDs) at compile-time. The returned config is merged with
	// default build configurations before being passed to the build tool.
	GetBuildConfig(networkType string) (*BuildConfig, error)

	// DefaultChainID returns the default chain ID for the devnet.
	//
	// Deprecated: Chain ID is extracted from genesis files and stored in metadata.
	// This method will be removed in v2.0.0. Return empty string for new plugins.
	// Examples: "stabledevnet_2200-1", "osmosis-devnet-1"
	DefaultChainID() string

	// Bech32Prefix returns the address prefix for this network.
	// Examples: "stable", "osmo", "cosmos"
	Bech32Prefix() string

	// BaseDenom returns the base token denomination.
	// Examples: "ustable", "uosmo", "uatom"
	BaseDenom() string

	// GenesisConfig returns default genesis parameters.
	GenesisConfig() GenesisConfig

	// DefaultPorts returns the default port configuration.
	DefaultPorts() PortConfig

	// DockerImage returns the Docker image name for this network.
	// Example: "ghcr.io/stablelabs/stable"
	DockerImage() string

	// DockerImageTag returns the Docker tag for a given version.
	// Allows networks to customize version-to-tag mapping.
	DockerImageTag(version string) string

	// DockerHomeDir returns the home directory inside Docker containers.
	// Example: "/home/stabled"
	DockerHomeDir() string

	// DefaultNodeHome returns the default node home directory path.
	// Example: "/root/.stabled"
	DefaultNodeHome() string

	// PIDFileName returns the process ID file name.
	// Example: "stabled.pid"
	PIDFileName() string

	// LogFileName returns the log file name.
	// Example: "stabled.log"
	LogFileName() string

	// ProcessPattern returns the regex pattern to match running processes.
	// Example: "stabled.*start"
	ProcessPattern() string

	// InitCommand returns arguments for initializing a node.
	// Parameters: homeDir, chainID, moniker
	// Returns: e.g., ["init", "node0", "--chain-id", "mychain-1", "--home", "/path"]
	InitCommand(homeDir, chainID, moniker string) []string

	// StartCommand returns arguments for starting a node.
	// Parameters: homeDir
	// Returns: e.g., ["start", "--home", "/path"]
	StartCommand(homeDir string) []string

	// ExportCommand returns arguments for exporting genesis/state.
	// Parameters: homeDir
	// Returns: e.g., ["export", "--home", "/path"]
	ExportCommand(homeDir string) []string

	// ModifyGenesis applies network-specific modifications to a genesis file.
	// Parameters:
	//   - genesis: Raw genesis JSON bytes
	//   - opts: User-provided customization options
	// Returns: Modified genesis JSON bytes, or error
	ModifyGenesis(genesis []byte, opts GenesisOptions) ([]byte, error)

	// GenerateDevnet generates validators, accounts, and modifies genesis.
	// This is the main entry point for devnet creation.
	GenerateDevnet(ctx context.Context, config GeneratorConfig, genesisFile string) error

	// DefaultGeneratorConfig returns the default configuration for devnet generation.
	DefaultGeneratorConfig() GeneratorConfig

	// GetCodec returns the network-specific codec configuration.
	// This is used for serialization/deserialization of chain-specific types.
	// Returns encoded codec configuration or error.
	GetCodec() ([]byte, error)

	// Validate checks if the module configuration is valid.
	// Called during registration and before use.
	Validate() error

	// SnapshotURL returns the snapshot download URL for the given network type.
	// Parameters:
	//   - networkType: Type of network ("mainnet", "testnet", etc.)
	// Returns: Full URL to the snapshot archive, or empty string if not available
	// Example: "https://stable-mainnet-data.s3.amazonaws.com/snapshots/stable_pruned.tar.zst"
	SnapshotURL(networkType string) string

	// RPCEndpoint returns the RPC endpoint for the given network type.
	// Parameters:
	//   - networkType: Type of network ("mainnet", "testnet", etc.)
	// Returns: Full URL to the RPC endpoint, or empty string if not available
	// Example: "https://cosmos-rpc.stable.xyz"
	RPCEndpoint(networkType string) string

	// AvailableNetworks returns a list of supported network types.
	// Returns: Slice of network type strings (e.g., ["mainnet", "testnet"])
	AvailableNetworks() []string

	// GetConfigOverrides returns TOML configuration overrides for a node.
	// The returned bytes are partial TOML that will be merged with the
	// default configs generated by node init.
	// Parameters:
	//   - nodeIndex: Index of the node (0, 1, 2, ...)
	//   - opts: Configuration options including ports and peers
	// Returns:
	//   - configToml: Partial config.toml overrides (can be nil if no overrides)
	//   - appToml: Partial app.toml overrides (can be nil if no overrides)
	//   - error: Error if generation fails
	GetConfigOverrides(nodeIndex int, opts NodeConfigOptions) (configToml []byte, appToml []byte, err error)
}

type NodeConfigOptions struct {
	// ChainID is the chain identifier
	ChainID string `json:"chain_id"`

	// Ports is the port configuration for this node
	Ports PortConfig `json:"ports"`

	// PersistentPeers is the persistent peers string (node_id@host:port,...)
	PersistentPeers string `json:"persistent_peers"`

	// NumValidators is the total number of validators
	NumValidators int `json:"num_validators"`

	// IsValidator indicates if this node is a validator
	IsValidator bool `json:"is_validator"`

	// Moniker is the node's moniker/name
	Moniker string `json:"moniker"`
}

type PortConfig struct {
	RPC       int `json:"rpc"`        // Tendermint RPC (default: 26657)
	P2P       int `json:"p2p"`        // P2P networking (default: 26656)
	GRPC      int `json:"grpc"`       // gRPC server (default: 9090)
	GRPCWeb   int `json:"grpc_web"`   // gRPC-Web (default: 9091)
	API       int `json:"api"`        // REST API (default: 1317)
	EVMRPC    int `json:"evm_rpc"`    // EVM JSON-RPC (default: 8545)
	EVMSocket int `json:"evm_socket"` // EVM WebSocket (default: 8546)
}

type SnapshotFormat string

type SnapshotInfo struct {
	// URL is the download URL for the snapshot archive.
	URL string `json:"url"`

	// Format is the archive format.
	Format SnapshotFormat `json:"format"`

	// Height is the block height of the snapshot.
	Height int64 `json:"height"`

	// Hash is the hash of the snapshot archive for verification.
	Hash string `json:"hash,omitempty"`

	// Size is the size of the snapshot in bytes.
	Size int64 `json:"size"`
}

type StateExporter interface {
	// ExportCommandWithOptions returns arguments for exporting genesis/state
	// with the given export options.
	// Parameters: homeDir, opts
	// Returns: e.g., ["export", "--home", "/path", "--for-zero-height"]
	ExportCommandWithOptions(homeDir string, opts ExportOptions) []string

	// ValidateExportedGenesis validates the exported genesis for this network.
	// This performs network-specific validation (e.g., checking for EVM modules).
	ValidateExportedGenesis(genesis []byte) error

	// RequiredModules returns the list of modules that must be present
	// in an exported genesis for it to be valid.
	RequiredModules() []string

	// SnapshotFormat returns the expected snapshot archive format for this network.
	// Parameters: networkType ("mainnet", "testnet")
	// Returns: SnapshotFormat (e.g., SnapshotFormatTarLz4)
	SnapshotFormat(networkType string) SnapshotFormat
}

type ValidatorInfo struct {
	Moniker         string `json:"moniker"`
	ConsPubKey      string `json:"cons_pub_key"`     // Base64 encoded Ed25519 pubkey
	OperatorAddress string `json:"operator_address"` // Bech32 valoper address
	SelfDelegation  string `json:"self_delegation"`  // Amount of tokens delegated
}