alien-goats CLI

CLI for creating and minting ALIENGOAT tokens on Stellar.

• Testnet workflow is one-command simple (setup)
• Mainnet workflow is supported with safety guards (--network mainnet --yes-mainnet)
• Asset code is parameterized (--asset-code or ALIENGOAT_ASSET_CODE)

New to this?

Start here before running commands:

• README-Learn-fast.md — narrative onboarding (the why, not just the how)
• README-Manual-QA.md — manual QA checklist after setup/mint
• README-goatmemo.md — compact 28-byte memo convention (GoatMemo v1)
• README-goatmemo-long.md — long-form encrypted IPFS + Stellar memo-hash pattern
• README-Game-Seeding.md — operator-funded game reward seeding on Stellar
• README-Custodial-Chain.md — cloud-native custody/ownership hierarchy for operators
• README-Social-Narrative.md — why blockchain "immutability" is socially enforced stability
• README-Phase-II-Contracts.md — Soroban contract phase plan + starter scaffold
• README-Trade-XLM.md — practical XLM⇄stable trading checklist and cost discipline

Install

npm install
npm link
cp .env.example .env

Network model (important)

• Default network: testnet
• For mainnet, pass --network mainnet (or set ALIENGOAT_NETWORK=mainnet)
• Any write command on mainnet requires --yes-mainnet

Write commands: trust, mint, lock-issuer, cleanup.

Fast testnet path

alien-goats setup --mint-amount 40000000

This creates/funds issuer+holder, builds trustline, and mints.

Example with custom asset code:

ALIENGOAT_ASSET_CODE=GATORXYZ alien-goats setup --asset-code GATORXYZ --mint-amount 1000

Mainnet-safe usage

Create trustline (mainnet)

alien-goats --network mainnet trust \
  --holder-secret S... \
  --issuer G... \
  --yes-mainnet

Mint (mainnet)

alien-goats --network mainnet mint \
  --issuer-secret S... \
  --destination G... \
  --amount 1000 \
  --yes-mainnet

Lock issuer flags (production controls)

alien-goats --network mainnet lock-issuer \
  --issuer-secret S... \
  --auth-required \
  --auth-revocable \
  --yes-mainnet

Optional (irreversible):

alien-goats --network mainnet lock-issuer \
  --issuer-secret S... \
  --make-immutable \
  --yes-mainnet

Environment variables

ALIENGOAT_NETWORK=testnet
ALIENGOAT_TESTNET_HORIZON=https://horizon-testnet.stellar.org
ALIENGOAT_MAINNET_HORIZON=https://horizon.stellar.org
ALIENGOAT_FRIENDBOT=https://friendbot.stellar.org
ALIENGOAT_ASSET_CODE=ALIENGOAT

ALIENGOAT_ISSUER_SECRET=S...
ALIENGOAT_ISSUER_PUBLIC=G...
ALIENGOAT_HOLDER_SECRET=S...
ALIENGOAT_DESTINATION=G...
ALIENGOAT_PUBLIC=G...
ALIENGOAT_MINT_AMOUNT=1000

CLI flags override env vars.

Commands

alien-goats keygen
alien-goats fund --public-key G...
alien-goats trust --holder-secret S... --issuer G...
alien-goats mint --issuer-secret S... --destination G... --amount 1000
alien-goats balance --public-key G...
alien-goats setup --mint-amount 100

Memo support (Text + Hash)

Write commands now support both Stellar memo types:

• Memo Text (--memo-text): UTF-8 text up to 28 bytes
• Memo Hash (--memo-hash): 32-byte hash as 64 hex characters

Examples:

alien-goats mint --issuer-secret S... --destination G... --amount 1000 --memo-text "GOAT mint v1"
alien-goats mint --issuer-secret S... --destination G... --amount 1000 --memo-hash 71e05ccbb99c36ed5a26d2396b6d28457594aae03c4d555775232b42fc1e1863

setup also supports per-step memo controls:

• --trust-memo-text / --trust-memo-hash
• --mint-memo-text / --mint-memo-hash

Production footguns (quick checklist)

