@lurrielcode/plugin-qubic

ElizaOS 2.0 Quick Plugin for the Qubic network — wallet context, balance checks, QU transfers, OTC Escrow, and smart-contract query/invoke.

Documentation

| Doc | Audience | Contents | |---|---|---| | README.md | Everyone | Install, vault setup (create + password), env, action list, develop | | FEATURES.md | Humans | Plain-English catalog of wallet, contracts, and Escrow (flows, fees, checklist) | | AI.md | Chat / tool-using agents | Quick routing, params, decision flows, anti-patterns | | AGENTS.md | Coding agents | Repo map, how to add actions, test/docs checklist |

Start with FEATURES.md for Escrow end-to-end. Point chat agents at AI.md (Quick routing first). Point coding agents at AGENTS.md.

Requirements

| Tool / package | Version | Role | |---|---|---| | Bun | 1.1+ (developed on 1.3.x) | Build, test, lint (bun run build, bun test) | | Node.js | 20+ (22 LTS recommended) | Runtime host for ElizaOS / Node consumers of dist/ | | TypeScript | 5.9+ (dev) | Typecheck / declarations | | @elizaos/core | 2.0.3-beta.7 (peer) | ElizaOS 2.0 plugin host — must match this pin | | @qubic.org/* | see plugin-qubic/package.json | wallet, rpc, contracts, vault, crypto, types |

Notes:

• This package is ESM ("type": "module"). Use a runtime that supports native ES modules.
• You do not need Bun in production if you only install the published package and run under Node/ElizaOS — Bun is required to develop / build / test this repo.
• Optional model plugins (e.g. Google GenAI, OpenAI) are not dependencies of this plugin; configure them in your Eliza character.

Install

bun add @lurrielcode/plugin-qubic
# or: npm install @lurrielcode/plugin-qubic

npx plugin-qubic-setup
# Interactive vault wizard: new wallet / import seed / verify existing vault.
# Prints QUBIC_VAULT_PATH + QUBIC_VAULT_PASSWORD for .env / character secrets (needed for signing).

Peer: @elizaos/[email protected] (or current 2.0 beta pin matching package.json).

Character

Minimal demo character (also in plugin-qubic/character.json):

{
  "name": "QubicDemo",
  "plugins": ["@lurrielcode/plugin-qubic"]
}

Copy character.json, set a model API key, and configure a vault (full mode) or QUBIC_IDENTITY (read-only). Prefer vault over plaintext seed — see Vault setup below.

Vault setup (preferred for full mode)

The agent needs a vault file on disk plus a password in env/secrets — not a seed pasted into chat.

Quick start (recommended)

npx plugin-qubic-setup
# or: bun run setup (from package root)

Interactive menu: (1) create new wallet, (2) import existing seed, (3) verify an existing vault.
Non-interactive:

npx plugin-qubic-setup --new --out .secrets/agent.qubic-vault
QUBIC_SEED='your55charlowercaseseed.......................' \
  npx plugin-qubic-setup --from-seed --force
npx plugin-qubic-setup --existing /absolute/path/to/agent.qubic-vault

The CLI prints QUBIC_VAULT_PATH, QUBIC_VAULT_PASSWORD, QUBIC_VAULT_ALIAS, and identity=….
(--new also shows the seed once for offline backup; --from-seed does not print the seed.)

Store the password somewhere safe. Keep .secrets/*.qubic-vault out of git (gitignored).
ElizaOS may also prompt for vault fields from agentConfig.pluginParameters at install / first run.

Point the agent at the vault

In .env / character settings + secrets (paths must be absolute):

QUBIC_VAULT_PATH=/absolute/path/to/.secrets/agent.qubic-vault
QUBIC_VAULT_PASSWORD=choose-a-strong-password
QUBIC_VAULT_ALIAS=agent
# optional label / read-only fallback:
# QUBIC_IDENTITY=<60-char-identity-from-script>

In Eliza character.json, put the password under settings.secrets, and the path (and optional alias) under settings:

{
  "settings": {
    "QUBIC_VAULT_PATH": "/absolute/path/to/agent.qubic-vault",
    "QUBIC_VAULT_ALIAS": "agent",
    "secrets": {
      "QUBIC_VAULT_PASSWORD": "choose-a-strong-password"
    }
  }
}

How unlock works

• Unlock runs once when the agent/service starts (not before every transfer).
• After unlock, signing actions use the in-memory wallet; you are not prompted for the password again until restart.
• Do not set plaintext QUBIC_SEED alongside the vault in production (QUBIC_SEED would win and bypass the vault file).

Password tips

• Prefer a long random password; plugin-qubic-setup generates one if you leave the password empty.
• Best practice: vault file and password in different places (e.g. file on disk, password in OS/secret manager) — not both in the same committed file.
• Never paste seed, vault bytes, or password into chat.
• Legacy one-liner: scripts/create-vault-from-seed.mjs (same as --from-seed).

Env

See plugin-qubic/.env.example.

| Variable | Notes | |---|---| | QUBIC_VAULT_PATH | Preferred. Absolute path to an encrypted Qubic vault (@qubic.org/vault v3). | | QUBIC_VAULT_PASSWORD | Vault password (required with path). Sensitive — never commit. | | QUBIC_VAULT_PUBLIC_ID | Optional. Pick a seed by identity when the vault has several. | | QUBIC_VAULT_ALIAS | Optional. Pick a seed by alias when the vault has several. | | QUBIC_SEED | Discouraged plaintext seed (55× a-z). Wins over vault if both set. Prefer vault. | | QUBIC_IDENTITY | Optional. 60× A–Z → read-only when no seed/vault | | QUBIC_RPC_URL | Default https://rpc.qubic.org (paths /live/v1 and /query/v1 are appended) | | QUBIC_TICK_OFFSET | Default 15 (target tick = current + offset) | | QUBIC_NO_ACTIONS | Optional kill-switch — actions validate as unavailable | | QUBIC_MAX_TRANSFER_QU | Optional ceiling for transfer / invoke attached QU (unset = no limit) |

Missing seed/vault does not crash the runtime — the plugin loads in read-only or unconfigured mode.

Amounts are integer QU (bigint). Do not send decimal amounts.

Actions & providers

| Name | Type | Requires | Description | |---|---|---|---| | QUBIC_WALLET | provider | vault/identity | Identity, balance, tick/epoch, mode (full / read-only) | | CHECK_QUBIC_BALANCE | action | vault/identity | Native QU balance for agent wallet or another identity | | CHECK_QUBIC_ASSETS | action | vault/identity | Owned shares/tokens (optional name/issuer/mgr filters) | | GET_QUBIC_TX | action | none (RPC only) | Archive tx lookup by hash + explorer link | | GET_QUBIC_HISTORY | action | vault/identity | Paginated archive tx list for an identity | | TRANSFER_QUBIC | action | full mode (vault) | Send integer QU to a recipient identity | | GET_QUBIC_TICK | action | none (RPC only) | Current network tick, epoch, and tick duration | | QUERY_QUBIC_CONTRACT | action | none (RPC only) | Read-only smart-contract query via @qubic.org/contracts | | INVOKE_QUBIC_CONTRACT | action | full mode (vault) | Signed smart-contract procedure call (broadcast + confirm) | | LOCK_QEARN | action | full mode (vault) | Lock QU in Qearn (≥ 10_000_000 QU; balance checked) | | UNLOCK_QEARN | action | full mode (vault) | Unlock QU (capped to locked; or all=true) | | GET_QEARN_STATUS | action | vault/identity | Per-epoch locks + weeks to full / early-unlock % | | GET_QEARN_STATS | action | none (RPC only) | Epoch APY / pool / burned & boosted stats | | GET_QSWAP_FEES | action | none (RPC only) | QSWAP fee schedule | | GET_QSWAP_POOL | action | none (RPC only) | AMM pool state for issuer+ticker | | GET_QSWAP_POSITION | action | none (RPC only) | Assets managed by QSWAP (mgr=13) | | QUOTE_QSWAP | action | none (RPC only) | Exact-input quote + effective QU/asset price | | SWAP_EXACT_QU_FOR_ASSET | action | full mode (vault) | Sell exact QU for asset (required minOut > 0; effectVerified) | | SWAP_EXACT_ASSET_FOR_QU | action | full mode (vault) | Sell exact asset for QU (mgr=13; required minOut > 0; effectVerified) | | VERIFY_QSWAP_EFFECT | action | none (RPC only) | Re-check swap effect vs assetBefore (no broadcast) | | TRANSFER_QSWAP_SHARE_RIGHTS | action | full mode (vault) | Move share management to/from QSWAP | | CREATE_ESCROW_DEAL | action | full mode (vault) | Create OTC Escrow deal (offer/request QU and/or assets) | | ACCEPT_ESCROW_DEAL | action | full mode (vault) | Accept escrow deal by index (attach requested QU) | | CANCEL_ESCROW_DEAL | action | full mode (vault) | Cancel an escrow deal you created | | MAKE_ESCROW_DEAL_PUBLIC | action | full mode (vault) | Publish an escrow deal | | TRANSFER_ESCROW_SHARE_RIGHTS | action | full mode (vault) | Move asset management rights (often to escrow index 27) | | RECOVER_ESCROW_TO_QX | action | full mode (vault) | After accept/cancel: move Escrow-managed shares back to QX (+100 QU fee) | | LIST_ESCROW_DEALS | action | vault/identity | List owned / proposed / public escrow deals | | LIST_ESCROW_MANAGED_ASSETS | action | vault/identity | Assets still under Escrow mgr=27 that need recover | | GET_ESCROW_FREE_ASSET | action | vault/identity | Free share amount available for escrow |

Service type: qubic (QubicService).

OTC Escrow

On-chain atomic OTC (contract index 27). Typical flow:

1. (Assets) TRANSFER_ESCROW_SHARE_RIGHTS so escrow can manage offered shares (calls QX when dest=27)
2. CREATE_ESCROW_DEAL — attaches offeredQu + 250_000 QU (base fee from Escrow.h); preflight free assets; effectVerified + dealIndex
3. Counterparty ACCEPT_ESCROW_DEAL — amount optional (auto from GetDeals); effectVerified + managedAssets
4. (Assets) RECOVER_ESCROW_TO_QX — move received (or leftover) shares from Escrow back to QX
5. Or MAKE_ESCROW_DEAL_PUBLIC / CANCEL_ESCROW_DEAL / LIST_ESCROW_DEALS
6. LIST_ESCROW_MANAGED_ASSETS — check whether any shares still sit under Escrow management

On-chain constraints (important):

• Pure QU↔QU deals are rejected — at least one side must include assets/shares.
• Create fee is 250_000 QU (ESCROW_BASE_FEE) on top of offeredQu.
• Accept may need more than requestedQu when NULL-issuer share fees apply (plugin computes this).
• Returning share management from Escrow to QX (RECOVER_ESCROW_TO_QX / newContractIndex=1) attaches 100 QU (QX.Fees.transferFee); Escrow destination is free. Override with action param fee if needed.
• Archive inclusion ≠ procedure success — check effectVerified on Escrow writes. Asset JSON shape: [{"issuer":"<60-char identity>","name":"CFB","amount":"10"}] (max 4 per side).

Example prompts

What's my Qubic balance?
Check Qubic balance of ONPISFZBYTFTHGUKXCIBDAKKOOAAOCULTWFBEOKLNBSKLXTIRWEJDTHGNXFH
Send 10 QU to ONPISFZBYTFTHGUKXCIBDAKKOOAAOCULTWFBEOKLNBSKLXTIRWEJDTHGNXFH
Pay 1 QU to ONPISFZBYTFTHGUKXCIBDAKKOOAAOCULTWFBEOKLNBSKLXTIRWEJDTHGNXFH
What's the current Qubic tick?
Query qearn getBurnedAndBoostedStats
List my escrow deals
How much do I have locked in Qearn?
What is the Qearn APY this epoch?
Lock 10000000 QU in Qearn
Unlock 10000000 QU from Qearn epoch 225
Unlock all my Qearn locks
Create escrow offering 1000 QU requesting 500 QU from ONPISFZBYTFTHGUKXCIBDAKKOOAAOCULTWFBEOKLNBSKLXTIRWEJDTHGNXFH

Qearn

Contract index 9. Actions: LOCK_QEARN, UNLOCK_QEARN, GET_QEARN_STATUS, GET_QEARN_STATS.

• Minimum lock/unlock: 10_000_000 QU; max per user/epoch: 1T QU. Full term: 52 weeks.
• Lock attaches the amount as the tx value (empty procedure payload); balance is checked first.
• Unlock: amount + lockedEpoch (capped to locked), or all=true. Early unlock returns principal; bonus % follows the public reward/burn/boost table.
• Status shows weeks remaining + early-unlock band; stats show pool APY / burned / boosted.

QSWAP

Contract index 13. Actions: GET_QSWAP_FEES, GET_QSWAP_POOL, GET_QSWAP_POSITION, QUOTE_QSWAP, SWAP_EXACT_QU_FOR_ASSET, SWAP_EXACT_ASSET_FOR_QU, VERIFY_QSWAP_EFFECT, TRANSFER_QSWAP_SHARE_RIGHTS.

• Swaps need an existing pool; attach 100_000 QU fee (+ input QU for QU→asset).
• Asset→QU requires share management under QSWAP (13).
• Archive inclusion ≠ AMM success (no contract returnCode). After a doubtful swap use VERIFY_QSWAP_EFFECT with assetBefore from GET_QSWAP_POSITION or from SWAP_*.data — never re-broadcast the same swap. See FEATURES.md (“Confirming whether a swap really ran”) and AI.md.

Develop

bun install          # Bun 1.1+
bun run build
bun test
bun run typecheck    # optional

Unit tests mock Qubic RPC (fetch) — no mainnet calls required. See FEATURES.md / AI.md for Escrow behavior while developing.

Notes

• Seed / vault password are never logged. Seed is dropped from service env after wallet creation.
• After broadcast, success requires archive inclusion. If confirmation fails, the error says do NOT retry (double-spend risk) and includes the tx hash.
• Amount units (verified 2026-08-10): RPC/@qubic.org bigint balances and transfer amounts are whole QU (QUBIC), 1:1 with the explorer. Example: identity ONPISFZB… showed 4317815119 on rpc.qubic.org and 4,317,815,119 QUBIC on explorer.qubic.org. PROTOCOL.ISSUANCE_RATE (1e12) is epoch emission size in QU, not a subunit scale — do not multiply/divide user amounts by it.
• Smart-contract procedure invoke is available via INVOKE_QUBIC_CONTRACT (full mode). Prefer QUERY_QUBIC_CONTRACT for read-only views.

License

This project is licensed under the MIT License (LICENSE).

In plain terms:

• You may use this software commercially and in closed-source products.
• You may modify and redistribute it freely.
• You must keep the copyright and permission notice.
• The software is provided as is, without warranty.

The intent is broad Qubic adoption: integrate this plugin wherever it helps.

Copyright (C) 2026 Lurriel - lurrielcode / contributors.