# Infrastructure provider registration and operation

Status: the identity-enforcing factory is deployed on Coston2 at
`0x8B9515dE9A6bd2508b5cDf18FaBd6187a670ae5A`, bound to Governor
`0x95E3780cEE4Cd5ba60d05e5E0B75123D7bd51ba3`. This is not a Flare-mainnet
deployment. hpFLR remains the initial/default infrastructure LST. Every new
provider still requires infrastructure-wallet authorization and governance approval.

## What approval creates

A MANA governance proposal calls the single bound `ProviderLSTFactory` with one
encoded registration. Successful execution creates a branded token and isolated
Vault, FIFO redemption queue, reward distributor, recipient registry, eligible
position registry, timelock, 2-of-3 stake controller and validator strategy policy.
The factory uses pinned implementations, completes reciprocal wiring, installs
the approved timelock delay and relinquishes bootstrap roles in one transaction.
Only then is the instance added to the on-chain directory.

It does not transfer another provider's funds, delegate native stake, claim live
rewards, start servers, supply AMM liquidity or authorize arbitrary governance
calls. Each token mints against its own native principal at 1:1. Rewards are
separate distributions; they never change the principal redemption rate.

## Registration in the UI

Open **LaunchPad > Launch your provider LST**. Connect a wallet associated with
your infrastructure and select **Verify connected wallet**. The app discovers
entities and their registered validators from the network's EntityManager,
resolved through Flare's canonical contract registry. Select the entity to use.
Accepted wallets are the entity identity itself or its currently confirmed
delegation, submit, submit-signatures or signing-policy address. Do not move an
operational key into a browser just to register; use your existing supported
wallet signing setup or another confirmed associated wallet.

Verification and governance eligibility are separate. A verified infrastructure
wallet can upload branding and authorize a launch without MANA proposal power.
After authorization, a separate proposal-eligible wallet may submit the exact
configuration. Voting eligibility comes from the Governor's configured
historical MANA voting sources. Existing escrow/staking sources can be reused
without withdrawing or migrating those positions.
Neither step requires sharing a wallet key with Forge.

### What infrastructure verification establishes

The deployed factory's `identityModel()` must equal
`keccak256("FLARE_ENTITY_PROVIDER_V1")`. Its verifier uses the canonical registry
at `0xaD67FE66660Fb8dFE9d6b1b4240d8650e30F6019` to resolve EntityManager on the
selected chain. No applicant-supplied registry, server-issued badge or wallet
self-match substitutes for that check. EntityManager's reverse-address lookups
may return the input address for an unregistered wallet; discovery filters those
through confirmed forward associations and registered node ownership.

Every proposed NodeID must be registered to the selected entity. The factory
checks the exact CB58 NodeID hashes, current forward wallet association and each
node's reverse ownership. This establishes an infrastructure association, not
brand ownership, an active validator term, capacity, BLS proof validity, uptime
or future rewards. Governance still reviews the application and the provider's
staking services still check native network eligibility before committing funds.

`authorizeProviderRegistration(encoded, entity)` records the connected wallet's
consent to the exact chain/factory/template-bound configuration hash. Editing
branding, node registrations, roles, timing or operations manifest requires new
consent. At governance execution the factory rechecks current associations and
node ownership; a removed wallet or transferred node cannot rely on stale
verification. The authorizing wallet or entity identity may revoke consent with
`revokeProviderRegistration(configHash)` before deployment. Another linked wallet
cannot overwrite an existing authorization. After execution, `launchEntity(token)`
records the verified entity at launch. Later identity changes do not silently
change the LST's operational roles, freeze holder funds or transfer administration.

