crosschain

type AdditionalNativeAsset struct {
	// The asset ID of the asset to use
	AssetId string `yaml:"asset_id,omitempty"`
	// The native asset that this bridged asset corresponds to or settles in (e.g., "chains/ETH/assets/ETH" for OptEth or Eclipse)
	BridgedAsset string `yaml:"bridged_asset,omitempty"`
	// The on-chain contract ID of the asset
	ContractId ContractAddress `yaml:"contract_id,omitempty"`
	// Decimals for the asset
	Decimals int32 `yaml:"decimals,omitempty"`
	// Maximum fee limit
	FeeLimit AmountHumanReadable `yaml:"fee_limit"`
	Aliases  []string            `yaml:"aliases,omitempty"`
}

type Address string

type AddressBuilder interface {
	GetAddressFromPublicKey(publicKeyBytes []byte) (Address, error)
}

type AddressBuilderWithFormats interface {
	// Returns the signature algorithm to be used for a given address format
	GetSignatureAlgorithm() SignatureType
}

type AddressConfig struct {
	// All formats supported by chain, including default
	Formats []AddressFormat `yaml:"formats,omitempty"`
}

type AddressFormat string

type AmountBlockchain big.Int

type AmountHumanReadable decimal.Decimal

type CallTxInput interface {
	TxVariantInput
	Calling()
}

type ChainBaseConfig struct {
	// The crosschain symbol of the chain
	Chain NativeAsset `yaml:"chain,omitempty"`
	// The driver to use for the chain
	Driver Driver `yaml:"driver,omitempty"`
	// The network selector, if necessary (e.g. select mainnet, testnet, or devnet for bitcoin chains)
	Network string `yaml:"net,omitempty"`
	// Decimals for the chain's native asset (if it has one).
	Decimals int32 `yaml:"decimals,omitempty"`

	// The ChainID of the chain, either in integer or string format
	ChainID StringOrInt `yaml:"chain_id,omitempty"`

	// Human readable name of the chain, e.g. "Bitcoin"
	ChainName string `yaml:"chain_name,omitempty"`

	// Does the chain use a special prefix for it's address?
	// E.g. most cosmos chains do this.
	ChainPrefix StringOrInt `yaml:"chain_prefix,omitempty"`

	// If the chain has a native asset, and it has an actual contract address, it should be set here.
	// This is also referred to as the "ContractID".
	// E.g.
	// - APTOS has 0x1::aptos_coin::AptosCoin
	// - INJ has inj
	// - HASH has nhash
	// - LUNA has uluna
	ChainCoin string `yaml:"chain_coin,omitempty"`
	// Additional native assets that may be used to pay fees on the chain.
	NativeAssets []*AdditionalNativeAsset `yaml:"native_assets,omitempty"`
	// If true, then the `.Chain` does not represent any native asset (i.e. no chain-coin, no decimals).
	NoNativeAsset bool `yaml:"no_native_asset,omitempty"`

	// If necessary, specific which asset to use to spend for gas.
	GasCoin string `yaml:"gas_coin,omitempty"`

	// Indicate if this chain should not be included.
	Disabled *bool `yaml:"disabled,omitempty"`

	// Staking configuration
	Staking StakingConfig `yaml:"staking,omitempty"`

	// Maximum total fee limit: required for caller to make use of with `TxInput.GetFeeLimit()`
	FeeLimit AmountHumanReadable `yaml:"fee_limit,omitempty"`

	// Transfer tax is percentage that the network takes from every transfer .. only used so far for Terra Classic
	ChainTransferTax float64 `yaml:"chain_transfer_tax,omitempty"`

	// Used only for deriving private keys from mnemonic phrases in local testing
	ChainCoinHDPath uint32 `yaml:"chain_coin_hd_path,omitempty"`

	// Should use `ChainID` instead
	XChainIDStr string `yaml:"chain_id_str,omitempty"`

	// Optional address configuration
	Address AddressConfig `yaml:"address,omitempty"`
}

