engine

type Checkpointer ¶ added in v0.0.61

type Checkpointer interface {
	SaveTxMarker(m *TxMarker) error
	// GetTxMarker returns (nil, nil) when no marker exists for taskID.
	GetTxMarker(taskID string) (*TxMarker, error)
}

Checkpointer persists a TxMarker durably before broadcast and retrieves it on re-execution, so a crash between broadcast and result-persist re-adopts the in-flight tx instead of signing a second one. Nil when no durable store is configured (handlers then broadcast without the guard, and log it).

type Engine ¶

type Engine struct {

	// Config is set once during single-threaded startup before Submit
	// is reachable; read-only thereafter. No synchronization.
	Config ExecutionConfig
	// contains filtered or unexported fields
}

Engine is the task executor. Every submitted task runs in its own goroutine. The store is the single source of truth for all task state. The engine context propagates to all handlers — on SIGTERM the context is cancelled and handlers observe ctx.Done() to stop gracefully.

func NewEngine(ctx context.Context, handlers map[TaskType]TaskHandler, store ResultStore) *Engine

func (e *Engine) GetResult(id string) *TaskResult

func (e *Engine) Healthz() bool

func (e *Engine) Livez() error

func (e *Engine) RecentResults() []TaskResult

func (e *Engine) RehydrateStaleTasks()

func (e *Engine) RemoveResult(id string) bool

func (e *Engine) Status() StatusResponse

func (e *Engine) Submit(task Task) (string, error)

type ExecutionConfig ¶ added in v0.0.50

type ExecutionConfig struct {
	// Keyring is opened from SEI_KEYRING_BACKEND. Nil when unset;
	// sign-tx handlers report a clear error rather than panic.
	Keyring keyring.Keyring

	// RPC talks to the co-located seid CometBFT RPC. Sign-tx handlers
	// use it for the chain-confusion guard and inclusion polling.
	RPC *rpc.Client

	// Checkpointer persists a pre-broadcast TxMarker so a crashed sign-tx
	// task re-adopts its in-flight tx on re-run rather than re-signing.
	// Nil when no durable store is configured.
	Checkpointer Checkpointer
}

ExecutionConfig carries process-wide deps the engine exposes to handlers. Fields are nil when the corresponding subsystem is not configured.

type ResultStore ¶ added in v0.0.25

type ResultStore interface {
	// Save persists a TaskResult. If a result with the same ID already
	// exists, it is overwritten (upsert).
	Save(r *TaskResult) error

	// Get returns a result by ID, or (nil, nil) when not found.
	Get(id string) (*TaskResult, error)

	// List returns the most recent results, newest first, up to limit.
	List(limit int) ([]TaskResult, error)

	// ListStaleTasks returns tasks left in "running" state from a
	// previous process that exited without completing them.
	ListStaleTasks() ([]TaskResult, error)

	// Delete removes a result by ID. Returns true if it existed.
	Delete(id string) (bool, error)

	// Ping verifies the store is responsive. Used by liveness checks.
	Ping() error

	// Close releases underlying resources.
	Close() error
}

ResultStore persists task results across all lifecycle states. Implementations must be safe for concurrent use.

type SQLiteStore ¶ added in v0.0.25

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

SQLiteStore persists task results in a SQLite database.

func NewMemoryStore() (*SQLiteStore, error)

func NewSQLiteStore(dbPath string) (*SQLiteStore, error)

func (s *SQLiteStore) Close() error

func (s *SQLiteStore) Delete(id string) (bool, error)

func (s *SQLiteStore) Get(id string) (*TaskResult, error)

func (s *SQLiteStore) GetTxMarker(taskID string) (*TxMarker, error)

func (s *SQLiteStore) List(limit int) ([]TaskResult, error)

func (s *SQLiteStore) ListStaleTasks() ([]TaskResult, error)

func (s *SQLiteStore) Ping() error

func (s *SQLiteStore) Save(r *TaskResult) error

func (s *SQLiteStore) SaveTxMarker(m *TxMarker) error

type StatusResponse ¶

type StatusResponse struct {
	Status string `json:"status"`
}

StatusResponse is the shape returned by the status endpoint.

type Task ¶

type Task struct {
	ID     string         `json:"id,omitempty"`
	Type   TaskType       `json:"type"`
	Params map[string]any `json:"params,omitempty"`
}

Task is a unit of work submitted by the controller. When ID is set, the engine uses it as the canonical task identifier (enabling deterministic IDs from the controller). When empty, the engine generates a random UUID.

