# Network identity and client configuration

Wallets, the explorer and marketplace clients require an independently approved
`grc-network-identity/v1` document. An EVM chain ID alone cannot distinguish two
networks that use the same ID. Do not populate this document from the RPC server
that the client is about to trust.

## Identity fields

| Field | Meaning |
| --- | --- |
| `evmChainId` | Positive canonical decimal string. Wallet builds/signing support `1` through `18446744073709551615` (uint64), derived from this approved document. |
| `cosmosChainId` | Exact Cosmos network identifier from the original approved genesis. |
| `genesisFileSha256` | SHA-256 of the original genesis file's exact bytes: 64 lowercase hexadecimal characters, without `0x`. |
| `hybridGenesisFingerprint` | The node's canonical original `app_state` fingerprint, with `0x`. This is a different hash from the whole-file SHA-256. |
| `evmAnchor.number`, `.hash` | A positive EVM block height and its approved block hash. Height zero is unsupported because Cosmos EVM can alias it to height one. |

The document also requires `schema: "grc-network-identity/v1"`. Hashes cannot be
all zero; unknown fields, noncanonical integers and incomplete documents fail.
See the shared [protocol](../platform/packages/network-protocol/README.md) for
the exact format and error codes.

## Establish the approved values

Use the original genesis and an approved node binary. Keep node commands inside
an explicit private home; exported current state is not the original genesis.

```sh
sha256sum /approved/original-genesis.json
./chain/build/grcd genesis hybrid-fingerprint \
  /approved/original-genesis.json --home /private/node-home
```

Approve the positive EVM anchor against independently trusted chain data and
record the deployment/network to which it belongs. Do not substitute a genesis
file digest or hybrid fingerprint for an EVM block hash. The local hybrid test
parent owns its initialized genesis, node and listeners and correlates block one
with Comet; that is a development fixture, not an approval of a public network.

## Wallet builds

Provide both the approved file and its independently recorded digest:

```sh
export GRC_NETWORK_IDENTITY_FILE=/approved/network-identity.json
export GRC_NETWORK_IDENTITY_SHA256=APPROVED_64_LOWERCASE_HEX_DIGEST
cd apps/wallet-web
npm ci --no-fund --no-audit
npm run build
```

The common Vite configuration embeds the validated identity in Web, Desktop and
Android assets. Changing an RPC URL does not change this pin. Without a document,
builds remain available for offline custody and backup use; network operations
fail with `NETWORK_IDENTITY_REQUIRED`. Supplying only one build variable fails.
The four wallet devnet E2Es use the same approved-file variables. The wallet
uses bigint for signing and reward checks; do not convert large IDs to JavaScript
Number. Optional Marketplace ID aliases accept canonical strings, bigints or
positive safe integer numbers; unsafe rounded numbers fail even if they happen
to match an identity. `42801` remains the local development ID and is refused by
the public-testnet manifest. Generic ID support selects no public parameters.

Older native packages contain their original Core and local identity. Rebuild
and separately accept each target for the approved public identity. The
reward-relayer server requires its own independently approved
`GRC_REWARD_RELAYER_NETWORK_IDENTITY_FILE` and
`GRC_REWARD_RELAYER_NETWORK_IDENTITY_SHA256`. It checks the same provider and
positive anchor around signing, broadcast, cached replies and recovery. Budget
v2 binds the complete approved identity; legacy v1 remains inspection-only
until a separately reviewed accounting migration. See the
[relayer operations guide](../platform/services/reward-relayer/README.md).
This implementation does not approve a funded signer or public operation.

[Wallet UI preview](screenshots/approved-chain-id-fixture.png) shows a locally
built Web client with the unapproved synthetic ID `9007199254740993`, a public
test account and mocked read-only RPC. It demonstrates exact ID display, with
no public network, native package, transaction or service-worker acceptance.

## Explorer and marketplace

Explorer configuration requires `networkIdentity`; an optional `chainId` must
equal its `evmChainId`. Marketplace clients and indexers receive the same explicit
document. A catalogue response or wallet link is compared with that expected
identity and cannot establish a new approved pin. A marketplace database from an
older configuration must be rebuilt in a new location; never silently adopt it.
See [marketplace integration](../marketplace/docs/game-integration.md) for callers.

## Verification limits

EVM consumers check chain ID and the positive anchor before and after reads.
Wallet signing rechecks before signing and before broadcast; changing the wallet
session or configured network invalidates pending work. Once an RPC broadcast
starts, an already submitted transaction cannot be recalled.

The EVM check does **not** independently validate Cosmos identity, either genesis
digest, finality, or RPC honesty. `assertCosmosNetworkIdentity` separately checks
a supplied Comet status; the explorer currently reports its Cosmos/validator view
as unavailable. RPC assertions are not a light-client proof. Public network
parameters, operator approval, complete deployment registers and ECO-005/006/017
production acceptance remain open.

## Local runtime acceptance

After building the pinned node/miner and compiling the production contracts,
`npm run test:hybrid:network-products` starts its own checked-free local node,
computes the original genesis fingerprint, binds a positive Comet/EVM anchor and
passes the exact approved file/digest to wallet and browser NFT flows. This
bounded subset tests native transfer and real browser marketplace purchase on
hybrid blocks. The full product/governance and four-validator suites remain
separate; none of these commands approves a public network.


`npm run test:hybrid:reward-services` runs the four focused wallet flows: native
transfer, staking, governance and sponsored rewards. These public-key fixtures
require the exact local ID `42801`, a literal loopback HTTP RPC, and the approved
file/digest before key derivation or contract deployment. The existing network
signer checks again before signing and broadcast. Node state uses an explicit
private temporary directory; HOME and XDG variables are inherited unchanged.

The reward flow also exercises a real claim with receipt visibility deliberately
hidden until the unchanged 60-second relayer timeout. Its separate fresh v2
journal must retain the known-hash hold across restart and snapshot/restore,
then settle canonical gas costs exactly once without another broadcast. This
controlled transport fault is not a crash test or public-network approval.