Skip to content

TOOLING.md

Latest commit

 

History

History
335 lines (264 loc) · 12.9 KB

TOOLING.md

File metadata and controls

335 lines (264 loc) · 12.9 KB

Tooling & Usage Guide

This guide captures how to operate Enigmatic’s DigiByte reference stack. It aligns with enigmatic_dgb/cli.py, the specs in ../specs/, and the examples in ../examples/ so contributors can move from a dry-run plan to an on-chain broadcast without guessing how components fit together.

1. Prerequisites

  • Python: 3.10+.
  • DigiByte node: DigiByte Core with RPC enabled and a funded wallet.
  • System packages: git, python3-venv, build-essential (for dependency builds).

2. Install & verify the CLI

git clone https://github.com/JohnnyLawDGB/Enigmatic.git
cd Enigmatic
python -m venv .venv && source .venv/bin/activate
pip install -e .[dev]

# Confirm availability
enigmatic-dgb --help

The editable install exposes the enigmatic-dgb CLI and keeps it synchronized with your working tree.

3. RPC & wallet configuration

All planner, sender, and watcher commands share a single configuration surface. Set environment variables once or create ~/.enigmatic/config.yaml so every subcommand can reuse the same connection details (legacy ~/.enigmatic.yaml is still supported).

export DGB_RPC_USER="rpcuser"
export DGB_RPC_PASSWORD="rpcpass"
export DGB_RPC_HOST="127.0.0.1"
export DGB_RPC_PORT="14022"
export DGB_RPC_WALLET="enigmatic"

Or use YAML (default path: ~/.enigmatic/config.yaml):

rpc:
  user: rpcuser
  password: rpcpass
  host: 127.0.0.1
  port: 14022
  wallet: enigmatic

Pass --config /path/to/alt.yaml to any enigmatic-dgb command to swap profiles. Load and unlock the target wallet before broadcasting so the transaction builder can sign each frame.

4. Command surface

Command Purpose
send-message Encode a free-form intent and payload without referencing a dialect.
send-symbol Encode and broadcast a symbol defined in a dialect YAML file.
plan-symbol Dry-run or broadcast a single symbol using automation metadata.
plan-chain Plan or broadcast multi-frame symbols defined in a dialect.
plan-pattern Plan/broadcast an explicit list of amounts (value-plane only).
send-sequence / plan-sequence Explicit sequences (independent UTXOs by default; --chained to reuse change).
watch Observe an address and stream decoded packets.
unspendable Generate a human-readable unspendable vanity address.
ord-scan Scan a block range for OP_RETURN and Taproot-style inscription candidates (experimental).
ord-index Query the local inscription cache built via ord-scan --update-index.
ord-decode Decode inscription-style payloads from a transaction (experimental).
ord-mine Discover inscriptions paying to your wallet or provided addresses (best-effort).
ord-plan-op-return Draft an OP_RETURN inscription envelope without broadcasting (experimental).
ord-plan-taproot Draft an Enigmatic Taproot Dialect v1 inscription leaf and funding sketch (experimental).
ord-inscribe Build, sign, and optionally broadcast an inscription transaction (experimental, irreversible).
dtsp-*, binary-utxo-* Encode/decode helpers for specific substitution mappings.
enigmatic-api Start the minimal HTTP JSON wrapper for encode/decode endpoints.

Common planner flags:

  • --min-confirmations – funding UTXO filter (default 1; set to 0 for unconfirmed starts).
  • --min-confirmations-between-steps – wait for confirmations between frames.
  • --wait-between-txs – poll cadence / pacing delay between frames.
  • --max-wait-seconds – abort threshold for confirmation waits.
  • --fee – override dialect fee punctuation (where supported).
  • --chained – reuse change output between steps instead of independent funding.
  • --auto-prepare-utxos – carve UTXOs automatically when independent funding is requested.
  • --auto-prepare-fee – fee for the auto-prepare transaction (defaults to --fee).
  • --block-target – optional absolute block height to celebrate or align with; broadcasting waits until the chain is within the configured drift window.

5. Typical workflow: dry-run → broadcast

  1. Plan a symbol or pattern without broadcasting.
  2. Inspect the emitted state vector: inputs, outputs (value plane), fee, cardinality, block-placement expectations, and optional OP_RETURN hints.
  3. Broadcast the exact plan after review; the builder reuses the planned change choreography so the broadcast matches the dry-run.

