Hashing (Proof-of-Work)

Purpose: The single canonical reference for the Structs proof-of-work hashing mechanism. Covers the four struct-bound hash types, the universal input format, the algorithm, age-based difficulty, planet ore clocks, raid pause, the permission model, and the CLI/client surfaces. If you only read one PoW doc, read this one. Build-specific framing lives in building.md; guild founding is a paid transaction with no proof-of-work (see the structs-guild skill); strategy and job-tracking live in async-operations.md.

What Hashing Is and Why It Exists

Four struct-bound game actions are not finalized by a simple transaction — they are committed by a transaction and then finalized by submitting a valid proof-of-work hash:

• Build a struct
• Mine ore
• Refine ore into Alpha Matter
• Raid a planet

Each of these is a two-step action: an initiate (or equivalent state change) that starts a clock, followed by a complete message that carries a proof and a nonce. The chain re-derives the hash from on-chain state plus your nonce, checks it equals your proof, and checks it clears the current difficulty. Only then does the action finalize.

These four are the only proof-of-work puzzles in the game. Founding a guild is a paid transaction (guild-create, 2,000,000 ualpha from the founder’s vault), not a hash race; the guild-charter query and the guildCharter* params still exist in state but nothing consumes them.

Hashing exists to make these high-value actions cost real work or real time, and to make that cost decay with age. A freshly initiated operation is effectively impossible to complete; an aged one is trivial. This is the engine behind the core tempo rule: initiate early, compute later. It is also what creates the ore-theft vulnerability window — refined Alpha is safe, but ore sits stealable for the entire ~34h refine clock. See resources.md and async-operations.md.

The Four Struct-Bound Hash Types

All four share one algorithm and one validator. They differ only in the hash-input keyword, the ID they key off, which clock supplies blockStart, and which parameter supplies the difficulty range.

The “difficulty range” is the tuning parameter the decay formula divides by. A higher range means difficulty decays more slowly (the operation stays hard for longer). It is not the difficulty itself.

Each complete message carries exactly two PoW fields plus the signer:

Universal Input Format

Every hash type builds its input string by concatenating known fields with literal keyword separators — no delimiters, no JSON, no length prefixes. The block height is rendered as a base-10 string, the nonce is appended as a string.

Struct operations (build / mine / refine):

hashInput = {id} + {KEYWORD} + {blockStart} + "NONCE" + {nonce}

where {KEYWORD} is one of "BUILD", "MINE", "REFINE".

Raid (two IDs joined by @):

hashInput = {fleetId} + "@" + {planetId} + "RAID" + {blockStart} + "NONCE" + {nonce}

Mine and refine still key the input on structId, but {blockStart} is the planet clock, not a per-struct attribute. Completing any extractor on a planet resets that shared mine clock for every extractor on the planet.

Worked examples

Universal format rules

If you compute proofs with an external tool, you must reproduce this exact concatenation and lowercase-hex encoding, or the chain will reject the proof.

The Algorithm

hash       = sha256( utf8_bytes(hashInput) )        # single SHA-256
proofHex   = lowercase_hex(hash)                     # 64 chars, [0-9a-f]
isValid    = (submittedProof == proofHex)
             AND (first `difficulty` hex chars of proofHex are all '0')

Key facts:

• One SHA-256 pass. No double-hash, no keccak, no salt beyond the input string itself.
• Difficulty is counted in leading hex zeros, not bits and not bytes. A difficulty of D requires the digest to begin with D consecutive 0 hex characters, so the per-attempt success probability is 1 / 16^D.
• The proof must match exactly. The chain recomputes the hash from on-chain state + your nonce; if your submitted proof is not byte-identical to that recomputation, it fails before the difficulty check.
• Max difficulty is 64 (the full digest length).

The validator (HashBuildAndCheckDifficulty) returns both validity and the achievedDifficulty (how many leading zeros the digest actually had), which is emitted in the EventHashSuccess event.

Difficulty and Decay

Difficulty is age-based and drops logarithmically as the operation’s clock ages:

age = currentBlockHeight - blockStart

if age <= 1 or range <= 1:
    difficulty = 64                                  # effectively impossible
else:
    e          = max { k in 0..63 : range^k <= age^63 }   # exact integer arithmetic
    difficulty = 64 - e                              # never below 1

