# Blessed: direct contract calls

Use this guide to inspect a coin and prepare calls with an Ethereum RPC client, an explorer, Foundry or a wallet. The public deployment response includes the ABI; the restricted project SDK is optional. Let the user review and sign in their own wallet. Do not request their key, seed phrase or a reusable signed transaction.

The current website features and lists operator-selected coins, currently BLESSED only. A deployment record or a successful creation transaction does not guarantee website listing. This guide is for inspecting existing coins and preparing available actions; it does not announce that public self-service launches are open. On-chain permissions and existing claims follow the deployed contracts.

## 1. Identify the deployment

The production reference is:

| Field | Value |
|---|---|
| Chain | Robinhood Chain mainnet, chain ID 4663 (`0x1237`) |
| Gas | ETH |
| Factory | `0xa0fbee2787355f988ebd93efc982fa31a904c45f` |
| Official first coin | BLESSED, coin ID `0`, target ESRT |

Check `eth_chainId` on the RPC and the wallet. Testnet 46630 and the old pilot use different contracts. Do not reuse their addresses, ABI or approvals.

Fetch the published record, checking the HTTP status before parsing it:

```sh
curl --fail --silent --show-error 'https://www.getblessed.fun/api/deployments?factory=0xa0fbee2787355f988ebd93efc982fa31a904c45f&coinId=0'
```

The response has `chainId`, `factory`, `coinId` and `input`. Parse `input.manifestJson` and `input.abiJson` as JSON strings. Contract addresses are in `manifest.coin.contracts[role].address`; ABI arrays are in `bundle.contracts[contractName]`, without an extra `.abi` field. For example, use `GenesisBond` for the address and `UmbrellaV4GenesisBond` for its ABI. `manifest.platform.input.usdg` is the USDG address.

The exact manifest text's SHA-256 must match an independently trusted or previously saved manifest hash. `input.expectedManifestSha256`, served in the same response, is only a consistency reference: comparing two fields from the same untrusted server does not independently authenticate it. The manifest also pins the ABI text's SHA-256 in `abiSha256`. Preserve the original strings; parsing and serializing JSON changes their bytes.

At a fresh fixed block, compare chain ID, factory registry record, contract addresses and code with the trusted record, and recheck that block's hash. Runtime code hashes use keccak256, unlike the manifest and ABI text's SHA-256. `factory.coin(id).coin` has these indices:

| Index | Role | ABI entry |
|---|---|---|
| 0 | Token | UmbrellaV4Token |
| 1 | Treasury | UmbrellaV4Treasury |
| 2 | StockReserve | StockReserve |
| 3 | GenesisBond | UmbrellaV4GenesisBond |
| 6 | Hook | UmbrellaV4Hook |
| 7 | RewardBudget | RewardBudget |
| 8 | BondDepository | UmbrellaV4BondDepository |
| 10 | InverseBond | InverseBond |

The full record has more fields. Decode it with the published LaunchFactory ABI rather than guessing its length. Proxy runtime alone does not identify the implementation: check the manifest's beacon and implementation pins too. A same-name token, an arbitrary router or a caller-supplied manifest is not the production coin.

## 2. Amounts and the execution account

USDG amounts use 6 decimals: 10 USDG is `10000000`. Coin amounts use 9 decimals: 1 BLESSED is `1000000000`. Prices and fields named `Wad` use 18 decimals. Use integer arithmetic, not floating-point numbers.

Read balances, allowances and rights for the account that will actually call the contract. If a Safe is the caller, use the Safe's address, not a signer EOA. The account needs ETH for gas unless its own wallet provides another payment mechanism. An allowance is not a purchase.

## 3. Buy in Genesis

Read `saleTerms()`, `saleStart()`, `saleDeadline()`, `saleState()`, `finalized()`, `raisedRaw()`, `purchasedRaw(account)`, `whitelistEnabled()`, and the caller's USDG `balanceOf` and `allowance(account, genesis)` at the same block. Check the saved sale terms, remaining hard cap, remaining per-account cap, deadline and any stop condition. `saleState() == 0` alone is insufficient: Active also includes a sale awaiting finalization, when purchases may be closed.

The following are function signatures, not instructions to broadcast automatically:

```solidity
// On USDG, only when the existing allowance is insufficient:
approve(address spender, uint256 amount)
// On the coin's GenesisBond:
purchase(uint256 usdgAmountRaw, bytes32 root, bytes32[] proof)
```

Use the verified GenesisBond as spender and the exact amount the user approved. If whitelisting is disabled, root is bytes32(0) and proof is an empty array. Otherwise obtain the valid root and proof for the execution account; do not invent them.