• Verify asset identity as ASSET_CODE:ISSUER_PUBLIC (code alone is not unique).
• Never publish or commit ISSUER_SECRET / HOLDER_SECRET.
• On mainnet, always dry-run values on testnet first.
• Start with tiny mint amounts before larger batches.
• Keep issuer and distribution duties separate.
• Record tx hashes for trust/mint/lock operations.

CLI error cheat sheet

• Mainnet write blocked... → add --yes-mainnet only after review.
• Memo text too long... → keep --memo-text to 28 bytes max.
• Invalid memo hash... → pass exactly 64 hex chars.
• Account not found: G... → destination/trustline account is missing on selected network.
• Missing <field>... → provide CLI flag or set matching .env variable.

Automated smoke test

npm run test:e2e

Runs testnet setup + balance and verifies minted amount appears.

Custom-asset test example:

ALIENGOAT_ASSET_CODE=GATORXYZ npm run test:e2e

Optional Soroban step (deploy + init reward-controller as part of e2e):

ALIENGOAT_SOROBAN_TOKEN_ID=C... \
ALIENGOAT_SOROBAN_SOURCE=admin \
npm run test:e2e:soroban

# Optional override (otherwise auto-resolved from `stellar keys address $ALIENGOAT_SOROBAN_SOURCE`):
# ALIENGOAT_SOROBAN_ADMIN_ADDRESS=G...

Cleanup script

npm run cleanup -- --issuer-secret S... --holder-secret S...

Mainnet cleanup requires explicit confirmation:

npm run cleanup -- --network mainnet --issuer-secret S... --holder-secret S... --yes-mainnet

Cleanup does:

1. sends holder ALIENGOAT back to issuer
2. removes holder trustline
3. merges holder account into issuer

Known testnet credentials used during validation

These were generated by this CLI on Stellar testnet during development.

Setup + mint validation run

• ISSUER_PUBLIC: GAOKZGSGUQESQ4LA2TX6CO4DDA6L63Q6U4BIDBAZODOZFAHQSDCI5IGC
• ISSUER_SECRET: SCVVAP3CKALTT4NRRTIFZ4XNZ5Y44RBQ5TAHJ6JM3FXKXY7CYC3VDK4M
• HOLDER_PUBLIC: GDR5NK2KNTXR2KMAMETKU4IV24MMM2KXDLI2E2HUPNMKWYYUPFPU4N5I
• HOLDER_SECRET: SCLO6SCQGZNZZJZ2G55SMA4MDMSTATCDPFJZ6X2OXZMWQZD3IQM7H3PX

Cleanup validation run

• ISSUER_PUBLIC: GB2AQJO7KSGI7XWI3NBIGO5HXW5AZDLFFBXIBOK4M6AD334OYJZFM2GU
• ISSUER_SECRET: SCSKCYNR2C55PS4JO3WZNS3EM3W7ZGJWRTQLH4Z75EHPVSPBTR5XRTXU
• HOLDER_PUBLIC: GCUVFJPBXSL4U5O3VKVUI7DRSGSG7UDVXMEFMGIWN4ZTLBM3AZARN4AY
• HOLDER_SECRET: SD42UBUDBAU2VDEFHVAL3WZYZBHJGMJBINR3HI2JO27ZHA7ZTIN2WUEK

Note: the cleanup validation holder account was merged, so that holder public key no longer resolves.

⚠️ WARNING: PRODUCTION ACTIONS (MAINNET)

These actions create irreversible on-chain effects and can move real value.

1) Prepare production env

cp .env.mainnet.example .env

Fill .env with your real mainnet values:

• ALIENGOAT_NETWORK=mainnet
• ALIENGOAT_ISSUER_PUBLIC, ALIENGOAT_ISSUER_SECRET
• ALIENGOAT_DESTINATION
• ALIENGOAT_MINT_AMOUNT

2) Preflight checks before any mint

• Issuer account exists on mainnet and has enough XLM reserve/fees
• Destination account exists on mainnet and has XLM reserve
• Destination trustline exists for ALIENGOAT from your issuer
• You are using the correct issuer keypair (public must match secret)

3) Mainnet trustline creation (only if needed)

alien-goats --network mainnet trust \
  --holder-secret S... \
  --issuer G... \
  --yes-mainnet

4) Mainnet mint (real token issuance)

Using env values:

alien-goats --network mainnet mint --yes-mainnet

Or explicit args:

alien-goats --network mainnet mint \
  --issuer-secret S... \
  --destination G... \
  --amount 1000 \
  --yes-mainnet

5) Optional issuer hardening

alien-goats --network mainnet lock-issuer \
  --issuer-secret S... \
  --auth-required \
  --auth-revocable \
  --yes-mainnet

To permanently make issuer immutable (cannot be undone):

alien-goats --network mainnet lock-issuer \
  --issuer-secret S... \
  --make-immutable \
  --yes-mainnet

6) Operational safety recommendations

• Start with a tiny mint amount first (e.g., 1)
• Verify balances and transaction hash after each step
• Keep issuer secret offline where possible
• Prefer multisig for production issuer/distribution accounts
• Never commit real secrets to git or share in chat logs

Token math + allocation guide

See TOKENOMICS.md for seed allocation models, donation-to-token formulas, dilution math, and mint policy guardrails.

Single Page App Simulator

A browser-only simulator is included at:

• simulator/index.html

It models:

• testnet vs production stages
• account creation (issuer/holder)
• trustline setup
• mint + transfer flow
• seed allocation math (donation / price * multiplier)
• simple market tick for price movement

🧠 Cheat Sheet: Understanding the Action

Quick plain-English glossary for what this CLI is doing.

• Stellar: The blockchain network where these token actions happen.
• Testnet: Practice network with fake value. Safe for development.
• Mainnet: Real network with real value. Actions are production-impacting.
• Issuer Account: The account that creates (issues/mints) your token.
• Distribution/Holding Account: Account that receives and holds issued tokens.
• Asset Code: Token symbol/name on Stellar (here: ALIENGOAT).
• Asset Issuer: The public key of the issuer account; together with asset code it defines the token.
• Trustline: Opt-in permission from a holder account to accept a specific issued asset.
• Mint (Payment op): Sending issued asset units from issuer to destination; this is token issuance in this flow.
• Horizon: Stellar API endpoint used by the CLI to read/write blockchain data.
• Network Passphrase: Chain identity protection (testnet vs mainnet transactions are not interchangeable).
• Base Fee: Network fee paid in XLM per operation in a transaction.
• Memo: Optional short note attached to a transaction.
• Tx Hash: Transaction ID used to verify the exact on-chain action.
• Auth Flags: Issuer controls (e.g., require authorization, revocable trustlines, clawback support).
• Immutable Issuer: Permanent flag that disables future account setting changes (irreversible).
• Account Merge: Closes one account and transfers remaining XLM to another account.

Minimal flow in words

1. Create/fund accounts (issuer + holder).
2. Holder creates trustline to issuer's ALIENGOAT asset.
3. Issuer mints by paying ALIENGOAT to holder.
4. Verify balances and tx hashes on Horizon/explorer.
5. (Optional) lock issuer controls for production policy.

Addendum: Helpful Endpoints, Tools, and Links

Stellar HTTP Endpoints

• Mainnet Horizon: https://horizon.stellar.org
• Testnet Horizon: https://horizon-testnet.stellar.org
• Testnet Friendbot: https://friendbot.stellar.org

Useful account query pattern:

https://horizon-testnet.stellar.org/accounts/<PUBLIC_KEY>
https://horizon.stellar.org/accounts/<PUBLIC_KEY>

Useful transaction query pattern:

https://horizon-testnet.stellar.org/transactions/<TX_HASH>
https://horizon.stellar.org/transactions/<TX_HASH>

Core Tools

• Stellar Laboratory (build/sign/inspect tx):
  • https://laboratory.stellar.org/
• Stellar Expert (explorer):
  • https://stellar.expert/explorer/public
  • https://stellar.expert/explorer/testnet
• Developer Docs:
  • https://developers.stellar.org/docs

Project-Specific Files

• CLI source: src/cli.js
• Cleanup script: scripts/cleanup.js
• E2E smoke test: scripts/test-e2e.js
• Mainnet env template: .env.mainnet.example
• Token math guide: TOKENOMICS.md
• Browser simulator: simulator/index.html

Quick Verification Workflow

1. Run command and copy returned Hash: ...
2. Open Horizon transaction endpoint with that hash
3. Confirm operation type, source account, destination, amount, and asset issuer
4. Check destination account balances endpoint