Example: dialect symbol

# Preview the HEARTBEAT symbol defined in examples/dialect-heartbeat.yaml
enigmatic-dgb plan-symbol \
  --dialect-path examples/dialect-heartbeat.yaml \
  --symbol HEARTBEAT --dry-run

# Broadcast once reviewed
enigmatic-dgb plan-symbol \
  --dialect-path examples/dialect-heartbeat.yaml \
  --symbol HEARTBEAT --broadcast

Example: chained frames from a dialect

enigmatic-dgb plan-chain \
  --dialect-path examples/dialect-heartbeat.yaml \
  --symbol HEARTBEAT_CHAIN \
  --to-address DT98bqbNMfMY4hJFjR6EMADQuqnQCNV1NW \
  --min-confirmations 0 --max-frames 3 --dry-run

# Add --broadcast to stream txids in order and reuse the planned change output between frames.

Example: explicit sequences without a dialect

# Inspect a prime staircase
enigmatic-dgb plan-sequence \
  --to-address DT98bqbNMfMY4hJFjR6EMADQuqnQCNV1NW \
  --amounts 73,61,47,37,23,13,5 \
  --fee 0.21 --op-return-ascii I,S,E,E,Y,O,U

# Broadcast the same plan using independent UTXOs
enigmatic-dgb send-sequence \
  --to-address DT98bqbNMfMY4hJFjR6EMADQuqnQCNV1NW \
  --amounts 73,61,47,37,23,13,5 \
  --fee 0.21 --op-return-ascii I,S,E,E,Y,O,U

# Optional: auto-carve UTXOs if the wallet has only one large input
enigmatic-dgb send-sequence \
  --to-address DT98bqbNMfMY4hJFjR6EMADQuqnQCNV1NW \
  --amounts 73,61,47,37,23,13,5 \
  --fee 0.21 --op-return-ascii I,S,E,E,Y,O,U \
  --auto-prepare-utxos

Example: generate an unspendable vanity address

enigmatic-dgb unspendable DCx "THiSxiSxTHExSTUFF"
# → DCxTHiSxiSxTHExSTUFFzzzzzzzzbSG1oo

Example: free-form message

enigmatic-dgb send-message \
  --to-address dgb1example... \
  --intent presence \
  --channel ops \
  --payload-json '{"window": "mid"}'

6. Creating or extending dialects

Use the dedicated dialect helpers instead of hand-editing YAML:

# Discover built-in examples and any custom directories you pass
enigmatic-dgb dialect list --dialect-dir ~/enigmatic-dialects

# Lint structure and reserved plane markers (FRAME_SYNC, HEARTBEAT, CONSENSUS_PROOF)
enigmatic-dgb dialect validate examples/dialect-heartbeat.yaml

# Scaffold a new dialect interactively
enigmatic-dgb dialect generate --output-path ~/enigmatic-dialects/dialect-custom.yaml

The generator collects value anchors, fee punctuation, cardinality, and block-placement cadence and writes a ready-to-edit YAML template. After tweaking anchors or metadata, dry-run with plan-symbol to confirm your state vector:

enigmatic-dgb plan-symbol \
  --dialect-path ~/enigmatic-dialects/dialect-custom.yaml \
  --symbol CUSTOM_SYMBOL \
  --dry-run

Keep dialect files close to their replay instructions inside examples/README.md (or your own directory index) so observers can reproduce them with the same CLI flags.

7. Decoding patterns and watching addresses

  • Live observation: enigmatic-dgb watch --address <dgb1...> --poll-interval 15 streams decoded packets (JSON per line). Pipe to jq or a log collector.
  • DTSP helpers: dtsp-encode, dtsp-decode, and dtsp-table convert between plaintext and decimal-time-substitution patterns.
  • Binary packet helpers: binary-utxo-encode / binary-utxo-decode map text to binary payloads expressed as decimal outputs.

Decoded walkthroughs in examples/example-decoding-flow.md mirror the watcher output and illustrate how block spacing and change-linking recover multi-frame symbols.

Ordinal inscription exploration

Probe the chain for inscription-style outputs or inspect a specific transaction using the shared RPC configuration. These helpers are conventional, non-consensus conveniences and may evolve as the Enigmatic Taproot dialect matures.