type TaskError ¶ added in v0.0.31

type TaskError struct {
	Task      string `json:"task"`
	Operation string `json:"operation"`
	Message   string `json:"message"`
	Hint      string `json:"hint,omitempty"`
	Retryable bool   `json:"retryable"`
	Cause     string `json:"cause,omitempty"`
}

TaskError is a structured error that includes operator-actionable context. Task handlers return this to provide rich error detail beyond a plain string.

func (e *TaskError) Error() string

type TaskHandler ¶

type TaskHandler func(ctx context.Context, params map[string]any) (json.RawMessage, error)

TaskHandler executes a specific task type. Handlers MUST be idempotent: the engine may re-execute a handler after a crash recovery. The returned json.RawMessage is the handler's optional structured result, persisted on TaskResult.Result and surfaced over GET /v0/tasks/{id}; handlers with no result return nil. The engine stamps the result on both the success and error paths (a handler returning an error may still carry a result, e.g. a tx hash for an inclusion-undetermined gov submit).

func TypedHandler[T any](fn func(ctx context.Context, params T) error) TaskHandler

func TypedHandlerWithResult[T, R any](fn func(ctx context.Context, params T) (R, error)) TaskHandler

type TaskResult ¶

type TaskResult struct {
	ID          string          `json:"id"`
	Type        string          `json:"type"`
	Status      TaskStatus      `json:"status"`
	Run         int             `json:"run"`
	Params      map[string]any  `json:"params,omitempty"`
	Result      json.RawMessage `json:"result,omitempty"`
	Error       string          `json:"error,omitempty"`
	SubmittedAt time.Time       `json:"submittedAt"`
	CompletedAt *time.Time      `json:"completedAt,omitempty"`
}

TaskResult records a task and its outcome.

Result carries a handler's structured output (e.g. assemble-genesis emits {"genesisHash":"<bare-hex>"}). It is optional and additive: handlers that emit nothing leave it nil and it is omitted from the wire, so the currently-deployed controller is unaffected. This in-band channel — read by the controller over the trusted GET /v0/tasks/{id} path — is the authenticated alternative to publishing results through attacker-writable shared storage.

type TaskStatus ¶ added in v0.0.15

type TaskStatus string

TaskStatus represents the lifecycle state of a task.

const (
	TaskStatusRunning   TaskStatus = "running"
	TaskStatusCompleted TaskStatus = "completed"
	TaskStatusFailed    TaskStatus = "failed"
)

type TaskType ¶

type TaskType string

TaskType identifies the kind of task to execute.

const (
	TaskSnapshotRestore          TaskType = "snapshot-restore"
	TaskConfigPatch              TaskType = "config-patch"
	TaskConfigApply              TaskType = "config-apply"
	TaskConfigValidate           TaskType = "config-validate"
	TaskConfigReload             TaskType = "config-reload"
	TaskMarkReady                TaskType = "mark-ready"
	TaskRestartSeid              TaskType = "restart-seid"
	TaskConfigureGenesis         TaskType = "configure-genesis"
	TaskConfigureStateSync       TaskType = "configure-state-sync"
	TaskSnapshotUpload           TaskType = "snapshot-upload"
	TaskResultExport             TaskType = "result-export"
	TaskAwaitCondition           TaskType = "await-condition"
	TaskGenerateIdentity         TaskType = "generate-identity"
	TaskGenerateGentx            TaskType = "generate-gentx"
	TaskUploadGenesisArtifacts   TaskType = "upload-genesis-artifacts"
	TaskAssembleAndUploadGenesis TaskType = "assemble-and-upload-genesis"
	TaskSetGenesisPeers          TaskType = "set-genesis-peers"
	TaskGovVote                  TaskType = "gov-vote"
	TaskGovSoftwareUpgrade       TaskType = "gov-software-upgrade"
	TaskGovParamChange           TaskType = "gov-param-change"
	TaskEvmLogicalDigest         TaskType = "evm-logical-digest"
)

type TxMarker ¶ added in v0.0.61

type TxMarker struct {
	TaskID        string
	TxHash        string
	TxBytes       []byte
	AccountNumber uint64
	Sequence      uint64
	ChainID       string
}

TxMarker is the pre-broadcast idempotency record for a sign-tx task — engine-owned metadata read during crash recovery, distinct from a handler's TaskResult.Result. It carries the signed tx bytes so a re-run re-broadcasts the identical tx rather than re-signing (which risks a double submit).