`@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

Package source lives in plugin-qubic/. 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/core@2.0.3-beta.7 (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 from package dir: cd plugin-qubic && bun run setup

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: plugin-qubic/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:

(Assets) TRANSFER_ESCROW_SHARE_RIGHTS so escrow can manage offered shares (calls QX when dest=27)
CREATE_ESCROW_DEAL — attaches offeredQu + 250_000 QU (base fee from Escrow.h); preflight free assets; effectVerified + dealIndex
Counterparty ACCEPT_ESCROW_DEAL — amount optional (auto from GetDeals); effectVerified + managedAssets
(Assets) RECOVER_ESCROW_TO_QX — move received (or leftover) shares from Escrow back to QX
Or MAKE_ESCROW_DEAL_PUBLIC / CANCEL_ESCROW_DEAL / LIST_ESCROW_DEALS
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.

Navigation Menu

Repository files navigation

`@lurrielcode/plugin-qubic`

Documentation

Requirements

Install

Character

Vault setup (preferred for full mode)

Quick start (recommended)

Point the agent at the vault

How unlock works

Password tips

Env

Actions & providers

OTC Escrow

Example prompts

Qearn

QSWAP

Develop

Notes

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
plugin-qubic		plugin-qubic
.gitignore		.gitignore
LICENSE		LICENSE
NOTICE.md		NOTICE.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

@lurrielcode/plugin-qubic

Documentation

Requirements

Install

Character

Vault setup (preferred for full mode)

Quick start (recommended)

Point the agent at the vault

How unlock works

Password tips

Env

Actions & providers

OTC Escrow

Example prompts

Qearn

QSWAP

Develop

Notes

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`@lurrielcode/plugin-qubic`