structs-energy

Structs Energy Management

Safety

See SAFETY.md for the trust contract. In this skill:

• reactor-infuse (Tier 1) — "Your alpha locks into the reactor; commission rate is captured permanently. Defusion has a cooldown." Surface the validator address, commission, and ualpha amount.
• struct-generator-infuse (Tier 2 — irreversible) — "Alpha Matter is annihilated in the conversion. And the generator is raidable — if it falls, the infused matter falls with it." Confirm the generator's defense posture (shield, PDC, defenders) before infusing.
• agreement-open (Tier 1) — "You pay upfront for the full duration. Closing early may trigger a cancellation penalty." Surface rate, duration in blocks, and total cost.
• reactor-defuse (Tier 2 — cooldown lock-in) — "Your alpha is suspended between reactor and wallet during the cooldown."
• Denomination footgun — reactor-infuse and struct-generator-infuse require the ualpha denomination suffix on the amount (e.g. 60000000ualpha, not 60000000). Missing denom = failed tx.

Decision Tree

Need more capacity?
├── Have Alpha Matter?
│   ├── Infuse into a reactor (safest, immediate, 1g ≈ 1kW minus commission)
│   │   → See "Reactor Infusion" below
│   └── Infuse into a generator (higher ratio, IRREVERSIBLE, vulnerable to raids)
│       → See "Generator Infusion" below
└── No Alpha Matter?
    └── Buy energy from a provider via agreement
        → See "Buy Energy" below

Have surplus energy?
└── Sell it by creating a provider
    → See "Sell Energy" below

---

Reactor Infusion (most common path)

Infusing Alpha Matter (ualpha) into a reactor immediately increases the player's capacity. This is the safest and most common way to get more energy.

How It Works

When you infuse ualpha into a reactor, the system generates power equal to the amount infused. This power is split between you and the reactor based on the reactor's commission rate:

• Player receives: power * (1 - commission)
• Reactor receives: power * commission

The player's capacity increases automatically — no allocation or substation setup needed.

Example

Infusing 3,000,000 ualpha into a reactor with 4% commission:

{
  "destinationType": "reactor",
  "destinationId": "3-1",
  "fuel": "3000000",
  "power": "3000000",
  "commission": "0.040000000000000000",
  "playerId": "1-33"
}

• fuel: 3,000,000 ualpha infused
• power: 3,000,000 mW generated (1 ualpha = 1 mW = 0.001 W)
• Reactor keeps 4%: 120,000 mW (120 W)
• Player receives 96%: 2,880,000 mW (2,880 W) added to capacity

Procedure