Approval and purchase are separate transactions on the normal direct-wallet path. Wait for a successful approval receipt, read the resulting allowance and current sale state, then simulate the exact purchase with `eth_call` from that same account. A wallet estimate does not replace simulation. Ask for the purchase signature only after simulation succeeds and the user has checked amount, destination, chain and gas. A supported smart account may assemble its own atomic batch; do not assume every wallet or the hosted app supports that path.

Wait for a successful receipt and check the GenesisBond's `Purchased` event for the actual purchaser. Its `usdgWad` uses 18 decimals, while the purchase input uses 6. Afterward re-read `purchasedRaw(account)` and balances. If the wallet response is lost or a transaction is unresolved, inspect wallet activity, nonce and receipts before trying again; a timeout is not proof that nothing was sent.

## 4. Claim or refund

Call from the address that purchased, using the coin's GenesisBond ABI:

```solidity
claim()
refund()
finalize()
```

`claim()` requires successful finalization and a positive unlocked amount; read `claimableUmbrellaOf(account)` first. It does not require a token approval. `refund()` is for a failed or terminal-refund sale, not a cancellation of an active purchase. Refunds depend on the sale outcome and fee rules; do not assume every failure refunds the gross payment. `finalize()` is public but only succeeds when the contract's timing and minimum-raise conditions permit it. Simulate each call from its real caller and verify its receipt.

## 5. Trading, discounted buys and Treasury exits

These become available only when the coin and the relevant market are ready. Do not reuse Genesis purchase calldata for them.

| Operation | Destination and signature |
|---|---|
| Market buy or sell | The factory's verified SharedUserSwapRouter: `swap(uint256 coinId,bool buy,uint256 amountIn,uint256 minOut,uint256 maxTaxBps,uint256 deadline)`. Where none is deployed (testnet), the coin's verified UserSwapRouter: the same arguments without `coinId` |
| Discounted buy | BondDepository: `deposit(uint256 marketId,uint256 amount,uint256 maxPriceWad,address to,uint64 expectedPremiumVersion,uint64 expectedConfigVersion)` |
| Collect vested discounted-buy tokens | BondDepository: `redeem(address to)` or `redeem(address to,uint256[] noteIds)` |
| Sell tokens to the Treasury | InverseBond: `swap(uint256 umbrellaAmount,uint256 minUsdgOutRaw)` |
| Redeem after an eligible wind-down | Treasury: `redeemWindDown(uint256 amount,uint256 minOut,bool inKind)` |

For a market buy approve USDG to the verified router; for a market sell approve the coin token to that router. The shared router serves every coin of the factory, so an approval to it can be spent on any of them, and a factory or Hook upgrade (48-hour timelock) can change where it is spent: approve only the amount of the swap. USDG input/output has 6 decimals and token input/output has 9. The router is separate from the 13 coin contracts and its ABI is not in the coin ABI bundle. `quote` has the same arguments as `swap` and returns the output amount; call it with `eth_call` only. It deliberately does not prove the caller's balance or allowance, so simulate `swap` as well. Choose nonzero minimum output, maximum tax and a deadline based on the current quote and user limits.

When available, `POST /api/trade/quote` accepts `factory`, `coinId`, `account`, `buy`, `amountRaw` and integer `slippageBps` in a JSON body. Its `route` identifies the CREATE2 router. Verify the route's chain/factory/coin, code and getters against the trusted deployment before approving it: `factory`, `manager`, `usdg` on the shared router; also `coinId`, `token`, `hook`, `poolId` on a coin's router. This endpoint only quotes: it does not sign or submit. A 503 can mean trading is not available. Do not send tokens directly to a Hook or substitute the StockRouter, which serves stock-reserve purchases.

For that quote request, `coinId` and `amountRaw` are decimal strings, `buy` is a JSON boolean and `slippageBps` is an integer from 0 to 9999. Supply the actual public execution address as `account`.

For a discounted buy, approve USDG to BondDepository, use market ID 0, set `to` to the execution account and read the current premium/config versions. For an InverseBond exit, approve the coin token to InverseBond and check price, capacity, oracle freshness and the minimum output. A wind-down is a distinct state: inspect the live Treasury/Reserve views and the published rules before choosing USDG versus in-kind repayment. The official BLESSED reserve is excluded from the 90-day no-stock-purchase wind-down.

## 6. Working with an assistant

Give the assistant this guide, the chain/factory/coin ID, your public execution address, the action and your amount/slippage limits. Ask it to return the exact target, value, decoded method and arguments, calldata, quote block/hash and simulation result for review. Do not infer transaction authorization from a chat message or a quote. Sign only in your own wallet and keep the resulting transaction hash.

Read-only discovery and history are described in [the read API guide](/read-api.md). Contract state and confirmed receipt events decide rights and execution, not a search result, screenshot or stored snapshot.
