# PART 2: Developer Forge & AI Front-End Programming Reference

# chainWare v11 — AI Front-End Programming Reference

Purpose: machine-readable handoff for an AI/code assistant building browser or application front ends against the current chainWare v11 L1/L2 application and its public CometBFT RPC proxy.

Source basis:
- chainWare v11 application source (`~/chainWare-v11/app/main.go`) captured from the running project.
- Public validator RPC is exposed through `/chainware-rpc`.
- CometBFT RPC transport is JSON-RPC 2.0.
- Application queries are performed with CometBFT `abci_query`.
- Signed transactions are submitted through CometBFT `broadcast_tx_commit`.

IMPORTANT:
- This file distinguishes IMPLEMENTED calls from RESERVED / FAIL-CLOSED calls.
- Do not assume a transaction is usable merely because it appears in `/capabilities`.
- Current source explicitly makes L1 `SETTLE` and L2 `STORAGE_CREDIT` fail closed because cross-layer inclusion-proof verification is not yet installed.
- Creator initialization is special and differs from ordinary signed transactions.
- After Creator initialization, signed transactions must include `gas`.

---

## 1. Network architecture

chainWare is split into two chains:

### Layer 1
Settlement / consensus / native coin / wallet / escrow / pointers.

Current L1 application transaction types:

- `CREATOR_INIT_L1`
- `REGISTER_WALLET`
- `TRANSFER`
- `STORAGE_FUND`
- `L2_POINTER`
- `ESCROW`
- `SIGNAL`
- `SETTLE` — RESERVED / FAIL-CLOSED CURRENTLY

### Layer 2
Content / storage.

Current L2 application transaction types:

- `CREATOR_INIT_L2`
- `STORE`
- `DELETE`
- `SIGNAL`
- `STORAGE_CREDIT` — RESERVED / FAIL-CLOSED CURRENTLY

---

## 2. Public validator URLs

A validator normally exposes these public HTTPS resources:

```text
https://<validator-domain>/chainware-rpc
https://<validator-domain>/chainware-rpc/<comet-method>
https://<validator-domain>/chainware-status
https://<validator-domain>/validator
https://<validator-domain>/genesis.json
https://<validator-domain>/chainware-bootstrap.json
```

The main front-end API base is:

```text
https://<validator-domain>/chainware-rpc
```

The proxy accepts:

```text
GET
POST
OPTIONS
```

and is intended to expose CometBFT RPC with CORS enabled.

---

## 3. JSON-RPC transport

POST JSON-RPC requests to:

```text
https://<validator-domain>/chainware-rpc
```