1. Check current capacity: structsd query structs player [id]
2. Choose a reactor (usually your guild's): structsd query structs reactor [id] — note the commission field
3. Infuse (the CLI will prompt for confirmation — review reactor commission, ualpha amount, and validator address before accepting):

structsd tx structs reactor-infuse [your-address] [validator-address] [amount]ualpha --from [key-name] --gas auto --gas-adjustment 1.5

Important: The amount must include the denomination, e.g. 60000000ualpha (not just 60000000). Omitting the denom will cause the transaction to fail.

1. Verify: re-query player, confirm capacity increased

Choosing a Reactor

• Your guild's reactor is the default choice — it strengthens the guild and you benefit from guild infrastructure
• Lower commission = more capacity for you
• Check commission before infusing: structsd query structs reactor [id]
• You can infuse into any reactor, not just your guild's
• The reactor-infuse command takes the validator address (structsvaloper1...), not the reactor ID. Find it in the reactor query output's validator field

Undoing Infusion

• structsd tx structs reactor-defuse [reactor-id] — starts a cooldown period before ualpha is returned
• structsd tx structs reactor-cancel-defusion [reactor-id] — cancel defusion and re-stake
• structsd tx structs reactor-begin-migration [player-address] [source-validator-address] [dest-validator-address] [amount] — move stake to a different reactor (takes addresses, not IDs)

---

Generator Infusion

Generators convert Alpha Matter to energy at higher ratios than reactors, but the infusion is irreversible and the generator is vulnerable to raids.

Conversion Rates

Procedure

1. Identify your generator struct: structsd query structs struct [id] — must be type 20, 21, or 22

2. Approval Block — generator infusion is Tier 2 (irreversible). Before signing, confirm:

   • struct-id is the generator you intend
   • amount of ualpha (this Alpha is annihilated on success — no defusion exists)
   • Generator's current defense posture: shield > 0, PDC online, no inbound fleet
   • --from key is the player who owns the generator

3. Infuse (CLI prompts for confirmation — review one more time on the prompt):

structsd tx structs struct-generator-infuse [struct-id] [amount]ualpha --from [key-name] --gas auto --gas-adjustment 1.5

Important: Amount must include denomination, e.g. 5000000ualpha.

1. Verify: query player for capacity increase

When to Use Generators

• You need maximum energy efficiency per gram of Alpha Matter
• You have defense in place (shields, PDC, defenders) to protect the generator
• You accept the risk that if the generator is destroyed, the infused Alpha is lost forever

Do not infuse generators without adequate defense.

---

Buy Energy (Agreement Path)

If you have no Alpha Matter to infuse, you can buy energy from another player who is running a provider.

Procedure

1. Find a provider: Query available providers:

structsd query structs provider-all

Or check your guild's providers. Look for one with acceptable rateAmount, capacityMaximum, and durationMaximum.

1. Open an agreement (CLI prompts — review rate × duration × capacity for the total upfront cost before accepting):

structsd tx structs agreement-open [provider-id] [duration-in-blocks] [capacity] --from [key-name] --gas auto --gas-adjustment 1.5

The agreement automatically creates an allocation.

1. Connect the allocation to a substation:

structsd tx structs substation-allocation-connect [substation-id] [allocation-id] --from [key-name] --gas auto --gas-adjustment 1.5

Connect to your guild's substation to benefit the guild, or create your own substation for independent energy management.

1. Verify: Query player to confirm capacity increased.

Agreement Management

• Increase capacity: agreement-capacity-increase [agreement-id] [additional-capacity]
• Decrease capacity: agreement-capacity-decrease [agreement-id] [reduce-by]
• Extend duration: agreement-duration-increase [agreement-id] [additional-blocks]
• Close: agreement-close [agreement-id] — may incur cancellation penalty

---

Sell Energy (Energy Commerce Pipeline)

If you have surplus capacity, you can sell energy to other players through the reactor-allocation-substation-provider pipeline. This is the core of Structs economic gameplay.

Full Pipeline (Step by Step)

1. Accumulate Alpha -- Mine ore, refine immediately. Consolidate ualpha to the account that will manage energy commerce.

2. Infuse into reactor -- Increases your player capacity. Use your guild's reactor for simplicity:

structsd tx structs reactor-infuse [your-address] [validator-address] [amount]ualpha --from [key-name] --gas auto

The validator-address is structsvaloper1... (find it in structsd query structs reactor [id] under the validator field). Commission is locked at infusion time and permanent for that infusion.

1. Create automated allocation -- Routes your capacity to a substation. Use automated type so it auto-grows when you infuse more alpha:

structsd tx structs allocation-create --allocation-type automated --from [key-name] --gas auto -- [your-player-id] [power-amount]

1. Create substation -- The distribution node for your energy:

structsd tx structs substation-create --from [key-name] --gas auto -- [your-player-id] [allocation-id]

1. Create provider -- Your marketplace storefront:

structsd tx structs provider-create --from [key-name] --gas auto -- [substation-id] [rate] [access-policy] [provider-penalty] [consumer-penalty] [cap-min] [cap-max] [dur-min] [dur-max]

1. Monitor agreements -- Buyers open agreements against your provider:

structsd query structs provider [provider-id]

1. Withdraw earnings periodically:

structsd tx structs provider-withdraw-balance --from [key-name] --gas auto -- [provider-id]

How Agreements Work (Payment Flow)

When a buyer opens an agreement:

1. Buyer pays capacity * rate * duration upfront in the rate denomination
2. Payment goes into the provider's collateral address (escrow)
3. System auto-creates a provider-agreement allocation (energy flows immediately)
4. Revenue drips from collateral to the provider's earnings address as blocks pass
5. Provider withdraws accumulated earnings at any time
6. On expiry (endBlock reached), the allocation is released

Agreement lifecycle: OPEN -> ACTIVE -> EXPIRED (or CLOSED early with cancellation penalties).

The Energy Flywheel

The most powerful economic strategy in Structs is compounding energy:

1. Mine ore from planets
2. Refine ore into Alpha immediately
3. Infuse Alpha into the guild reactor
4. Automated allocation grows substation capacity
5. Sell energy via provider, earning guild tokens
6. Reinvest guild tokens (via guild-bank-redeem for alpha, or trade)

Each cycle compounds: more alpha = more capacity = more energy to sell = more tokens = more economic power.

Important Notes

• Defusion cooldown: Infused alpha is not immediately liquid. reactor-defuse starts a cooldown period. Don't infuse alpha you may need for short-term operations (fleet rebuilds, emergency purchases).
• Commission is locked: The reactor's commission rate at infusion time is permanent for that specific infusion. Check commission before infusing.
• Automated allocations: Limited to one per source. They auto-grow with your capacity -- no manual adjustment needed after creation. If you attempt to create a second automated allocation from the same source, the transaction will error. Delete the existing one first, or use dynamic type for additional allocations.
• Provider-agreement allocations: Auto-created by the system when agreements open. Do not create or modify these manually.

Provider Management

• Grant guild members access (for guild-market providers): permission-guild-rank-set [provider-id] [guild-id] 262144 [rank] (PermProviderOpen -- guild members at or above the specified rank can open agreements)
• Revoke guild access: permission-guild-rank-revoke [provider-id] [guild-id] 262144
• Update terms: provider-update-capacity-maximum, provider-update-duration-minimum, etc.
• Delete provider: provider-delete [provider-id] (close agreements first)

---

Quick Reference

Commands Reference

TX_FLAGS (interactive — the CLI prompts you to confirm): --from [key-name] --gas auto --gas-adjustment 1.5

TX_FLAGS_APPROVED (only after commander approval; suppresses the prompt): TX_FLAGS plus -y. See SAFETY.md "The -y Rule." reactor-infuse and struct-generator-infuse are Tier 1/Tier 2 — always default to interactive so you see the validator, commission, amount, and (for generators) the irreversibility warning.

Requires: structsd on PATH and a configured signing key.

Important: Entity IDs containing dashes (like 3-1, 4-5) are misinterpreted as flags by the CLI parser. Always place -- between flags and positional args: structsd tx structs command --from key --gas auto -- [entity-id] [other-args]

Error Handling

• Going offline — Load exceeds capacity. Immediately deactivate non-essential structs (struct-deactivate), then increase capacity via reactor infusion or agreement.
• "insufficient balance" — Not enough ualpha. Mine and refine ore first, or buy energy via agreement instead.
• "generator infuse failed" — Verify the struct is a generator type (20, 21, or 22) and is online.
• Commission too high — Check other reactors. You can infuse into any reactor, not just your guild's.
• No providers available — Ask guild members to create providers, or infuse your own reactor.

See Also

• structs-economy skill — Full economic operations (all allocation types, token transfers)
• structs-power skill — Substations, player connections, power monitoring
• knowledge/mechanics/power — Capacity formulas, load calculations, online status
• knowledge/economy/energy-market — Provider/agreement mechanics, pricing
• knowledge/mechanics/resources — Alpha Matter conversion rates