Skip to main content

​
Satcoin mining API and protocol

This is the technical map for Satcoin (SAT) mining inside Fased Agent. Use it to understand how the Control UI, CLI, plugin gateway methods, and Satcoin program instructions line up. This page describes how Fased Agent connects to Satcoin mining v1, the current agent-operated mining protocol implementation. The Satcoin on-chain programs, API crates, layouts, build docs, and security policy live in the public protocol source repo: satcoin-org/sat. Use that repo to verify protocol source. Use this page to understand how Fased Agent connects that protocol to wallets, Gateway, CLI, and the Mining page.

​
Stack map

The public operator surfaces are the Mining page and fased mining. The internal integration surface is the sat.* gateway method family registered by the sat-mining plugin.

​
Runtime IDs

Pre-launch Fased Agent releases do not ship active Satcoin mainnet IDs. Mainnet IDs are written only after Mining Sync verifies the signed Satcoin mainnet manifest. 
config/sat-runtime.env
Manual values are for explicit local/devnet testing or recovery review only. All four values must come from the same signed manifest or the same test deployment: 
FASED_SAT_PROGRAM_ID=
FASED_SAT_BOND_PROGRAM_ID=
FASED_SAT_MINT_ADDRESS=
FASED_SAT_MINT_PROGRAM_ID=
See SAT Mainnet Sync for the operator flow.

​
Constants

ConstantValue
SAT decimals11
hard cap21,000,000 SAT
cycle seconds300
minimum entry0.25 SOL
allocation buckets25
erosion83 ppm
miner SAT route90%
staking SAT route5%
treasury SAT route5%
SOL deterministic rebate30%
SOL performance rebate50%
SOL treasury route15%
SOL staking route5%

​
Control UI routes

The browser Mining page talks to Gateway HTTP routes. These routes require the normal Control UI auth and wallet approval gates where applicable.
RouteMethodPurpose
/api/mining/profileGETread miner profile
/api/mining/profilePUTsave miner profile, strategy, funding, claim, and sweep policy
/api/mining/wallet-attachmentGETread the active singleton mining-wallet assignment
/api/mining/walletsGETlist mining-eligible wallets
/api/mining/readinessGETrun readiness checks
/api/mining/statusGETread live mining status
/api/mining/historyGETread cycle outcomes and recent actions
/api/mining/recoveryGETread recovery summary
/api/mining/startPOSTstart the runtime
/api/mining/stopPOSTstop the runtime
/api/mining/capital/initPOSTinitialize miner capital
/api/mining/reserve/top-upPOSTbootstrap registry reserve
/api/mining/capital/depositPOSTdeposit SOL into miner capital
/api/mining/capital/withdrawPOSTwithdraw free miner capital
/api/mining/capital/commitPOSTset active commit
/api/mining/action/participatePOSTmanually submit current participation
/api/mining/action/crankPOSTmanually advance crank-style work
/api/mining/action/finalize-epochPOSTlegacy-named finalize helper for current roots
/api/mining/action/claimPOSTclaim an eligible cycle
/api/mining/recovery/claimPOSTretry claim for a selected recovery cycle
/api/mining/recovery/resolve-disputePOSTresolve a selected dispute
/api/mining/recovery/republish-rootsPOSTrepublish selected roots after preflight
/api/mining/history/clearPOSTclear local mining history
Some recovery route names still carry legacy epoch wording because the surrounding UI used that name before the current cycle-native protocol was finalized. New protocol language should use cycle where possible.

​
CLI surface

fased mining calls gateway methods through the normal Gateway RPC client. The Mining page and chat @mining control use the same runtime methods. The documented operator command is the installed fased mining ... binary. If the command is missing from a source checkout, run ./install.sh --no-onboard once to install the repo-backed CLI.
CommandGateway methodNotes
fased mining statussat.getMiningStatuslive status, workers, capital, planner, and action summary
fased mining readinesssat.getMiningReadinesswallet, signer, RPC, funding, miner init, ATA checks
fased mining walletssat.listMiningWalletsmining-eligible local wallets
fased mining startsat.startMiningwaits for final result and validates running=true
fased mining stopsat.stopMiningwaits for final result; reports drain mode separately
fased mining historysat.getMiningHistoryhistory and activity windows
fased mining deposit-capitalsat.depositMinerCapitaldeposit SOL into miner capital
fased mining withdraw-capitalsat.withdrawMinerCapitalwithdraw free miner capital
fased mining set-commitsat.setActiveCommitupdate active commit amount
fased mining claim-backlogsat.claimBacklogclaim the oldest ready backlog batch
fased mining keeper runsat.runKeeperOncerun one keeper/cranker tick
fased mining cleanup resolvedsat.closeResolvedCycleAccountsclose resolved cycle accounts for one cycle
CLI start and stop do not rely on a submitted request alone. start prints success only when the final Gateway payload says mining started and the returned status is running. stop prints a hard stopped message only when status is not running; if locked capital or pending cycles remain, the CLI reports drain mode.

