# Arxium

> Arxium is a layer-1 chain for regulated real-world assets. The chain itself enforces each asset's compliance rules (KYC/AML claims, allowed jurisdictions, holder caps, freezes) on every transfer, for both sender and recipient, so no app or contract can skip them. Builders use the TypeScript SDK and `arx` CLI (`@arxiumlabs/sdk`) against the public devnet `corechain-devnet`.

Key facts for writing code:

- Install: `npm install @arxiumlabs/sdk` (library, Node 20+, zero runtime deps, also runs in browsers and Workers) or `npm install -g @arxiumlabs/sdk` (the `arx` CLI).
- Node RPC: `https://retracer-api.arxium.network/rpc/corechain-devnet`. Every request needs `Authorization: Bearer rk_…` (free key at https://retracer.arxium.network, GitHub sign-in). Send a descriptive `User-Agent`. Free keys: 10 req/s; on `429` wait `Retry-After` seconds.
- CLI env: `ARX_RPC` (node URL), `ARX_TOKEN` (API key), `ARX_KEY` (encrypted key file), `ARX_PASSPHRASE` (for scripts).
- Amounts are integers (`bigint` in the SDK): 1 ARX = 1,000,000,000 IUM. Every action costs a flat 0.001 ARX.
- Addresses: accounts `arx1…`, assets `arxasset1…` (derived from issuer address + the issuer's chosen asset id; look up with `GET /assets/alias/{issuer}/{id}` → `.ref`).
- Signatures cover the chain's genesis hash, so an action signed for one chain is rejected on another. `ArxiumRpc.sendAction` fetches it for you.
- An action is final when `GET /actions/{signature}` returns `committed`; a refused one returns `{"status":"dropped","reason":"…"}`. The reason string is the error code (no numeric codes). Blocks are ~2 s; poll instead of sleeping.
- Only *asset* balances are compliance-gated. Native ARX transfers, fees and staking need no KYC.
- The devnet resets (height goes backwards). Re-claim from the faucet and click "Get attested" in the Console again. Devnet has no real value; never put real personal data in an attestation.

## Docs

- [Overview](https://arxium.network/docs): the docs' paths and where to start.
- [Endpoints and API keys](https://arxium.network/docs/endpoints): gateway, node RPC, indexer, Explorer, Console, rate limits.

CLI walkthrough (in order, everything from the terminal with `arx`):

1. [Quickstart](https://arxium.network/docs/quickstart): install `arx`, import a Console key, claim test ARX, send and verify a transfer.
2. [Issue a regulated asset](https://arxium.network/docs/issue-asset): register a KYC-gated asset, get attested, watch the chain refuse a transfer to an unattested holder, restrict by country, cap holdings, freeze a holder or the asset.
3. [Verify without a node](https://arxium.network/docs/verify): check state proofs and validator fault evidence locally with `arx-verify` or the browser verifier.

SDK walkthrough (in order, the same flow from JavaScript/TypeScript):

1. [SDK quickstart](https://arxium.network/docs/sdk-quickstart): project setup, a shared `arxium.mjs` (client, unlocked Console key, `send()`), read a balance, send ARX.
2. [Issue an asset from code](https://arxium.network/docs/sdk-issue-asset): `deriveAssetRef`, register with `required_claims`, issue, `encodeSetAssetLimits`, the other issuer controls.
3. [Compliant transfers in your app](https://arxium.network/docs/sdk-transfers): pre-check with `rpc.assets()` and `eligibility_reason`, send, catch `ActionDroppedError` and show `reason`.

Reference:

- [Devnet limits](https://arxium.network/docs/limits): resets, block times, devnet-only ZK keys.

## SDK

- `ArxiumRpc({ rpc, token })`: `.sendAction({ privateKey, sender, payload })` signs, submits and waits for the block, returning `{ action, status }`, and throws `ActionDroppedError` (with `.reason`, the node's exact text, and `.action`) if the chain refuses it; `.account(addr)`; `.assets(addr)` (balances with `transfer_eligible` / `eligibility_reason`, needs SDK 0.6.0+); `.action(signature)`; `.genesisHash()`.
- Asset refs: `deriveAssetRef(issuerAddress, assetId)` computes the `arxasset1…` ref locally.
- Keys: `generateKey`, `unlockKey`, `importSeed`, `toKeyFile`, `verifyKeyFile`.
- Amounts: `arxToIum("1.5")`, `iumToArx(n)`.
- Multisig senders (up to 16 members, threshold 1..=N): `multisigAddress`, `multisigSignature`, `verifyMultisig`.
- Asset encoders (issuer only unless noted): `encodeRegisterAsset(assetId, complianceRequired, metadata)` (anyone; the sender becomes issuer), `encodeIssueAsset`, `encodeIssueAssetTo`, `encodeBurnAsset`, `encodeSetAssetLimits(asset, maxHolders, maxBalancePerHolder, maxAttestationAge)`, `encodeFreezeAsset`, `encodeSetHolderFrozen`, `encodeLockHolderAmount`, `encodeLockHolderAmountUntil`, `encodeIssuerForcedTransfer`, `encodeRecoverHolder`, `encodeLockIssuance`, `encodeTransferIssuer`, `encodeSetAssetMetadataUri`, `encodeTransferAsset` (any holder, compliance-checked).
- `AssetMetadata`: `{ asset_class, decimals, required_claims, allowed_jurisdictions, max_supply, metadata_uri, symbol, name }`. `ClaimTopic` is `"kyc" | "aml" | "accredited" | "jurisdiction"`. Jurisdictions are ISO 3166-1 alpha-2 codes; `null` means any.
- Attestor encoders (registered attestors only): `encodeGrantAttestation(subject, identityHash, topics, jurisdiction)`, `encodeRevokeAttestation(subject)`. A re-grant replaces the previous claims entirely. Attestors are added and removed by validator vote, not by any admin.
- Generic: `encodePayload({ action, ... })` / `decodePayload(bytes)`, `signAction`, `signingBytes`, `verifySignedAction`.

## CLI

- `arx query status | account <addr> | action <sig> | block <h> | validators | finality | search <q>`
- `arx keys new <file> | import --file <file> | show`
- `arx send <action> <args…>`: signs, submits, waits for the block; prints the node's reason and exits 1 if dropped. Actions include `transfer <to> <ium>`, `register-asset <id> <symbol> <name> <decimals> [topics] [jurisdictions]`, `issue-asset <asset> <amount>`, `transfer-asset <asset> <to> <amount>`, `set-asset-limits <asset> <max-holders|-> [max-balance-per-holder|-] [max-attestation-age-blocks|-]`, `freeze-holder`/`unfreeze-holder <asset> <holder>`, `freeze-asset`/`unfreeze-asset <asset> <reason>` (these four need arx 0.6.0+), `grant-attestation`, `revoke-attestation`, `stake`, `unstake`.
- `arx verify <signature>`: checks finality and the Ed25519 signature on your own machine.

## Useful RPC reads

- `GET /accounts/{addr}`: balance, nonce, `attested_by`, `claims`, `jurisdiction`.
- `GET /accounts/{addr}/assets`: per-asset `balance`, `transfer_eligible` and `eligibility_reason` (sender side): `eligible`, `asset_frozen`, `holder_frozen`, `missing_attestation`, `missing_required_claim`, `attestation_expired`, `jurisdiction_not_allowed`, `no_transferable_balance`. Check this before sending.
- `GET /accounts/{addr}/proof`: state proof, verifiable offline.
- `GET /actions/{signature}`: `pending | dropped{reason} | committed@height`.

## Transfer errors (TransferAsset), in check order

Both sender and recipient must pass. The first failure is the dropped reason:

1. `{asset} is frozen: no transfers until it is unfrozen`
2. `{address} is frozen for {asset} and may neither send nor receive it`
3. `compliance check failed: {address} is not KYC'd/allowlisted`
4. `{address} is missing the {Topic} claim required by {asset}`
5. `{address}'s attestation is {age} blocks old, over {asset}'s limit of {max_age}`
6. `{address}'s jurisdiction ({Some("XX")|None}) is not among those {asset} permits`
7. `{asset} already has {n} holders, the cap: {address} cannot become one`
8. `{address} would hold {resulting} of {asset}, over the per-holder limit of {limit}`
9. `invalid nonce for {sender}: expected {e}, got {g}`
10. `{sender} has {locked} of {asset} locked: only {available} of {balance} is spendable, needs {amount}`
11. `insufficient {asset} balance for {sender}: has {b}, needs {a}`

Issuer-only actions from anyone else fail with `only the issuer ({issuer}) of {asset} may do this, got {sender}`. `IssuerForcedTransfer` skips all compliance gates by design (court orders, sanctions) and requires a non-empty `reason`.

## Optional

- [Explorer](https://explorer.arxium.network): blocks, actions, addresses, the attestor behind each attestation.
- [Console](https://console.arxium.network): signing key, faucet, "Get attested" on devnet, issuer pages.
- [Browser verifier](https://arxium.network/verify): state proofs and evidence, checked locally.
- Contact: contact@arxium.network