References: [EntityManager interface](https://dev.flare.network/network/fsp/solidity-reference/IEntityManager),
[official implementation](https://github.com/flare-foundation/flare-smart-contracts-v2/blob/main/contracts/protocol/implementation/EntityManager.sol).

Fill the identity section:

| Input | Meaning |
| --- | --- |
| Provider name | Infrastructure brand shown in the provider selector and proposal. |
| Unique identifier | Lowercase slug; its UTF-8 keccak256 hash is the on-chain provider ID. |
| Description | Plain-text explanation of the infrastructure, service and provider responsibilities. |
| Token name and symbol | ERC-20 branding, checked against the existing token-directory display format. Symbols are unique within the factory, case-insensitively. |
| Documentation URL | Optional public HTTPS operating-policy reference. It is not an upload destination or credential field. |
| Uploaded logo | PNG, JPEG or WebP converted by the browser into a static PNG. The exact PNG hash is committed in the proposal and registry. |

The logo's upload signature binds the site origin, chain, exact image hash and a
five-minute expiry. It cannot approve tokens or move funds. The upload service
checks current infrastructure or proposal eligibility and supports EOA and ERC-1271 verification.
The image is public; do not upload confidential material. The server accepts
bounded PNG chunks only, verifies their checksums, rejects executable/unsupported
content, and serves only hash-matched PNG bytes with non-executable MIME headers.
The hash makes replacement detectable; it does not promise indefinite hosting.
Retain a copy of the normalized PNG and public registration for independent backup.

Providers choose their own operating systems and wallet layout. An independent
launch uses a provider-owner public address; it does not require seven wallets,
three watchers or a Forge rewards root poster. The owner administers that
provider's contracts, not Forge governance. It may be a compatible multisig.

The optional bundled modules expose these roles when a provider chooses them:

| Role | Authority |
| --- | --- |
| Provider owner | Administers its own LST through its own timelock; has no Forge governance authority from this role. |
| Guardian | Emergency Vault pause authority. |
| Rewards root poster | Posts the provider's calculated allocations, subject to funding and challenge controls. |
| Custody | C-chain identity of the provider's native C/P-chain custody; principal and rewards must return through the instance's Vault. |
| Watchers 1-3 | Independent controller signers. Two approve each exact typed action. |

The app discovers the connected wallet's infrastructure association through
EntityManager. Independent launches require no manual validator selection or BLS
fields. A discovered NodeID is included only as evidence for the factory's
identity check, not as a restriction on staking destinations. When using the supplied native
staking modules, configure the 48-byte BLS public key, 96-byte proof
of possession and network delegation fee in basis points. The NodeID and exact
BLS/fee registration are hashed into the policy. This fee field describes the
native validator registration, not a new platform fee. Never enter a BLS private
key, seed phrase, C/P-chain private key, password or populated secret configuration.
The factory commits to public registration bytes; it does not certify native
validator availability, proof validity or current capacity. The staking executor
must independently verify those before posting stake.

For providers selecting the bundled reward service, its configuration includes
the provider-controlled constructor
or initialization dial: timelock delay, pause lifetime, backing-divergence
threshold/grace, minimum redemption in wei, snapshots per epoch, claim/challenge
windows, challenge buffer, posting deadline and random-round offset/search window.
Durations are seconds. The minimum redemption is not an upper withdrawal cap.
The challenge window must cover the timelock plus its buffer. The random offset
must be at least two; its search window is limited by the distributor to 64 rounds.
Choose snapshot settings consistent with the distribution service; its default
configuration requires an odd snapshot count for median weighting. Do not reuse
short test timings as an unreviewed production policy.

Network-owned system addresses and network staking minima are pinned by the
factory deployment, not editable by applicants. Providers choose their own
staking terms and distribution systems within actual network constraints.
HP Mana's supplied strategy uses 60-day self-bonds targeting 20 million FLR per
NodeID and 14-day delegations staggered weekly; adoption is optional.
Returned liquidity serves unfunded FIFO redemptions before any new stake. Actual
network capacity, stake minima, validator terms, recovery time and liquidity still
apply; weekly maturity is not a guaranteed seven-day exit.

Select **Upload logo & review registration**. The app encodes the exact tuple,
calls `factory.validate`, uploads the signed image and displays every approved
input plus the chain/factory-bound configuration hash. Download the public JSON.
Its exact UTF-8 bytes hash to `operationsConfigHash`; that field is intentionally
omitted from the JSON itself to avoid a circular hash. Keep the original bytes,
not merely a reserialized copy. The JSON includes the unhashed public node data
needed to reconstruct the policy commitments.

Select **Authorize this launch** and confirm the factory transaction with the
verified wallet. This grants consent to deploy the reviewed configuration, not
permission to move tokens or spend native principal. Keep the public manifest and
configuration hash. Then submit the proposal with a proposal-eligible wallet,
switching wallets if necessary without editing the reviewed form. The form's
**Revoke launch authorization** action remains available after proposal submission.
After a reload, the authorizing wallet or entity can call the factory's
`revokeProviderRegistration(configHash)` using the saved hash.

The proposal still requires the Governor's voting delay, successful
vote/quorum and execution. Voting times are read from the actual Governor.
Execution uses the target, values, calldata and description hash from the exact
proposal; a provider proposal must never be rerouted to the pool-creation target.
The proposal displays the provider description, symbol, image and encoded settings.

## Discovering and using approved instances

Reload the LST page to load factory records. The app checks the factory/Governor
binding, on-chain registration, token metadata and canonical PairFactory lookup.
Select the provider without pasting addresses. A selection causes a document
navigation with `?lst=<registered token>` so all mint/redemption/reward contracts
remain fixed for that document's lifetime. An unknown or mismatched requested
token stops loading instead of silently minting hpFLR. Failure to discover extra
providers does not remove the original hpFLR application.

Provider tokens enter the token directory with their approved name, symbol and
content-addressed logo. A real registered stable WFLR pool can be discovered;
this does not manufacture reserves or bypass oracle protection. A provider's
market still needs approved pool/oracle wiring and real liquidity before it can
produce an executable protected swap. Once that wiring exists, the backend and
Pages route engines discover the registered provider token automatically; no
static token-list edit is needed. Both directional aggregator policies, nonzero
token feed mappings, and the pool's own guard must exist. Discovery is bounded
and cached for 15 seconds; its failure preserves previously configured markets.
Reload after market setup to refresh the browser directory. Provider-specific public claim artifacts
use `rewards/providers/<lowercase token address>/`, keeping them separate from the
initial hpFLR artifacts. Merkle proofs must match that provider's distributor.
The browser checks each provider artifact's chain, token, Vault, queue and
distributor, recomputes its content commitment, and verifies the connected
holder's Merkle proof before exposing a claim. Missing or invalid proofs show a
triggered availability/verification message, not a presumed zero allocation.
Changing accounts discards pending reward responses for the previous account.

### Protected pool activation

Provider approval intentionally does not grant the provider permission to edit
platform-wide oracle policy. Pool creation continues through the existing
Governance/Propose Pool workflow, including the pool's approved FTSO delegation
configuration. Once its real stable provider-LST/WFLR pair exists, the existing
administrators configure the following through their normal authorized accounts:

| Contract authority | Required call/check |
| --- | --- |
| FTSOPriceOracle owner | `setTokenFeedId(providerToken, FLR_USD_FEED_ID)`; confirm the feed against the approved native/WFLR mapping. Provider principal is 1:1, with rewards separate. |
| PairFactory fee manager | Confirm `swapPriceOracle` is the approved oracle, then `setPairOraclePolicy(pair, reviewedDeviationBips)`. Do not replace a live global oracle just to activate one provider. |
| ForgeDexAggregator owner | `setOraclePairPolicy(providerToken, WFLR, reviewedDeviationBips)` and the reverse direction. Check that `priceOracle()` is the same approved oracle. |
| Liquidity suppliers | Add actual tokens through the existing LP selection UI. A registered empty pool cannot produce an executable quote. |

Use the deployment's reviewed price-deviation policy, not an applicant-chosen
exception. The app checks current feed freshness and execution bounds at quote
and contract execution; a directory entry is not a price or solvency guarantee.
Pool activation is distinct from the provider's governed eligible-position
registration for reward attribution described below.

## Provider-operated services

Canonical source is `hpflr-main/`, not a separate independently maintained copy of
the contracts. The distribution service is
`apps/reward-snapshot-distributor`; shared calculators live in
`ops/allocation-calculator`, `ops/epoch-calculator`, `ops/eligible-positions`,
`ops/reward-claim-check`, `ops/reconcile` and `ops/lib`.
Watchers and typed execution live in `ops/stake-automation` and use
`ops/flare-tx`. Preserve this repository layout: the applications import shared
operations code by relative path.

Approved providers should receive access to a reviewed, pinned source repository
or a source-only export of those components with their lockfiles, tests and
runbooks. **A separate distribution repository has not been published by this
implementation.** Never copy `.keys`, populated `.env` files, journals, node_modules,
private deployment material or custody bundles into a provider repository.

The local source-only handoff is now generated with
`node scripts/export-provider-rewards.js --output /tmp/provider-rewards.tar.gz`
from Forge. See `docs/PROVIDER-REWARDS-KIT.md`. The exporter uses an explicit file
allowlist, rejects symlinks/overwrites, preserves imports and lockfiles, and
includes an independently runnable verifier and fixture tests. It does not
publish a repository, change access permissions or put service source on Pages.
The archive checksum must be delivered through a trusted handoff. A local export
is not a clean committed release; pin the reviewed source before operating it.

Each provider must:

1. Record its factory event, token and all instance addresses; verify runtime and
   EIP-1967 implementation hashes, reciprocal bindings, final roles and timelock.
   Do not substitute hpFLR's original addresses in a new brand's service settings.
2. Reconstruct the public registration hashes and verify the real native NodeID,
   public BLS registration, term, capacity, reward owner and network limits.
3. Place three watcher configurations on separate machines. Install dependencies
   from pinned lockfiles, keep secrets outside source with owner-only permissions,
   and begin in read-only observation. Require agreement on the exact operation ID
   before enabling approvals. Use separate relayer and custody processes.
4. Supply transaction fees separately from holder principal. Do not pay operational
   gas by reducing 1:1 redemption amounts. Reconcile C/P/atomic-UTXO state and the
   mirrored ledger before confirming or returning any lot.
5. Configure its distribution service with its token, Vault, queue, distributor,
   registries, timelock, archive RPC and independent fallback. Start in `observe`,
   then `calculate`; only enable `post` with the correct encrypted root-poster
   keystore after independent outputs match.
6. Resolve canonical Flare epochs and finalized boundaries. Commit randomness,
   derive snapshots, attribute holders/approved LP positions and calculate median
   effective exposure. Never invent epoch IDs or replace missing archive history
   with current balances. Register governed LP/gauge/vault adapters before their
   activation epochs; end users do not need registration.
7. Claim through the approved native reward manager/controller/Vault path and
   recognize only the measured native balance increase. Both reward executor and
   recipient authorizations must be correct. Fund the oldest eligible epoch;
   principal and reward earmarks remain separate.
   Leave the distribution service's `AUTO_CLAIM_VALIDATOR_REWARDS=false` for
   controller-only factory instances: their claims must use the typed controller,
   not the service's legacy direct-Vault claim path.
8. Independently verify root, allocation sum, funding, artifact hash, exclusions
   and position policy. Publish immutable proof artifacts to the provider's
   public artifact directory and sync that directory to the app's agreed public
   path. Public hosting carries proofs, never signing credentials.
9. Monitor the challenge period. Correct a bad root through its permitted
   timelocked path before claims begin; after claims start that epoch's root
   cannot simply be replaced. Claims pay native rewards or mint matching 1:1 LST
   principal when restaked. Reconcile after claims and rollover.
10. Retain recoverable public artifacts and operational journals. On an outage,
    resume from canonical history; do not restart with guessed balances. Stop
    new exposure on disagreement and follow the documented recovery/incident
    workflow. Two healthy watchers may replace the third, advancing signer epoch
    and invalidating prior approvals.

Read the canonical service README, `ops/stake-automation/README.md`, and deployment,
queue, custody, epoch and incident runbooks for command interfaces. Some older
manual runbook examples predate the controller and show raw-key command options;
do not copy those examples into production automation. Use the encrypted-keystore
service interfaces and controller-only OPS wiring described above.

The native complete-key custody limitation remains explicit: an EVM multisig or
2-of-3 controller does not cryptographically protect a stolen complete native
P-chain key. The threshold-custody lab is not the production signing integration.
Provider approval does not transfer this custody responsibility to the platform.

## Provider logo publication

Provider registration uploads a bounded, validated raster image. Its byte hash is
committed by the proposal and used for content-addressed retrieval. Descriptions
are rendered as text; providers never submit executable branding content.

The publication service requires configured public-image storage before uploads
can succeed. It stores branding, not wallets or user secrets. The original hpFLR
interface can operate without provider-logo storage. An unavailable upload is
reported at the registration action; it does not create a usable proposal image.

Service operators configure the PROVIDER_LOGOS binding using the deployment
runbook, keep test and production storage separate, and maintain backups and
upload monitoring. Providers should retain their exact submitted logo and public
manifest. No storage or wallet credentials belong in a proposal or browser form.

## Acceptance boundary

The identity-enforcing factory is a new deployment, not an upgrade to existing
provider contracts. Deployment must configure the frontend's provider factory and
bind it reciprocally to its Governor. The existing Governor binds its factory
only once; do not try to overwrite a live binding. A previously bound deployment
needs a separately reviewed governance deployment/transition. See
[the continuity plan](PROVIDER-GOVERNANCE-CONTINUITY.md) for preserving existing
positions and predecessor proposal execution. Existing LSTs and
their holders are not migrated or modified by this registration work.

The local tests execute real MANA proposals against full canonical provider
stacks, verify branding and zero bootstrap authority, and exercise isolated
mint/FIFO funding/claim accounting. Logo tests verify raster validation,
signature domain/expiry, eligibility and hash-matched serving. These results do
not establish live validator eligibility, mainnet custody, deployed branding
storage or fully configured provider swap markets. Record those independently;
do not present an empty pool or missing proof artifact as a working route/claim.