​
Gateway methods

​
Profile and wallet methods

MethodPurpose
sat.getMinerProfileread active profile
sat.setMinerProfilesave profile and runtime policy
sat.listMiningWalletslist wallets with mining capability and balances
sat.getMiningWalletAttachmentread the active singleton mining-wallet assignment
sat.getMiningReadinessreturn wallet, signer, RPC, funding, miner init, and ATA checks
sat.getMiningStatusreturn live status, issuance, capital, workers, planner, and history summary
sat.getMiningHistoryreturn stored outcome and action windows
sat.getMiningRecoveryreturn recovery summary and recommended action

​
Capital methods

MethodPurpose
sat.initMinerSlotsprepare miner cycle slots for an authority
sat.initMinerCapitalinitialize miner capital account
sat.depositMinerCapitalmove wallet SOL into miner capital
sat.withdrawMinerCapitalwithdraw free capital back to the wallet
sat.setActiveCommitset on-chain active commit and optionally persist config
sat.bootstrapRegistryReserveinitialize or top up shared reserve support

​
Cycle methods

MethodPurpose
sat.openCycleopen shared cycle state
sat.submitCyclesubmit miner allocation for a cycle
sat.settleCyclePagesettle a registry page chunk
sat.finalizeCycleSettlementfinalize page settlement for a cycle
sat.scoreCyclePagescore participants on a page
sat.distributeCyclePagedistribute miner SAT and rebates for a page
sat.runKeeperOncerun one keeper/cranker tick
sat.claimCycleRewardsclaim one cycle
sat.claimCycleRewardsBatchclaim several cycles
sat.claimBacklogclaim oldest ready backlog batch
sat.retargetUnlockadjust unlock target on cadence
sat.closeResolvedCycleAccountsclose resolved cycle artifacts and reclaim rent
sat.compactPendingCycleRangecompact local pending-cycle tracking

​
Recovery and dispute methods

MethodPurpose
sat.getEpochinspect legacy epoch-compatible state for recovery tooling
sat.getRecoverySummarybuild targeted recovery summary
sat.resolveDisputeresolve dispute state
sat.republishEpochRootsrepublish roots after preflight
sat.getValidatorAttestationinspect one attestation
sat.listValidatorAttestationslist attestations
sat.submitValidatorAttestationsubmit validator attestation
sat.getDisputeinspect one dispute
sat.listDisputeslist disputes
sat.openDisputeopen a dispute

​
Protocol lane methods

MethodPurpose
sat.setProtocolRecipientsset treasury and staking recipients
sat.refillRegistryReserveFromTreasuryrefill the registry reserve from protocol treasury SOL shortfall
sat.claimProtocolTreasuryclaim treasury lane, leaving reserve-aware maintenance first
sat.claimProtocolStakingcompatibility staking lane claim
sat.runProtocolMaintenanceOnceone bounded operator pass over reserve, treasury, and staking lanes
These are protocol maintenance operations. They are not normal miner day-to-day actions, and they are not shown on the Mining page. Launch operators run them from internal maintenance tooling. The bounded model is permissionless: any caller may pay the transaction fee, but the program fixes recipients and caps the action. Reserve refill can only target sat_registry_reserve and only up to the configured shortfall. Treasury and staking claims use fixed protocol recipients, so a random caller cannot redirect protocol funds.

​
Bond-staking roadmap boundary

Miner auto-claim only claims that miner’s own cycle SAT and rebates. It does not claim the protocol treasury lane, the protocol staking lane, or other miners’ SAT. The bond-staking distributor consumes the existing protocol staking lane without coupling staking logic into mining settlement:
  • split staking SAT claim pulls pending staking-lane SAT to the bond distributor vault
  • split staking SOL claim sends the SOL lane to the ops/maintenance recipient
  • eligible staking bonds can share SAT from the distributor by index accounting
  • each staking bond owner still claims their own synced SAT amount
Bond-staking policy belongs to launch configuration and public launch proof. This API page only describes the integration boundary: miner auto-claim is miner-owned, while bond distributor claims are position-owned and separate from miner claim-out. Basic bonds can be used for identity and anti-spam, while any staking-weight thresholds, warmup, cooldown, or unlock timing must come from the active launch configuration.

​
Scale improvement roadmap

