orama chain

orama chain [flags]

Read the Orama chain. Every command here only reads, except 'faucet', which
funds an account on a test network, 'send', which pays another account, and
'withdraw-earnings', which moves your earnings to your own balance.

Three read paths exist, and each command uses one:

  --gateway  the gateway's read-only /v1/chain/ proxy (default: the active
             environment's gateway). Status, blocks, transactions, the
             validator set, supply, the indexer and the Orama module queries
             (x/nodes, x/storage, x/fees, ...) under /v1/chain/query/.
  --node     a node's Cosmos REST API, for example http://127.0.0.1:31003.
             Accounts, bank balances, staking validators.
  --rpc      a node's CometBFT RPC, for example http://127.0.0.1:31001. The
             Orama modules are on a node's REST API too, but the CLI reads them
             through abci_query; with --rpc set, earnings, node, deal and query read
             it directly instead of through the gateway.

Node, deal and cluster transactions are built and signed by 'orama global',
'orama storage' and 'orama cluster'; --onion on those submits through Tor.
'send' and 'withdraw-earnings' are signed by your RootWallet and sent through the
gateway, or --node; 'send' is private unless --public is given (see 'orama chain
send'). 'faucet' signs on a node over SSH (see 'orama chain faucet').

orama chain balance <address>

Show an account's bank balances from --node's REST API. This is the account's
spendable bank balance. Earnings live in a separate account: see
'orama chain earnings'.

orama chain deal <deal-id>

Show a storage deal from x/storage through the gateway (or --rpc).

orama chain earnings <address>

Show the earnings balance x/fees holds for an account, through the gateway (or --rpc). Earnings
are what the account is paid for running nodes and services; they are not in
the bank balance.

orama chain faucet <recipient> [flags]

Send test ORAMA to an account from the chain's faucet (MsgFaucet).

The faucet exists only on a test network: a chain whose id contains -stagenet-,
-devnet- or -localnet- and whose genesis turned it on (faucet_enabled). This
command reads the chain id from the node first and refuses any other chain
before it signs anything. The chain refuses a drip over its maximum and a second
drip to the same recipient inside its cooldown (24 hours by default).

The transaction is signed ON a node, with the node's operator key (the
"validator" key of oramad's test keyring), over SSH with the environment's
wallet-provided key. The key never leaves the node and nothing secret is
printed. The operator pays the fee from its earnings. The recipient need not
exist yet. --amount is in norama (1 ORAMA = 1000000000 norama).

Prints the transaction hash, the amount, and the recipient's bank balance once
the transaction is in a block.

  orama chain faucet orama1fvfzzvqv2ara2crn3z352zjhnfl0tw4rk82j53 --env stagenet
  orama chain faucet <address> --env stagenet --amount 5000000000 --node 203.0.113.10

--node is the SSH host of the node that signs (here it is not the REST URL the
other 'orama chain' commands take); without it the environment's first node
signs.

orama chain node <node-id>

Show a node's record from x/nodes through the gateway (or --rpc): operator, roles, bonds, endpoints, capacity and status.

orama chain query <Service/Method> [request-json] [flags]

Run a gRPC query of an Orama module and print the response as JSON. By default it
goes through the gateway's GET /v1/chain/query/<Service>/<Method>; with --rpc it
goes to that node's CometBFT abci_query. The request is JSON with the proto
field names. For example:

  orama chain query orama.nodes.v1.Query/Node '{"node_id":"node-1"}'
  orama chain query orama.nodes.v1.Query/Node '{"node_id":"node-1"}' --rpc http://127.0.0.1:31001

'orama chain query --list' prints every query the CLI knows.

orama chain send <to> <amount> [--public] [flags]

Send ORAMA to another account. <amount> is in ORAMA, with up to nine decimals
(12, 0.5, 0.000000001).

A send is PRIVATE unless you say otherwise: value moves inside the shielded pool,
and the chain shows no sender, recipient or amount. A private send needs the
RootWallet to build the shielded bundle, and this RootWallet cannot yet (its agent
refuses shielded messages), so today a send without --public stops with that
explanation. It never turns into a public payment on its own.

--public is the only way to pay openly, and it is a choice you make each time:
the sender, the recipient and the amount are then visible on the chain to everyone,
permanently. The command prints the payment and that warning and asks you to type
"yes"; --yes skips the question for scripts. The RootWallet then shows the
transaction and asks you to approve it.

<to> is an orama1... account for a public send. Withdraw earnings to your balance
first ('orama chain withdraw-earnings'); earnings cannot be sent directly.

Transactions go through the gateway of the selected network, or --node (a chain
REST API, for example one reached over an SSH tunnel). Either must be https, or on
this machine. The wallet signs only for the chain the selected network names (from
its registry manifest): an endpoint that answers another chain id is refused, and a
network that names none needs --chain-id. The fee is worked out from the chain and
shown before you confirm; one over --max-fee (1 ORAMA unless you raise it) is
refused before it is signed.

  orama chain send orama1fvfzzvqv2ara2crn3z352zjhnfl0tw4rk82j53 12.5 --public
  orama chain send orama1fvfzzvqv2ara2crn3z352zjhnfl0tw4rk82j53 0.5 --public --yes

orama chain status

Show CometBFT's status: the network id, the latest block and whether the node is
catching up. Reads the gateway's /v1/chain/status, or --rpc's /status.

orama chain validator [oramavaloper-address]

Without an argument, list the CometBFT validator set from the gateway's
/v1/chain/validators (or --rpc's /validators). With an oramavaloper address,
show that validator's staking record from --node's REST API.

orama chain withdraw-earnings <amount> [flags]

Move <amount> ORAMA of your earnings to your own bank balance
(MsgWithdrawEarnings). <amount> is in ORAMA, with up to nine decimals.

Earnings are what your nodes are paid; they sit in a separate account that cannot
be sent from. Withdrawing makes them spendable: the amount is the one thing you
choose, the destination is always your own account, and the chain refuses an
amount above your earnings. See what you have with 'orama chain earnings <address>'.

Then use them as you choose: send them publicly ('orama chain send <to> <amount>
--public'), or move them into the shielded pool to keep them private (this needs a
RootWallet that builds shielded bundles). Withdrawing is itself visible on the
chain: it shows that this account withdrew this amount.

The RootWallet shows the transaction and asks you to approve it. Transactions go
through the gateway of the selected network, or --node, over https or on this
machine, and the wallet signs only for the chain the selected network names (see
'orama chain send' for --chain-id and --max-fee).

  orama chain withdraw-earnings 25