type ChainClientConfig struct {
	URL          string `yaml:"url,omitempty"`
	SecondaryURL string `yaml:"secondary_url,omitempty"`

	// Set a secret reference, see config/secret.go.  Used for setting an API keys.
	Auth2 config.Secret `yaml:"auth,omitempty"`

	// Optional configuration of the Driver.  Some chains support different kinds of RPC.
	Provider         string                 `yaml:"provider,omitempty"`
	CrosschainClient CrosschainClientConfig `yaml:"crosschain_client"`

	// Does the chain rely on an indexer in addition to RPC?  If so, the URL and type
	// may be set here.
	IndexerUrl  string `yaml:"indexer_url,omitempty"`
	IndexerType string `yaml:"indexer_type,omitempty"`
	// Maximun depth to scan for transaction, if there is no index to use (substrate...)
	MaxScanDepth int `yaml:"max_scan_depth,omitempty"`

	NoGasFees bool `yaml:"no_gas_fees,omitempty"`

	// Default gas budget to use for client gas estimation
	GasBudgetDefault AmountHumanReadable `yaml:"gas_budget_default,omitempty"`
	// Gas budget that cannot be exceeded below
	GasBudgetMinimum AmountHumanReadable `yaml:"gas_budget_min,omitempty"`
	// A remainder balance (e.g. rent threshold) that must be maintained after a transfer.
	ReserveAmount AmountHumanReadable `yaml:"reserve_amount,omitempty"`
	// A default for clients to gas price if there's not better way to estimate.
	ChainGasPriceDefault float64 `yaml:"chain_gas_price_default,omitempty"`
	// A local multiplier for client to apply to gas estimation, if it's important/needed.
	ChainGasMultiplier          float64 `yaml:"chain_gas_multiplier,omitempty"`
	SecondaryChainGasMultiplier float64 `yaml:"secondary_chain_gas_multiplier,omitempty"`
	// for gas estimation of gas limit, for somechains the simulation may be flaky and need a multiplier
	ChainGasLimitMultiplier float64 `yaml:"chain_gas_limit_multiplier,omitempty"`
	// The multiplier to apply to gas when there is a minimum replacement increase.
	// This is used for EVM chains, to avoid the "replacement transaction underpriced" message.
	// Normally it is 10%, but on chains like Base and Optimism, it seems to be at least 25% in practice.
	ReplacementTransactionMultiplier float64 `yaml:"replacement_transaction_multiplier,omitempty"`
	// The max/min prices can be set to provide sanity limits for what a gas price (per gas or per byte) should be.
	// This should be in the blockchain amount.
	ChainMaxGasPrice float64 `yaml:"chain_max_gas_price,omitempty"`
	ChainMinGasPrice float64 `yaml:"chain_min_gas_price,omitempty"`
	// Default gas limit for transactions
	GasLimitDefault int `yaml:"gas_limit_default,omitempty"`
	// TransactionActiveTime specifies the duration for which a transaction remains valid after being submitted.
	// The value is represented as a `time.Duration` string.
	// This field is currently used only by the Stellar network.
	//
	// Example format: "30s" (30 seconds), "2m" (2 minutes), "1h" (1 hour).
	TransactionActiveTime time.Duration `yaml:"transaction_active_time,omitempty"`
	// How many confirmations is considered "final" for this chain?
	XConfirmationsFinal int                 `yaml:"confirmations_final,omitempty"`
	Confirmations       ConfirmationsConfig `yaml:"confirmations,omitempty"`

	// Gas price oracle address
	// Currently this is used for EVM L2 chains that have an additional "l1" fee.
	GasPriceOracleAddress string `yaml:"gas_price_oracle_address,omitempty"`

	// Rate limit setting on RPC requests for client, in requests/second.
	RateLimit rate.Limit `yaml:"rate_limit,omitempty"`
	// Period between requests (alternative to `rate_limit`)
	PeriodLimit time.Duration `yaml:"period_limit,omitempty"`
	// Number of requests to permit in burst
	Burst int `yaml:"burst,omitempty"`

	// Rate limiter configured from `rate_limit`, `period_limit`, `burst` (requires calling .Configure after loading from config)
	Limiter *rate.Limiter `yaml:"-" mapstructure:"-"`
	// HTTP timeout for the client (will default to global factory configuration)
	HttpTimeout time.Duration `yaml:"http_timeout,omitempty"`

	// Additional metadata.  Not Used in crosschain itself, but helpful to enrich API endpoints.
	External External `yaml:"external,omitempty"`
	// Informational URLs for the chain explorers.
	ExplorerUrls ExplorerUrls `yaml:"explorer_urls,omitempty"`
	// If true, this means that the chain is not intended for future use and
	// is only maintained for legacy purposes (by the upstream community).
	// E.g. "Terra Classic" or "Fantom" are legacy chains that each have replacements.
	Legacy bool `yaml:"legacy,omitempty"`
	// Indicate to the driver if additional information should be included for older crosschain clients.
	IncludeLegacyInformation bool `yaml:"include_legacy_information,omitempty"`
	// If true, the client will only use confirmed UTXOs for unspent output queries.
	ConfirmedUtxo bool `yaml:"confirmed_utxo,omitempty"`
}

