Documentation
¶
Overview ¶
Package ops builds the individual HAPI operations beacon submits. Each builder returns a ready-to-submit hiero transaction (or a query) with exactly the fields the operation requires and nothing more; submission and outcome verification are the client package's job.
The freeze family (design §6.2, §9) is the core upgrade trigger: every variant is a single FreezeService.freeze call differing only in which of {freeze_type, start_time, update_file, file_hash} it sets. The deprecated start_hour/min and end_hour/min fields are never used.
Index ¶
- Constants
- func FileInfoOf(hc *hiero.Client, fileID hiero.FileID) (hiero.FileInfo, error)
- func FileMemo(hc *hiero.Client, fileID hiero.FileID) (string, error)
- func FreezeAbort() *hiero.FreezeTransaction
- func FreezeOnly(start time.Time) *hiero.FreezeTransaction
- func FreezeUpgrade(start time.Time, updateFile hiero.FileID, hash []byte) *hiero.FreezeTransaction
- func HashBytes(data []byte) []byte
- func NetworkVersion(hc *hiero.Client) (hiero.NetworkVersionInfo, error)
- func ParseStartTime(s string) (time.Time, error)
- func ParseUpgradeHash(s string) ([]byte, error)
- func PrepareUpgrade(updateFile hiero.FileID, hash []byte) *hiero.FreezeTransaction
- func ResumeUpload(u Uploader, readMemo MemoFunc, fileID hiero.FileID, data []byte) error
- func SemverString(v hiero.SemanticVersion) string
- func UpgradeTelemetry(start time.Time, telemetryFile hiero.FileID, hash []byte) *hiero.FreezeTransaction
- func UploadRawFile(u Uploader, fileID hiero.FileID, data []byte) error
- func VerifyUploadedHash(hc *hiero.Client, fileID hiero.FileID, wantRaw []byte) error
- type MemoFunc
- type SubmitFunc
- type Uploader
Constants ¶
const DefaultCheckpointEvery = 128
DefaultCheckpointEvery is how often the upload driver awaits a receipt (rather than firing) during a bulk append. It bounds how far the running hash can silently diverge before a rejected chunk surfaces: a failure is caught within this many chunks instead of only at the final hash read-back, so resume has little to redo. Callers may override it via Uploader.CheckpointEvery.
const StartTimeLayout = "2006-01-02.15:04:05"
StartTimeLayout is yahcli's UTC start-time format (Go reference layout). The parsed instant is in UTC, which is what FreezeTransaction.SetStartTime takes.
Variables ¶
This section is empty.
Functions ¶
func FileInfoOf ¶
FileInfoOf reads fileID's on-chain metadata (size, expiry, keys, memo) via FileInfoQuery. For special files the memo holds the running SHA-384 of the staged contents (§7).
func FileMemo ¶
FileMemo reads fileID's memo — the running SHA-384 of a special file's staged contents (§7) — trimmed. It backs both the post-upload read-back (VerifyUploadedHash) and resume's boundary match (ResumeUpload).
func FreezeAbort ¶
func FreezeAbort() *hiero.FreezeTransaction
FreezeAbort builds a FREEZE_ABORT freeze: it cancels a scheduled freeze/upgrade before it fires. No start time, update file, or hash.
func FreezeOnly ¶
func FreezeOnly(start time.Time) *hiero.FreezeTransaction
FreezeOnly builds a FREEZE_ONLY freeze: the network halts at start without any software change. No update file or hash.
func FreezeUpgrade ¶
FreezeUpgrade builds a FREEZE_UPGRADE freeze: at start the network halts and applies the software previously staged by PrepareUpgrade. updateFile and hash must match the PrepareUpgrade that staged them.
func HashBytes ¶
HashBytes returns the SHA-384 digest of data — the hash contract the network tracks for special files (§7) and the value passed to prepare-upgrade.
func NetworkVersion ¶
func NetworkVersion(hc *hiero.Client) (hiero.NetworkVersionInfo, error)
NetworkVersion queries a running network for its active build: the Hedera services version and the HAPI protobuf version (HAPI NetworkGetVersionInfo, design §6.2). It is the post-restart confirmation that a software upgrade is live (§7 step 5).
func ParseStartTime ¶
ParseStartTime parses yahcli's UTC start-time literal (yyyy-MM-dd.HH:mm:ss) into a time.Time. The result is in UTC.
func ParseUpgradeHash ¶
ParseUpgradeHash decodes a hex SHA-384 upgrade-zip hash into raw bytes for FreezeTransaction.SetFileHash. It requires a well-formed 48-byte (SHA-384) digest, catching a truncated or wrong-algorithm hash before submission.
func PrepareUpgrade ¶
func PrepareUpgrade(updateFile hiero.FileID, hash []byte) *hiero.FreezeTransaction
PrepareUpgrade builds a PREPARE_UPGRADE freeze: it stages the software on the nodes from updateFile, pinned to hash. No start time — preparation is immediate. hash must be the SHA-384 of the staged updateFile contents, the same value later passed to FreezeUpgrade.
func ResumeUpload ¶
ResumeUpload continues an interrupted UploadRawFile without re-sending chunks the network already has (design §8.2). It reads fileID's memo (the running SHA-384 of the staged contents), matches it to a chunk boundary — checking only boundaries, O(#chunks) — and resumes FileAppend from the first missing chunk. It never re-sends the initial FileUpdate past a match (that would truncate the file); if no boundary matches (empty/unreadable memo, or a mismatch), it falls back to a full upload from chunk 0, which FileUpdate safely resets.
func SemverString ¶
func SemverString(v hiero.SemanticVersion) string
SemverString renders a HAPI SemanticVersion as canonical semver (major.minor.patch, with optional -pre and +build), e.g. "0.58.3" or "0.58.0-rc1+abcdef".
func UpgradeTelemetry ¶
func UpgradeTelemetry(start time.Time, telemetryFile hiero.FileID, hash []byte) *hiero.FreezeTransaction
UpgradeTelemetry builds a TELEMETRY_UPGRADE freeze: at start the network applies the telemetry/observability bundle staged in telemetryFile (0.0.159 by default), pinned to hash.
func UploadRawFile ¶
UploadRawFile writes data verbatim into fileID: an initial FileUpdate carrying the first chunk, then sequential FileAppend chunks of up to bytesPerOp until the file is fully written (design §8.1, §9 gaps 1–2 — the SDK's append defaults are bypassed by driving the loop ourselves for progress control and checkpointing). It is generic over the target file, so the telemetry file (0.0.159) reuses it.
func VerifyUploadedHash ¶
VerifyUploadedHash reads fileID's info and asserts its memo — where the network records the running SHA-384 of a special file (§7) — equals wantRaw. This is the post-upload read-back that makes "success" mean the staged file is observably correct (§5), not merely that the writes were accepted.
Types ¶
type MemoFunc ¶
MemoFunc returns a file's current memo — where the network records the running SHA-384 of a special file's staged contents (§7), as hex. It is the read seam for resume, mirroring SubmitFunc on the write side, and lets ResumeUpload be unit-tested without a node.
type SubmitFunc ¶
type SubmitFunc func(tx hiero.TransactionInterface) error
SubmitFunc submits one transaction. Depending on which Uploader seam it backs it either fires the transaction (returns at precheck) or awaits its SUCCESS receipt. It is the seam between the network-free upload driver here and the client package, and lets the driver be unit-tested without a node.
type Uploader ¶
type Uploader struct {
// Fire submits a transaction and returns at precheck, without a receipt.
Fire SubmitFunc
// Verify submits a transaction and awaits its SUCCESS receipt.
Verify SubmitFunc
// ReadMemo reads the target file's running-hash memo. When set, each checkpoint
// compares it against the expected SHA-384 of the chunks staged so far, so a
// fired chunk that silently failed is caught within CheckpointEvery chunks
// rather than only at the final read-back. Leave nil for files whose memo is
// not a running hash (checkpoints then rely on the append receipt alone).
ReadMemo MemoFunc
// CheckpointEvery awaits a receipt every N append chunks; <=0 uses the default.
CheckpointEvery int
}
Uploader drives special-file upload transactions. It separates the fast Fire path (submit + precheck, no receipt) used for the bulk of the append chunks from the Verify path (submit + await SUCCESS receipt) used for the initial FileUpdate and periodic checkpoints. Firing most chunks lets a large upload run at the node's ingest rate instead of one consensus round-trip per chunk, while the checkpoints still catch a rejected chunk early; the caller's final on-chain hash read-back verifies the upload as a whole. Both seams are injected so the driver stays unit-testable without a node.
Source Files