Basic request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "status",
  "params": {}
}
```

JavaScript helper:

```js
async function rpc(rpcBase, method, params = {}) {
  const response = await fetch(rpcBase, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: Date.now(),
      method,
      params
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  const decoded = await response.json();

  if (decoded.error) {
    const message = decoded.error.message || "RPC error";
    const detail =
      typeof decoded.error.data === "string"
        ? decoded.error.data
        : decoded.error.data
          ? JSON.stringify(decoded.error.data)
          : "";

    throw new Error(detail && detail !== message ? `${message}: ${detail}` : message);
  }

  return decoded.result;
}
```

---

## 4. Application query transport

All chainWare application query paths are sent through CometBFT:

```text
method: abci_query
```

with:

```json
{
  "path": "/state",
  "data": "",
  "prove": false
}
```

The returned application value is base64-encoded JSON.

JavaScript helper:

```js
const textDecoder = new TextDecoder();

function base64ToBytes(value) {
  const raw = atob(value);
  const bytes = new Uint8Array(raw.length);

  for (let i = 0; i < raw.length; i += 1) {
    bytes[i] = raw.charCodeAt(i);
  }

  return bytes;
}

async function chainQuery(rpcBase, path) {
  const result = await rpc(rpcBase, "abci_query", {
    path,
    data: "",
    prove: false
  });

  const response = result?.response || {};

  if (Number(response.code || 0) !== 0) {
    throw new Error(response.log || `Query failed: ${path}`);
  }

  if (!response.value) {
    return null;
  }

  return JSON.parse(
    textDecoder.decode(base64ToBytes(response.value))
  );
}
```

---

# 5. COMPLETE CURRENT APPLICATION QUERY PATHS

The following paths are defined by the current v11 `queryState()` switch.

## 5.1 `/state`

Works on L1 and L2.

```text
/state
```

Returns chain-level application state summary.

Current response fields:

```json
{
  "AppVersion": 1,
  "Layer": "layer-1 or layer-2",
  "ChainID": "string",
  "Height": 0,
  "Initialized": true,
  "CreatorInitialized": true,
  "CreatorManifestHash": "string",
  "CreatorTxHash": "string",
  "CreatorTxHeight": 0,
  "Denomination": "string",
  "Decimals": 12,
  "CoinCap": "string",
  "TreasurySupply": "string",
  "L1CreatorTxHash": "string",
  "L1CreatorHeight": 0,
  "BootstrapBudgetID": "string",
  "BootstrapRewardPerWallet": "string",
  "BootstrapEligibleWallets": 0,
  "BootstrapRewardedWallets": 0,
  "BootstrapBudgetRemaining": "string",
  "BootstrapReconciliationRequired": false,
  "TxCount": 0
}
```

NOTE:
Some older front-end code may look for lowercase aliases such as `chain_id`, `height`, or embedded `accounts`. Do not depend on those unless verified against the currently running release. Prefer the explicit v11 query endpoints below.

---

## 5.2 `/capabilities`

```text
/capabilities
```

Returns runtime capability metadata.

Example shape:

```json
{
  "AppVersion": 1,
  "Layer": "layer-1",
  "ChainID": "l1-11",
  "Initialized": true,
  "CreatorInitialized": true,
  "CreatorMode": "unsigned-one-time-protocol-transaction",
  "CreatorGas": "0",
  "TransactionEnvelopeVersion": 1,
  "TransactionTypes": [
    "CREATOR_INIT_L1",
    "REGISTER_WALLET",
    "TRANSFER",
    "STORAGE_FUND",
    "L2_POINTER",
    "ESCROW",
    "SIGNAL",
    "SETTLE"
  ],
  "MaxTxBytes": 524288
}
```

L2 reports:

```json
[
  "CREATOR_INIT_L2",
  "STORE",
  "DELETE",
  "SIGNAL",
  "STORAGE_CREDIT"
]
```

Front ends SHOULD query `/capabilities` when connecting rather than hard-code assumptions.

---

## 5.3 `/creator`

```text
/creator
```

Response shape:

```json
{
  "initialized": true,
  "manifest_hash": "string",
  "manifest": {},
  "creator_tx_hash": "string",
  "creator_tx_height": 0,
  "l1_creator_tx_hash": "string",
  "l1_creator_height": 0
}
```

Use this to determine whether Creator initialization has already occurred and to retrieve the committed manifest.

---

## 5.4 `/wallet-registration/<walletAddress>`

L1.

```text
/wallet-registration/cw1234...
```

Not registered:

```json
{
  "registered": false,
  "wallet": "cw1234..."
}
```

Registered responses use the wallet-registration record.

Purpose:
- Check whether a wallet has been registered.
- Determine bootstrap reward status.

---

## 5.5 `/bootstrap-budget`

L1.

```text
/bootstrap-budget
```

Response:

```json
{
  "id": "protocol:budget:initial-bootstrap",
  "reward_per_wallet": "integer base units",
  "eligible_wallets": 100,
  "rewarded_wallets": 0,
  "remaining": "integer base units",
  "reconciliation_required": true
}
```

Use this for bootstrap-budget / initial-wallet-reward UI.

---

## 5.6 `/storage-funding/<transactionHash>`

L1.

```text
/storage-funding/<L1_TX_HASH>
```

Looks up one storage-funding record by transaction hash.

Known fields include:

```json
{
  "ID": "hash",
  "Wallet": "cw...",
  "L2ChainID": "l2-11",
  "Amount": "integer base units",
  "CreatedHeight": 123,
  "TxHash": "hash",
  "Status": "LOCKED_PENDING_L2_PROOF"
}
```

Exact JSON field casing is determined by the Go struct tags / serializer in the running release. Front ends should inspect a live response before assuming casing.

---

## 5.7 `/storage-fundings`

L1.

```text
/storage-fundings
```

Returns the complete storage-funding map keyed by funding transaction hash.

Useful for:
- storage funding history
- pending cross-layer storage credits
- explorer / diagnostics

---

## 5.8 `/l2-pointers`

L1.

```text
/l2-pointers
```

Returns all currently recorded L1 pointers to L2 transactions.

Each pointer contains conceptually:

```json
{
  "Hash": "L1 pointer tx hash",
  "Signer": "cw...",
  "L2ChainID": "l2-11",
  "L2TxHash": "hash",
  "L2Height": 123,
  "Action": "ACTION_NAME",
  "CreatedHeight": 456
}
```

This is the core read-side bridge for front ends that need to discover L2 content from L1.

---

## 5.9 `/account/<address>`

L1 and usable wherever account state exists.

```text
/account/cw1234...
```

Missing account returns:

```json
{
  "balance": "0",
  "nonce": 0
}
```

Existing account:

```json
{
  "balance": "integer base units",
  "nonce": 7
}
```

IMPORTANT:
Before building a signed transaction, query the signer account and use:

```text
next nonce = current nonce + 1
```

Balances are integer base units, not floating-point values.

---

## 5.10 `/escrow/<escrowID>`

L1.

```text
/escrow/<id>
```

Returns one escrow or an application error if absent.

Escrow shape includes:

```json
{
  "id": "string",
  "creator": "cw...",
  "amount": "string",
  "l2_reference": "string",
  "status": "LOCKED",
  "created_height": 123,
  "payload": {}
}
```

---

## 5.11 `/escrows`

L1.

```text
/escrows
```

Returns the complete escrow map.

Useful for:
- treasury / escrow dashboards
- explorer
- proposal-linked escrow visibility

---

## 5.12 `/content/<key>`

L2.

```text
/content/<key>
```

Returns one stored L2 content record.

Conceptual response:

```json
{
  "Key": "content-key",
  "Owner": "cw...",
  "CreatedHeight": 100,
  "UpdatedHeight": 125,
  "Content": {}
}
```

Only the owner may overwrite or delete the same key.

IMPORTANT:
If keys may contain `/`, percent-encode them or adopt an application-level key convention that does not rely on raw path slashes.

---

## 5.13 `/signals`

L1 and L2.

```text
/signals
```

Returns all signals recorded on that layer.

Signal records conceptually include:

```json
{
  "Hash": "transaction hash",
  "Signer": "cw...",
  "Height": 123,
  "Data": {}
}
```

Signals are generic application messages and may be used by higher-level front ends as an indexing / event convention.

---

# 6. TRANSACTION ENVELOPE

Normal signed transactions use this JSON envelope:

```json
{
  "version": 1,
  "chain_id": "l1-11",
  "type": "TRANSFER",
  "gas": "string",
  "nonce": 1,
  "signer": "cw...",
  "payload": {},
  "public_key": "base64 Ed25519 public key",
  "signature": "base64 Ed25519 signature"
}
```

Fields:

```text
version      uint32
chain_id     string
type         string
gas          string, required after Creator initialization
nonce        uint64
signer       string
payload      JSON
public_key   base64 Ed25519 public key
signature    base64 Ed25519 signature
```

Maximum transaction bytes reported by current app:

```text
524288 bytes
```

---

# 7. WALLET ADDRESS DERIVATION

Current signer verification derives the wallet address from the raw Ed25519 public key:

```text
sha256(publicKeyBytes)
take first 20 bytes of digest
hex encode lowercase
prefix with "cw"
```

Conceptually:

```js
address = "cw" + hex(sha256(publicKeyBytes).slice(0, 20));
```

The transaction is rejected if:

```text
tx.signer != derived address
```

---

# 8. SIGNING DOCUMENT

The signature is NOT made over the complete transaction including the signature itself.

The signed document is:

```json
{
  "version": 1,
  "chain_id": "l1-11",
  "type": "TRANSFER",
  "gas": "string",
  "signer": "cw...",
  "nonce": 1,
  "payload": {},
  "public_key": "base64..."
}
```

Canonical transaction signing rules from the current application:

1. Canonicalize `payload` JSON.
2. Build the signing document using:
   - version
   - chain_id
   - type
   - gas
   - signer
   - nonce
   - canonical payload
   - public_key
3. JSON-serialize the signing document.
4. Sign those bytes with Ed25519.
5. Base64-encode the signature.
6. Insert it into the final transaction envelope.

CRITICAL:
The exact JSON canonicalization and field ordering used by the client must match the chain's implementation. If your friend's AI writes a new signer, it should reproduce the current chainWare canonical-JSON algorithm rather than assume ordinary `JSON.stringify()` is always sufficient.

---

# 9. SUBMITTING A TRANSACTION

The final transaction JSON is serialized to bytes, then base64-encoded and sent with:

```text
broadcast_tx_commit
```

Example JSON-RPC:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "broadcast_tx_commit",
  "params": {
    "tx": "<base64-encoded transaction JSON>"
  }
}
```

JavaScript:

```js
function bytesToBase64(bytes) {
  let raw = "";
  for (const byte of bytes) raw += String.fromCharCode(byte);
  return btoa(raw);
}

async function broadcastTransaction(rpcBase, tx) {
  const bytes = new TextEncoder().encode(JSON.stringify(tx));

  return rpc(rpcBase, "broadcast_tx_commit", {
    tx: bytesToBase64(bytes)
  });
}
```

A front end MUST inspect nonzero result codes.

Possible result sections include:

```text
check_tx
tx_result
deliver_tx
```

If a returned section contains:

```text
code != 0
```

the transaction should be treated as rejected and its `log` displayed.

---

# 10. COMPLETE CURRENT L1 TRANSACTION TYPES

## 10.1 `CREATOR_INIT_L1`

Purpose:
Initialize the Layer 1 chain once from the Creator manifest.

Special behavior:
- one-time protocol transaction
- Creator mode is unsigned
- Creator gas is `0`
- exact Creator payload validation is handled separately from normal transactions

Front ends should normally use `/creator` and `/capabilities` to determine whether this is still available.

Do not expose Creator initialization after the chain is initialized.

---

## 10.2 `REGISTER_WALLET`

L1.

Payload:

```json
{}
```

The signer becomes the wallet being registered.

Effects:
- rejects duplicate registration
- may pay the configured bootstrap reward if the wallet remains within the eligible bootstrap allocation
- creates a wallet-registration record
- updates bootstrap-budget counters

---

## 10.3 `TRANSFER`

L1.

Payload:

```json
{
  "to": "cw...",
  "amount": "1000000000000"
}
```

Requirements:
- `to` is nonempty
- `amount` is a positive integer string
- sender has sufficient balance

NEVER use JavaScript floating-point numbers for native amounts.

Use integer strings / BigInt.

---

## 10.4 `STORAGE_FUND`

L1.

Payload:

```json
{
  "l2_chain_id": "l2-11",
  "amount": "1000000000000"
}
```

Effects:
- subtracts amount from signer
- moves amount into protocol storage escrow address:

```text
protocol:escrow:storage:<l2_chain_id>:<signer>
```

- creates a storage-funding record
- initial status:

```text
LOCKED_PENDING_L2_PROOF
```

Current cross-layer completion is not yet fully enabled because L2 `STORAGE_CREDIT` is fail-closed.

---

## 10.5 `L2_POINTER`

L1.

Payload:

```json
{
  "l2_chain_id": "l2-11",
  "l2_tx_hash": "ABCDEF...",
  "l2_height": 123,
  "action": "POST"
}
```

Requirements:
- l2_chain_id required
- l2_tx_hash required
- l2_height >= 1
- action required
- one L2 transaction may not receive multiple L1 pointers

Use this after the L2 transaction is confirmed when implementing the L2-first / L1-pointer pattern.

---

## 10.6 `ESCROW`

L1.

Payload minimum:

```json
{
  "id": "optional-custom-id",
  "amount": "integer-string",
  "l2_reference": "required-reference"
}
```

If `id` is omitted/empty, the app derives an ID from the transaction hash.

Current creation behavior:
- rejects duplicate escrow IDs
- requires `l2_reference`
- creates escrow status:

```text
LOCKED
```

NOTE:
Current code stores `amount` but the shown execution path does not itself debit the creator balance. Do not infer additional treasury accounting unless verified in the newer escrow/governance code.

---

## 10.7 `SIGNAL`

L1.

Payload:

```json
{
  "any": "JSON payload"
}
```

The app stores the raw payload as a signal record with:
- transaction hash
- signer
- block height
- data

This is a generic extensibility mechanism.

---

## 10.8 `SETTLE`

L1.

STATUS:

```text
NOT CURRENTLY USABLE
FAIL-CLOSED
```

Current application error:

```text
SETTLE fail-closed: Layer 2 inclusion-proof verification is not installed
```

A front end must NOT present this as a functioning settlement operation yet.

---

# 11. COMPLETE CURRENT L2 TRANSACTION TYPES

## 11.1 `CREATOR_INIT_L2`

Purpose:
Initialize the Layer 2 chain once using the Creator manifest and L1 Creator linkage.

Special one-time Creator behavior applies.

---

## 11.2 `STORE`

L2.

Payload:

```json
{
  "key": "content-key",
  "content": {
    "arbitrary": "JSON content"
  }
}
```

Requirements:
- `key` required
- `content` required

Ownership:
- first store establishes the owner as transaction signer
- only the existing owner may overwrite a key

The record preserves original `CreatedHeight` and updates `UpdatedHeight`.

---

## 11.3 `DELETE`

L2.

Payload:

```json
{
  "key": "content-key"
}
```

Requirements:
- key must exist
- signer must be existing content owner

Effect:
Deletes the L2 content record.

---

## 11.4 `SIGNAL`

L2.

Same generic behavior as L1 signal.

Payload:

```json
{
  "any": "JSON payload"
}
```

---

## 11.5 `STORAGE_CREDIT`

L2.

STATUS:

```text
NOT CURRENTLY USABLE
FAIL-CLOSED
```

Current application error:

```text
STORAGE_CREDIT fail-closed: Layer 1 inclusion-proof verification is not installed
```

Do not build UI that assumes automatic L1-funded L2 storage credit is live yet.

---

# 12. RECOMMENDED L2-FIRST FRONT-END WRITE FLOW

For content/media/application data intended to live on L2:

```text
1. Query L2 /account/<wallet> if nonce state exists there.
2. Build and sign L2 STORE/SIGNAL transaction.
3. broadcast_tx_commit to L2.
4. Confirm successful transaction result.
5. Obtain L2 transaction hash and block height.
6. Build L1 L2_POINTER transaction:
     l2_chain_id
     l2_tx_hash
     l2_height
     action
7. Sign with L1 wallet nonce.
8. broadcast_tx_commit to L1.
9. UI treats L1 pointer as the authoritative public index/reference.
```

Do not reverse these steps for content whose authoritative payload belongs on L2.

---

# 13. RECOMMENDED ACCOUNT / NONCE FLOW

Before every ordinary signed transaction:

```js
const account = await chainQuery(l1Rpc, `/account/${encodeURIComponent(address)}`);
const nonce = Number(account.nonce || 0) + 1;
```

Better for large nonce values:

```js
const nonce = BigInt(account.nonce || 0) + 1n;
```

Avoid signing multiple concurrent transactions from the same account using the same nonce.

A front end should serialize writes per wallet or maintain a pending-nonce manager.

---

# 14. AMOUNT / PRECISION RULES

Current chainWare design uses integer base units.

Configured project precision:

```text
12 decimal places
```

Never transmit:

```json
{
  "amount": 1.25
}
```

Prefer:

```json
{
  "amount": "1250000000000"
}
```

for 1.25 units when decimals = 12.

JavaScript helper:

```js
function toBaseUnits(text, decimals = 12) {
  const [wholeRaw, fractionRaw = ""] = String(text).trim().split(".");
  const whole = wholeRaw || "0";

  if (!/^\d+$/.test(whole) || !/^\d*$/.test(fractionRaw)) {
    throw new Error("Invalid amount");
  }

  if (fractionRaw.length > decimals) {
    throw new Error(`Too many decimal places; maximum is ${decimals}`);
  }

  const fraction = fractionRaw.padEnd(decimals, "0");
  return (BigInt(whole) * 10n ** BigInt(decimals) + BigInt(fraction || "0")).toString();
}
```

---

# 15. PUBLIC COMETBFT RPC CALLS FOR FRONT ENDS

The `/chainware-rpc` proxy fronts the validator's CometBFT RPC server.

The most useful read calls for front-end/explorer/validator tooling are:

```text
status
health
net_info
validators
blockchain
block
block_by_hash
block_results
commit
consensus_params
unconfirmed_txs
num_unconfirmed_txs
tx
tx_search
block_search
abci_info
abci_query
genesis
genesis_chunked
```

Write/broadcast methods include:

```text
broadcast_tx_async
broadcast_tx_sync
broadcast_tx_commit
```

Potential diagnostic/administrative read methods supported by CometBFT deployments can include:

```text
consensus_state
dump_consensus_state
```

Evidence submission may exist at the CometBFT layer:

```text
broadcast_evidence
```

IMPORTANT:
The authoritative list of generic CometBFT methods is determined by the exact installed CometBFT version/configuration. chainWare currently uses the CometBFT 0.38 family. Front-end code should feature-detect or handle JSON-RPC "method not found" rather than assume every diagnostic method is publicly enabled.

---

# 16. COMMON COMETBFT FRONT-END CALL EXAMPLES

## Status

```js
const status = await rpc(rpcBase, "status", {});
```

Useful fields typically include:

```text
node_info.network
sync_info.latest_block_hash
sync_info.latest_block_height
sync_info.latest_block_time
sync_info.catching_up
validator_info.address
validator_info.voting_power
```

---

## Network peers

```js
const netInfo = await rpc(rpcBase, "net_info", {});
```

Useful for:
- connected peer count
- peer identity
- peer endpoints

---

## Validator set

```js
const validators = await rpc(rpcBase, "validators", {
  height: null,
  page: "1",
  per_page: "100"
});
```

Useful for:
- active validators
- voting power
- validator pubkeys
- consensus membership

---

## Block

```js
const block = await rpc(rpcBase, "block", {
  height: "123"
});
```

Latest block can generally be requested with no explicit height:

```js
const latestBlock = await rpc(rpcBase, "block", {});
```

---

## Block results

```js
const results = await rpc(rpcBase, "block_results", {
  height: "123"
});
```

Useful for transaction results/events.

---

## Transaction by hash

```js
const tx = await rpc(rpcBase, "tx", {
  hash: "0xABCDEF...",
  prove: false
});
```

Hash encoding expectations should be verified against the running node.

---

## Transaction search

```js
const found = await rpc(rpcBase, "tx_search", {
  query: "tx.height=123",
  prove: false,
  page: "1",
  per_page: "30",
  order_by: "desc"
});
```

Whether rich transaction search works depends on CometBFT indexing configuration.

---

# 17. CONNECTION BOOTSTRAP

A generic front end should be able to start from one validator domain.

Recommended boot process:

```text
1. GET https://<validator>/chainware-bootstrap.json
2. Read chain ID / public RPC / peer/bootstrap metadata.
3. POST status to /chainware-rpc.
4. Query /state.
5. Query /capabilities.
6. Verify the expected layer and chain ID.
7. Cache several known validator RPCs.
8. Select a healthy / caught-up endpoint.
```

Do not permanently bind the app to the first validator.

---

# 18. `chainware-bootstrap.json`

Known bootstrap concepts include:

```json
{
  "format": "chainware-...-bootstrap-...",
  "protocol_release": "...",
  "application_version": "...",
  "chain_id": "...",
  "network_id": "...",
  "genesis_url": "https://.../genesis.json",
  "genesis_sha256": "...",
  "persistent_peers": "...",
  "bootstrap_rpc": "https://.../chainware-rpc",
  "default_ports": {
    "p2p": 0,
    "rpc": 0,
    "abci": 0,
    "status": 0
  },
  "paths": {
    "rpc": "/chainware-rpc",
    "status": "/chainware-status",
    "validator": "/validator",
    "genesis": "/genesis.json",
    "bootstrap": "/chainware-bootstrap.json"
  }
}
```

Field sets may evolve by release; front ends should ignore unknown fields.

---

# 19. FRONT-END FEATURE MAP

A developer can build these immediately from the current calls.

## Network dashboard

Use:

```text
status
net_info
validators
/state
/capabilities
```

Can show:
- chain ID
- layer
- latest height
- syncing status
- connected peers
- active validators
- voting power
- app version
- transaction capabilities

---

## Wallet

Use:

```text
/account/<address>
/wallet-registration/<address>
REGISTER_WALLET
TRANSFER
```

Can show:
- balance
- nonce
- registration
- bootstrap reward
- send funds

---

## Storage dashboard

Use:

```text
/storage-fundings
/storage-funding/<hash>
STORAGE_FUND
```

Can show:
- L1 funds locked for storage
- funding status
- pending L2 proof state

Do not claim automatic L2 credit is complete yet.

---

## L2 content

Use:

```text
/content/<key>
STORE
DELETE
```

Can build:
- profiles
- posts
- comments
- media metadata
- documents
- app state

Higher-level schemas must be defined by the application because `STORE.content` is arbitrary JSON.

---

## L1 content index

Use:

```text
/l2-pointers
L2_POINTER
```

Can build:
- feed discovery
- explorer links from L1 -> L2
- newest-first index if action/key conventions are standardized

---

## Escrow

Use:

```text
/escrows
/escrow/<id>
ESCROW
```

Can build:
- escrow explorer
- locked escrow list
- escrow detail

Current base app does not expose escrow release/cancel transaction types in the source represented here.

---

## Signals

Use:

```text
/signals
SIGNAL
```

Can build application-specific events on either layer.

---

# 20. IMPORTANT MISSING / NOT-YET-NATIVE HIGHER-LEVEL APIs

The base v11 application interface represented here does NOT define dedicated query methods such as:

```text
/feed
/profile
/post
/comments
/reactions
/proposals
/votes
/treasury
/budgets
/delegations
/notifications
```

Those concepts can be implemented on top of:

```text
L2 STORE
L2 content keys
L1 L2_POINTER
SIGNAL
ESCROW
```

or can later be promoted into first-class application transaction/query types.

Do not copy old chainWare v5/v8 social API paths into a v11 front end without first verifying that they were reintroduced in the running v11 app.

---

# 21. SUGGESTED CONTENT KEY CONVENTIONS FOR FRONT ENDS

These are conventions, NOT current protocol-enforced endpoints.

Possible L2 keys:

```text
profile:<wallet>
post:<post-id>
comment:<comment-id>
reaction:<post-id>:<wallet>
media:<asset-id>
proposal:<proposal-id>
vote:<proposal-id>:<wallet>
delegation:<wallet>
```

Then point to accepted L2 transactions from L1 using:

```text
L2_POINTER.action
```

Possible actions:

```text
PROFILE
POST
COMMENT
REACTION
MEDIA
PROPOSAL
VOTE
DELEGATION
```

Again: these action values are application conventions unless/until protocol validation is added.

---

# 22. ERROR HANDLING

A robust client should handle four layers of failure:

```text
1. HTTP failure
2. JSON-RPC error
3. ABCI query response.code != 0
4. transaction check/deliver result code != 0
```

Never treat HTTP 200 alone as transaction success.

For transaction broadcasts inspect the returned transaction result sections and logs.

---

# 23. SECURITY RULES FOR FRONT-END IMPLEMENTERS

Never transmit a user's private key to a validator.

Signing should happen:
- locally in the browser
- in a local wallet application
- in a hardware signer if later supported

The validator needs only:

```text
signer address
public key
signature
signed transaction
```

Validate:
- chain_id before signing
- nonce immediately before signing
- recipient/address format
- amount with BigInt
- response code after broadcast

Never use `Number` for large balances.

Never silently switch chain IDs.

Never sign arbitrary payloads supplied by an untrusted page without showing the user what is being signed.

---

# 24. MINIMAL FRONT-END CONNECTION EXAMPLE

```js
const rpcBase = "https://YOUR-VALIDATOR/chainware-rpc";

async function connectChainWare() {
  const [status, state, capabilities] = await Promise.all([
    rpc(rpcBase, "status", {}),
    chainQuery(rpcBase, "/state"),
    chainQuery(rpcBase, "/capabilities")
  ]);

  return {
    rpcBase,
    network: status?.node_info?.network || capabilities?.ChainID || state?.ChainID,
    height: status?.sync_info?.latest_block_height || state?.Height,
    catchingUp: Boolean(status?.sync_info?.catching_up),
    state,
    capabilities
  };
}
```

---

# 25. AI IMPLEMENTATION INSTRUCTIONS

If you load this file into another AI, give it this instruction:

```text
Treat this chainWare v11 reference as the protocol/API contract for frontend work.

Before writing a feature:
1. Identify whether it reads L1, reads L2, writes L1, or writes L2.
2. Use /capabilities to verify transaction support.
3. Use application reads through abci_query.
4. Use signed transaction envelopes for ordinary writes.
5. Use broadcast_tx_commit unless a different confirmation model is explicitly requested.
6. Never invent query paths or transaction types.
7. Never use SETTLE or STORAGE_CREDIT as operational features while they remain fail-closed.
8. For higher-level social/governance concepts not represented by first-class v11 methods, use documented STORE/L2_POINTER conventions only when the application schema is supplied.
9. Preserve integer-string amounts and 12-decimal base-unit arithmetic.
10. Ask for the actual current application source or live /capabilities response if this reference conflicts with a newer chain release.
```

---

# 26. QUICK MACHINE INDEX

```json
{
  "protocol": "chainWare",
  "reference": "v11",
  "transport": {
    "public_rpc_path": "/chainware-rpc",
    "jsonrpc": "2.0",
    "query_method": "abci_query",
    "broadcast_method": "broadcast_tx_commit"
  },
  "application_queries": [
    "/state",
    "/capabilities",
    "/creator",
    "/wallet-registration/<wallet>",
    "/bootstrap-budget",
    "/storage-funding/<txHash>",
    "/storage-fundings",
    "/l2-pointers",
    "/account/<address>",
    "/escrow/<id>",
    "/escrows",
    "/content/<key>",
    "/signals"
  ],
  "l1_transactions": {
    "CREATOR_INIT_L1": "special creator init",
    "REGISTER_WALLET": "implemented",
    "TRANSFER": "implemented",
    "STORAGE_FUND": "implemented",
    "L2_POINTER": "implemented",
    "ESCROW": "implemented",
    "SIGNAL": "implemented",
    "SETTLE": "fail-closed"
  },
  "l2_transactions": {
    "CREATOR_INIT_L2": "special creator init",
    "STORE": "implemented",
    "DELETE": "implemented",
    "SIGNAL": "implemented",
    "STORAGE_CREDIT": "fail-closed"
  },
  "transaction": {
    "version": 1,
    "max_tx_bytes": 524288,
    "signature": "Ed25519",
    "address": "cw + lowercase hex(first20bytes(sha256(raw_ed25519_public_key)))",
    "post_creator_gas_required": true
  },
  "precision": {
    "recommended_decimals": 12,
    "amount_wire_type": "integer decimal string"
  }
}
```

---

# 27. VERSIONING WARNING

This reference represents the current v11 application interface discovered from the project source available when this file was generated.

The safest runtime source of truth for any deployed chain is:

```text
/capabilities
/state
/creator
```

plus the exact source/binary version running on its validators.

When chainWare adds treasury voting, proposal queues, rDAO delegation, escrow release logic, feed indexing, or inclusion-proof settlement, regenerate this reference from the updated application source instead of teaching an AI to guess the new interface.