type ChainConfig struct {
	*ChainBaseConfig   `yaml:",inline"`
	*ChainClientConfig `yaml:",inline"`
}

type ClientConfig struct {
	Driver   Driver          `yaml:"driver"`
	URL      string          `yaml:"url,omitempty"`
	Auth     string          `yaml:"auth,omitempty"`
	Provider string          `yaml:"provider,omitempty"`
	Network  NetworkSelector `yaml:"network,omitempty"`
}

type ConfirmationsConfig struct {
	Final   int `yaml:"final,omitempty"`
	Tracked int `yaml:"tracked,omitempty"`
}

type ContractAddress Address

type CrosschainClientConfig struct {
	Url     string          `yaml:"url"`
	Network NetworkSelector `yaml:"network,omitempty"`
}

type Driver string

type ExplorerUrls struct {
	Tx      string `yaml:"tx"`
	Address string `yaml:"address"`
	Token   string `yaml:"token"`
}

type External struct {
	Dti string `yaml:"dti,omitempty"`

	CoinMarketCap struct {
		// CoinMarketCap's ID for the chain
		ChainId string `yaml:"chain_id,omitempty"`
		// CoinMarketCap's ID for the chain's native asset, also called "UCID"
		AssetId string `yaml:"asset_id,omitempty"`
	} `yaml:"coin_market_cap,omitempty"`
	CoinGecko struct {
		// TODO: is there a chain ID for coingecko?
		ChainId string `yaml:"chain_id,omitempty"`
		// Coingecko's asset ID, if relevant
		AssetId string `yaml:"asset_id,omitempty"`
	} `yaml:"coin_gecko,omitempty"`
	IndexingCo struct {
		ChainId  string `yaml:"chain_id,omitempty"`
		Disabled bool   `yaml:"disabled,omitempty"`
	} `yaml:"indexing_co,omitempty"`
}

type GasFeePriority string

type ITask interface {
	GetChain() *ChainConfig
	GetDecimals() int32

	// Informational / debugging
	String() string
}

type MultiTransferInput interface {
	TxVariantInput
	MultiTransfer()
}

type NativeAsset string

type NetworkSelector string

type PublicKeyFormat string

type SignatureRequest struct {
	// Required: The payload to sign
	Payload []byte
	// May be optionally set, if different from the from-address.
	Signer Address
}

type SignatureResponse struct {
	// Signaure of the payload
	Signature TxSignature
	// Address + public key of the signer
	PublicKey []byte
	Address   Address
}

type SignatureType string

type StakeTxInput interface {
	TxVariantInput
	Staking()
}