• age is in blocks (~6 sec/block).
• range is the per-type difficulty source from the table above (BuildDifficulty, OreMiningDifficulty, OreRefiningDifficulty, or the planet’s PlanetaryShield).
• At age <= 1 the difficulty is pinned to 64, so you cannot complete on the same block you initiated.
• A larger range makes the curve fall more slowly — bigger operations stay hard longer.
• The integer form is mathematically 64 − floor(63·log(age)/log(range)), evaluated with big-integer powers rather than floating-point logarithms so every node computes the same answer. A client that uses log10 will agree except at the exact boundary blocks, where floating-point rounding can be off by one — always re-check difficulty against the chain before submitting, or hash one block later than the boundary.

The difficulty cliff

The jump between D=8 and D=9 is the single most important tactical fact in PoW. But even D=8 burns CPU. The recommendation is to wait for D=3, where the hash is trivially instant and zero CPU is wasted — the wait is the cost.

Time-to-difficulty table (6 sec/block)

At range = 10 the curve is so short that difficulty is already 1 once the Extractor is 10 blocks old; -D is irrelevant for it.

To compute for any range and target D:

age_blocks   = ceil( range ^ ((64 - D) / 63) )      # smallest age with range^(64-D) <= age^63
time_seconds = age_blocks * 6

Worked example: fresh vs aged anchor

The same operation is impossible or instant depending only on how old its clock is. This is why timing dominates PoW.

• Fresh anchor (age <= 1): difficulty is pinned to 64. The proof is rejected — you cannot complete on or near the block you initiated. A brand-new build sits here.
• Aged anchor: difficulty falls to 1 once the clock reaches range blocks old, and stays there. For a Command Ship build (range = 200), age = 200 blocks (~20 min) gives 200^63 <= 200^63, so e = 63 and difficulty = 1. For a mine (range = 14,000), difficulty hits 1 at age = 14,000 blocks (~23 hr). A struct you initiated and left untouched for tens of thousands of blocks is at difficulty 1 — the nonce is found in a handful of attempts (milliseconds).

So an old, abandoned anchor is a cheaper proof than a fresh one: initiate the moment you can, then come back later when the difficulty has decayed. A raid keyed to the target planet’s blockStartRaid works the same way — the longer that planet has been raid-vulnerable, the cheaper the raid proof.

Because the mine and refine clocks reset after every successful completion (see the per-type clock below), back-to-back mining of the same extractor re-enters the full decay each cycle. Repeat-mining is therefore naturally paced — you re-wait the decay every time, not just once.

The Per-Type Clock (blockStart)

The age that drives difficulty is measured from a clock specific to each operation. Knowing when each clock starts (and resets) tells you when a proof becomes cheap.

Because mining and refining clocks reset every cycle, a long-running extractor/refinery re-ages from scratch after each completion — you re-wait the full decay each time. Because those clocks are shared per planet, completing on extractor A resets extractor B’s remaining wait too.

Mine/Refine Cycle Lifecycle

The mine and refine clocks are not just a difficulty input — they define a cycle whose lifecycle is easy to get exactly backwards. The rules (from x/structs/keeper/planet_cache.go and struct_cache.go):

• Activation starts the first cycle. Bringing a mining/refining struct online (OreMiningActivate / OreRefiningActivate) increments the planet’s active quantity. The shared clock is re-anchored only on 0→1. There is no separate “begin mining” or “begin refining” action — activation is the start when you are the first rig. The *-compute commands compute and submit the completion, not the start.
• Deactivating does not clear the clock. Going offline decrements oreMiningActiveQuantity / oreRefiningActiveQuantity. The clock stays. A stale clock with a zero counter is harmless; the next 0→1 activate re-anchors.
• Cycles never expire. There is no staleness or timeout check. An anchor thousands (or hundreds of thousands) of blocks old is still perfectly completable — and is cheaper to complete, because difficulty has fully decayed. Never “clean up” an aged mine/refine — completing it is the cheapest possible proof.
• Completion auto-restarts the cycle. A successful MsgStructOreMinerComplete / MsgStructOreRefineryComplete resets the planet clock to the current block. Every extractor/refinery on that planet re-enters the full decay.
• Ore is checked at completion, not at start. CanOreRefine only requires stored ore at the moment of completion (HasStoredOre). You can activate a refinery with 0 ore, mine (or receive) ore mid-cycle, and complete successfully. Practical consequence: start the refinery alongside the extractor rather than mine-then-refine serially — the pipeline completes faster.

Raid pause (mine and refine)

While a visiting fleet heads the planet’s raid queue (locationListStart != ""), mine and refine compute and complete are rejected with under_raid. The CLI prints planet (...) is under raid: mining is paused until the raid ends (refine equivalent).

