Skip to content

User Guide

Jump to bottom
Terramike edited this page Oct 1, 2026 · 4 revisions

User Guide

Current release: v0.14.1. New users start read-only by default — every market read, balance check, and proposal build works keyless; signing stays refused until the typed xrpl-trade live ceremony. See Security for the full safety model.

Install and start

git clone https://github.com/terramike/xrpl-muse-skill.git
cd xrpl-muse-skill
pip install -r requirements-locked.txt
export PATH="$PWD/bin:$PATH"
xrpl-trade setup
xrpl-sign init-policy
xrpl-trade faucet --network testnet

xrpl-trade setup asks whether to generate a new wallet (default no) and which network to use. Local generation is testnet/devnet only; selecting an existing address stores only public address/network settings. A generated testnet credential is stored separately in a typed, owner-only file bound to the network and account; it is never printed by setup or wallet creation. Do not copy it to mainnet.

xrpl-trade wallet backup --network testnet displays the testnet seed once for an offline backup. Run that command in your own terminal, not through a chat assistant, so the seed does not enter the conversation transcript. Mainnet seed creation and backup are refused by this CLI.

The transaction ceremony

  1. Propose: run an xrpl-trade command. It builds an unsigned transaction, prints the account, network, assets and issuers, amount, price, fee, and expiry, then saves a hash-bound proposal. It does not submit.
  2. Review: check all proposal terms and verify the full 64-character digest. For NFT buys, independently check the issuer/minter as well as the current seller. For NFT uploads, review the staged file and full digest.
  3. Approve and sign: Muse must bind genuine user confirmation to the exact reviewed operation before the vault supplies credentials. Mainnet signing requires a named profile and the full digest:
xrpl-sign --profile <name> --hash <full-64-character-hash> --approve

The CLI --approve flag is only an assertion. A typed command in a transcript is not proof of consent. Without the actual Muse approval and vault boundary, do not sign mainnet transactions.

Read-only policy review can use a hash prefix, but a prefix can never authorize signing.

Profiles and policy

Mainnet proposals and signing require a named entry in ~/.xrpl/profiles.json, which binds account, network, credential reference, policy file/digest, and accounting state. Create a profile file from existing supported configuration with xrpl-sign init-profiles; review the generated profile carefully. After a deliberate policy edit, review it and run:

xrpl-sign sync-profile --profile <name>

The profile and policy schemas reject unknown or invalid settings. The v4 policy is testnet-locked by default. Missing per-asset spend limits block that asset; destination payments require an allowlisted address/tag. Do not weaken the policy just to silence a rejection.

Mainnet provisioning and release status

The CLI refuses mainnet wallet creation and backup. Provision and store mainnet credentials in the secure vault. Mainnet giveaway credentials are also vault-only. Legacy local seeds must be removed or migrated out before mainnet signing.

Mainnet remains blocked until an operator verifies in the real Muse environment that genuine confirmation gates one-time credential injection and the proposing agent cannot modify the signer, dependencies, profiles, policy, or state. xrpl-trade doctor can inspect local files but cannot certify those runtime protections.

Other bots may use read-only and proposal commands, but do not inherit Muse's secure credential boundary. Do not use another bot for mainnet unless its own vault and approval implementation is independently verified.

NFT upload review

Stage artwork locally, review the file and full SHA-256 digest, then supply that independently reviewed digest:

xrpl-trade nft-stage --file ~/.xrpl/media/art.png --name "Neon Drift"
xrpl-trade nft-pin-and-propose --stage <stage-id> \
  --approve-stage <full-reviewed-stage-sha256>

The stage digest is checked before Pinata credentials are accessed. Muse must bind the reviewed stage ID and digest into its actual approved operation; the CLI flag alone is not approval. Pinning writes externally and can leave content pinned even if a later proposal step fails. The signer separately requires the exact proposal hash approval before an NFT mint is submitted.

Doctor and accounting recovery

xrpl-trade doctor reports local profile, signer/helper, protected-file, and accounting checks plus unresolved reservations. Treat its Muse deployment status as unverified.

Never delete or truncate damaged accounting state. Recover only from a reviewed reconstruction after recording the source SHA-256; the signer preserves the damaged file and refuses to discard known liabilities. To migrate legacy accounting, use xrpl-sign migrate-state with the profile, legacy state kind, full source digest, and full reviewed migration digest. See Technical Reference for the safe recovery flow.

More help

Wiki

Propose → approve → sign. Nothing moves without your hash.

Clone this wiki locally