The current keeper and auto-claim loop is the launch baseline. The runtime now has the operator controls needed to rehearse scale deliberately before raising any defaults:
TrackFased Agent work
Larger claim batchesautomation.claimBatchCycles defaults to 5 and is capped at 16; benchmark 5, 8, 10, 12, and 16 before raising the default
Delayed-claim recoverypersist backlog status, claim oldest ready cycles first, and expose fased mining claim-backlog
Public keeper toolingexpose fased mining keeper run for one headless keeper/cranker tick by an eligible miner wallet
RPC hardeningsupport primary/backup RPC, show timeout/rate-limit counters, and separate read/submit paths where useful
Account cleanupexpose fased mining cleanup resolved --cycle <id> first; add broad scanners only after delayed claims are proven
Metricsshow settlement lag, claim backlog, failed keeper steps, keeper wins/misses, reserve health, and cleanup queue size
Keep settlement chunk size conservative until compute, account count, and unattended soak runs prove a larger value.

​
Config fields

The plugin config lives under plugins.entries["sat-mining"].config.
FieldMeaning
enabledwhether the runtime wants mining enabled
networklocal, devnet, or mainnet-beta
walletIdactive mining wallet id
roleminer, validator, or admin
riskModelegacy risk name: conservative, balanced, aggressive, swarm
strategyPresetcurrent preset: spread, balanced, conviction, swarm, top_k, ranked, adaptive, crowd_aware, or safe_fallback
strategyExecutiondeterministic or auto
strategyModelegacy mode: base or skill
commitLamportsconfigured active commit in lamports
minSolBalanceLamportswallet reserve target
claimModeauto, prompt, or manual
skillConfigmodel or skill-backed strategy planning options
automation.autoFinalizeEpochautomatic settlement-finalize helper
automation.autoClaimautomatic claim helper
automation.claimBatchCycleshidden claim backlog batch cap; defaults to 5, capped at 16
automation.satSweeppost-claim sweep policy
tokenConfigSAT program, bond program, mint, and mint program overrides
plannerConfigUCB or Thompson planner policy options
federationHandleoptional Fased Network handle context
federationPeersoptional coordination peer list
coordinationGroupoptional coordination group label
claimMode is a runtime profile value. The beginner Mining page should not be read as promising a separate manual protocol claim product. Normal stable mining uses automatic miner claim; prompt and manual are advanced review or recovery profile settings when exposed by the active install.

​
State layout

Common PDA seed families:
  • sat_global_state
  • sat_cycle_state
  • sat_cycle_registry_meta
  • sat_cycle_registry_page
  • sat_cycle_settlement_progress_v2
  • sat_miner_cycle_state
  • sat_miner_capital_state
  • sat_treasury_state
  • sat_registry_reserve
  • sat_rebate_vault
  • sat_treasury_vault
  • sat_staking_vault
  • sat_bond_position
  • sat_bond_tier_policy

​
Authority and PDA notes

PDAs do not have private key files. The program signs for them by seed when an instruction path allows it. Satcoin authority surfaces:
SurfaceMeaning
SAT program upgrade authoritycan upgrade SAT mining program code while retained
SAT mint program upgrade authoritycan upgrade mint-program code while retained
SPL mint authorityshould be the SAT mint-authority PDA after init
SPL freeze authorityshould be none for the public mint posture
SAT program_admincan set treasury and staking recipient addresses
bond policy update authoritycan update bond tier thresholds and unlock delay
The miner runtime does not hold admin keys. It uses the singleton @wallet:mining wallet for operator actions and reads the configured program ids, mint address, mint program id, bond program id, network, and RPC.

​
Cost and account flow

Satcoin mining has three separate SOL concepts:
ConceptMeaning
wallet SOLpays transaction fees and missing account creation
miner capitalSOL deposited into the miner capital PDA for commit, erosion, and rebate accounting
registry reserveprotocol PDA that pays shared cycle, registry, and settlement account rent
Per-cycle flow:
  • the miner wallet pays submit, settlement, claim, and recovery transaction fees
  • the miner wallet pays miner-cycle PDA rent when it first submits that cycle
  • active commit is locked inside miner capital until distribute releases it
  • erosion is charged from miner capital and routed into rebate, treasury, and staking lanes
  • keeper bounty comes from the performance rebate lane when the cycle can fund it
  • claim mints Satcoin to the miner ATA and moves SOL rebate back into miner capital
Treasury/staking recipients are fixed recipient lanes. They are not the payer for normal shared cycle account creation. In the bond-staking path, the staking recipient can become a distributor PDA while the SOL staking lane remains an operations support route. Cycle committed SOL is mining participation. Market liquidity is a separate post-launch venue concept.

​
Integration rules

  • Use the CLI or Control UI for operator actions.
  • Use sat.* gateway methods for internal automation.
  • Use the Satcoin IDL and program account layouts as source of truth for raw wire integration.
  • Keep wallet SOL, miner capital, claimed Satcoin, and bond Satcoin separate.
  • Treat legacy epoch names as compatibility names around recovery helpers, not the current protocol vocabulary.
  • Prefer local-socket-signer for unattended Satcoin mining.
  • Do not bypass wallet approval gates for capital, sweep, or policy changes.