Difficulty does not keep dropping during that window. When the queue empties, PauseOreClocksForRaid shifts each active planet ore clock forward by the paused interval (blockRaiderArrived → raid end), so pre-raid age is preserved. A clock that was first anchored during the raid lands at age zero.

Do not launch or retry struct-ore-mine-compute / struct-ore-refine-compute while the planet is under raid. Wait for the visitor to leave, then resume — the preserved age is still there.

Permissions Relating to Hashing

Hashing is not permissionless. Completing a struct-bound proof is gated at two independent layers, and each of the four types requires its own matching permission bit (not all four).

Layer 1 — Address permission (ante handler)

Before a complete message reaches its handler, the ante decorator checks the signing address holds the matching bit:

An unregistered address, or a registered address lacking the bit, is rejected here.

Layer 2 — Object permission (keeper handler)

The handler then verifies the caller may act on the owner of the object via CanBuildHashedBy / CanMineHashedBy / CanRefineHashedBy / CanRaidHashedBy, each of which runs a PermissionCheck for the same single bit (PermHashBuild / PermHashMine / PermHashRefine / PermHashRaid). The check passes if the caller:

1. is the owner of the object, or
2. holds object-level permission for that bit on the owner, or
3. meets the guild-rank threshold for that permission.

The permission bits

A player’s primary address receives PermAll, so owners can always complete their own work. The interesting case is delegation.

Delegation recipe (open-but-granted hashing)

Because completing a proof requires only the relevant hash_* bit, you can hand the grind to a low-trust worker key without exposing your play/transfer permissions:

# Grant a worker address play + all hash permissions (and nothing else)
structsd tx structs permission-set-on-address cosmos1worker... 15728641 \
  --from primary --gas auto -y
# 15728641 = PermPlay (1) | PermHashAll (15728640)

That worker can now submit *-complete proofs on your behalf but cannot move tokens or restructure your account. See structs-permissions for the full delegation model.

Throttle

The ante also throttles proofs to one attempt per object per block (keyed by the struct/fleet ID). Spamming proofs for the same object in a single block is rejected.

CLI and Client Surfaces

CLI — compute vs complete

The -D flag tells *-compute not to start hashing until difficulty has dropped to that level. The CLI polls block height and sleeps until the target is reached. Use -D 3 for instant, zero-waste hashing. The *-compute commands auto-submit minutes to days later, so they always run in the auto-approved form — see conventions and SAFETY.md.

Client — the webapp TaskManager

The web client implements the identical scheme: a TaskManager spawns a Web Worker per task that loops sha256(prefix + nonce) until the leading-hex-zero check passes, then submits the matching Msg*Complete (proof = the hex digest, nonce = decimal string). It builds the same input strings ({id}{KEYWORD}{blockStart}NONCE{nonce}, raid uses @), uses the floating-point form of the same difficulty formula (64 - floor(log10(age)/log10(range)*63)), and re-checks difficulty before submitting so a stale proof restarts rather than failing on-chain. Any conformant client — CLI, webapp, or your own bot — interoperates because the input format and algorithm are fixed.

Its wait policy is its own choice, not part of the protocol: the worker sleeps in 10-second polls until difficulty reaches 10 or below, rather than the -D 3 this guide recommends for the CLI. Both are conformant — a client may start hashing at any difficulty it likes. See develop/client/work-and-pow.md for the full client-side implementation.

Not Proof-of-Work (Disambiguation)

Several other game flows use the words “proof” or “hash” but are not this SHA-256 PoW:

The submitted-SHA-256-proof mechanism described in this doc is build, mine, refine, and raid. Address registration and proxy join are signatures, not difficulty hashes.

Source References

For verification against the chain and client implementations.

structsd (chain):

structs-webapp (client):

See Also

• building.md — Build-specific PoW framing, struct states, charge
• async-operations.md — Background compute, the pipeline pattern, job tracking
• combat.md — Raids, shield vulnerability, the raid clock
• fleet.md — Visiting-fleet queue that arms under_raid
• resources.md — Ore vulnerability window driven by the refine clock
• permissions.md — Full 25-bit permission model and handler reference
• structs-guild skill — Paid guild founding (no proof-of-work)
• schemas/formulas.md — Difficulty formulas alongside other game math
• api/integration-notes.md — Live data-shape gotchas for integrators (endpoints, event detail, field-name traps)
• conventions — Proof-of-work policy and the -D 3 default