# Scan a slice of the chain for candidates
enigmatic-dgb ord-scan --start-height 1800000 --end-height 1800010 --limit 10

# Decode inscription-like payloads from a transaction (all vouts)
enigmatic-dgb ord-decode <txid> --json

Pass --no-include-op-return or --no-include-taproot-like to narrow searches. Add --json to emit machine-readable results when scripting. If a wallet-scoped RPC cannot see a mempool transaction, ord-decode retries with the base RPC endpoint automatically. Taproot-aware parsing is experimental and may not recognize all inscription formats.

Optional local inscription index

Recurring scans can persist decoded inscriptions to a lightweight, local SQLite cache to avoid re-scanning the chain. Enable indexing explicitly during scans:

enigmatic-dgb ord-scan --start-height 1800000 --end-height 1800010 --update-index

The index lives at ~/.enigmatic-dgb/ordinals.sqlite by default (override with --index-path). It is non-consensus, can be safely deleted, and can always be repopulated by running ord-scan --update-index again.

Query cached inscriptions without hitting RPC:

enigmatic-dgb ord-index list --limit 20
enigmatic-dgb ord-index show <txid>
enigmatic-dgb ord-index by-address <dgb-address>

Taproot inscription planning

Use the plan-only Taproot helper to sketch an inscription following the Enigmatic Taproot Dialect v1. It connects to the DigiByte node using the same RPC flags as other ordinal commands and does not sign or broadcast the transaction. See taproot-dialect-v1.md for the envelope layout. See also taproot-wallets-cli.md for setting up a Taproot descriptor wallet with digibyte-cli.

# Plan a text/plain inscription
enigmatic-dgb ord-plan-taproot "hello taproot"

# Plan a binary payload with a custom content type and JSON output
enigmatic-dgb ord-plan-taproot 0x68656c6c6f --content-type application/octet-stream --json

Creating inscriptions

Move from planning to on-chain inscriptions with explicit safety controls. Fees are your responsibility; inscriptions are permanent and can bloat the chain.

# Dry-run an OP_RETURN inscription and inspect the signed hex without broadcasting
enigmatic-dgb ord-inscribe "hello chain" --scheme op-return --no-broadcast --max-fee-sats 250000

# Taproot-style inscription with content-type hint and fee cap
enigmatic-dgb ord-inscribe 0x68656c6c6f --content-type text/plain --scheme taproot --max-fee-sats 400000

Use --no-broadcast (the default) to validate funding and signatures without relaying. Add --max-fee-sats (defaults to 250000) to abort when the estimated fee exceeds your budget. Supply --broadcast only after reviewing the signed hex and fee estimate; the CLI prints a warning before submission so you can double-check the payload and fee.

8. Integrating wallets & RPC setups

  • For mainnet/testnet switching, swap config files via --config (e.g. ~/.enigmatic.testnet.yaml) while reusing the same dialect file.
  • For air-gapped signing, use plan-* commands to export the planned inputs and outputs, sign offline via DigiByte Core, then broadcast with sendrawtransaction.
  • For automation, wrap CLI invocations in scripts or import TransactionBuilder, SymbolPlanner, and DigiByteRPC directly from the package to reuse the same deterministic planning logic.

9. Validation & troubleshooting

  • Run pytest to confirm encoder/decoder and planner invariants before rolling out new dialects.
  • Use --min-confirmations=0 with caution: chains will reference unconfirmed change outputs in memory until the prior frame confirms.
  • If a broadcast fails, re-run the identical plan-* command to confirm no wallet state drift occurred between planning and submission.
  • Troubleshooting quick hits:
    • RPC unreachable: verify DGB_RPC_* variables, wallet path, and node availability; add --verbose to surface transport errors.
    • Wallet not funded or locked: ensure the target wallet is loaded and unlocked, and that spendable UTXOs exist for the configured --min-confirmations window.
    • Max fee cap triggered: reduce inscription payload size or raise --max-fee-sats after confirming current mempool fees.
    • No inscriptions found: widen the block range, loosen --include-op-return / --include-taproot-like filters, or run ord-scan --update-index to refresh the cache before ord-index/ord-mine calls.
    • Local index empty: ensure ~/.enigmatic-dgb/ordinals.sqlite exists or pass --index-path to ord-scan --update-index to rebuild it.

10. References