type StakingConfig struct {
	// the contract used for staking, if relevant
	StakeContract string `yaml:"stake_contract,omitempty"`
	// the contract used for unstaking, if relevant
	UnstakeContract string `yaml:"unstake_contract,omitempty"`
	// Compatible providers for staking
	Providers []StakingProvider `yaml:"providers,omitempty"`
}

type StakingProvider string

type StringOrInt string

type Tx interface {
	Hash() TxHash
	Sighashes() ([]*SignatureRequest, error)
	SetSignatures(...*SignatureResponse) error
	Serialize() ([]byte, error)
}

type TxAdditionalSighashes interface {
	// This is available in case a transaction needs to make signatures-over-signatures.
	// This should return any _remaining_ signatures requests left to fill.
	// The caller will always call .SetSignatures() after this with all of the signature made so far.
	AdditionalSighashes() ([]*SignatureRequest, error)
}

type TxCall interface {
	Tx
	// Set transaction input.  This may not be needed, but could be used to adjust:
	// * fees
	// * other dynamic chain information not included in the origin Call message
	SetInput(input CallTxInput) error

	// List of addresses that may be needed to sign
	SigningAddresses() []Address

	// List of 3rd party contract addresses that this Call resource interacts with
	// (omit native system contracts)
	ContractAddresses() []ContractAddress

	// Get original serialized message that Call was constructed with
	GetMsg() json.RawMessage
}

type TxHash string

type TxInput interface {
	GetDriver() Driver
	TxInputConflicts
	TxInputGasFeeMultiplier
	TxInputGetMaxPossibleFee
}

type TxInputConflicts interface {
	// Test independence of two tx-inputs, assuming the same address is used.
	// Examples:
	// - using the same nonce or sequence is NOT independent
	// - spending the same resources or utxo's is NOT independent
	// - solana (using recent_block_hash) is pretty much always independent
	// This is used to determine if a transaction needs to be queued or if it can be immediately signed & broadcasted.
	IndependentOf(other TxInput) (independent bool)

	// Test if tx-input could possibly result in a "double-send" given the history of past attempts.
	// A double send is a user re-signing their transaction (to overcome a timeout or use new fees), but then risk multiple transactions
	// landing on chain.  A valid re-sign should only occur if it's only possible for one transaction to land out of the total set of attempts.
	// Examples:
	// - Solana typically has no conflicts, but need to ensure (a) new blockhash is used, and (b) sufficient time has passed
	//   to be sure a double send won't occur (return `true`).
	// - If tx-inputs are not independent (spending same resources), then typically double-sends are impossible (and should return `true` here).
	// - If there exists tx-inputs that are fully independent (and not timed out), then a double-send is possible and this should return false.
	SafeFromDoubleSend(previousAttempts TxInput) (safe bool)
}

type TxInputEnvelope struct {
	Type Driver `json:"type"`
}

type TxInputGasFeeMultiplier interface {
	SetGasFeePriority(priority GasFeePriority) error
}

type TxInputGetMaxPossibleFee interface {
	// Get the maximum possible fee that could occur for this transaction.
	// This is used to guard against "griefing" attacks where a user is charged way more than they intended.
	// The contract address may be "" when the fee is for the native asset, as is often the case..
	//
	// Note: The caller/user should check this after TxInput has been populated with all other fields, as they can influence
	// what the ultimate max fee is.
	GetFeeLimit() (AmountBlockchain, ContractAddress)
}

type TxInputWithUnix interface {
	SetUnix(int64)
}

type TxLegacyGetSignatures interface {
	// Replaced by TxWithMetadata.GetMetadata()
	GetSignatures() []TxSignature
}

type TxSignature []byte

type TxStatus uint8

type TxVariantInput interface {
	TxInput
	GetVariant() TxVariantInputType
}

type TxVariantInputType string

type TxWithMetadata interface {
	// If the client SubmitTx needs additional metadata, this can be used to define it.
	GetMetadata() ([]byte, bool, error)
}

type UnstakeTxInput interface {
	TxVariantInput
	Unstaking()
}

type WithdrawTxInput interface {
	TxVariantInput
	Withdrawing()
}