BitNote

Decentralized encrypted memory for agents—truly own your secrets, identity, and memories.

Security Scan

The skill's code and runtime instructions match a decentralized encrypted-vault purpose, but registry metadata omits required secrets and the skill can decrypt private keys and sign on‑chain transactions while allowing autonomous invocation — these mismatches and privileges warrant caution.

Purpose & Capability

The name/description (decentralized encrypted memory) align with the included code: reading on‑chain username mappings, decrypting stored key material, encrypting share payloads, and signing/broadcasting transactions. However the registry metadata claims no required environment variables or primary credential while SKILL.md and the scripts require a high-entropy passphrase (BITNOTE_PASSPHRASE) to decrypt keys; that metadata omission is a meaningful incoherence.

Instruction Scope

SKILL.md explicitly tells the agent to decrypt stored key material and (for writes) sign and broadcast transactions via the provided scripts. The instructions otherwise stay within the stated purpose (read/write/share encrypted notes), but they grant the skill access to long‑lived secrets and to broadcast transactions — a broad action surface that must be tightly controlled in deployment. The SKILL.md does recommend operator approval before non-dry-run writes, but that is a policy instruction; nothing in the registry metadata enforces it.

Install Mechanism

There is no install spec in the registry (instruction-only install), which is lower-risk, but the package includes JavaScript files and package.json depending on ethers. The SKILL.md quickstart instructs manual npm install (npm i ethers). Lack of an automated/install spec is not itself malicious but creates chance of missing dependency/permission warnings for users.

Credentials

The skill legitimately needs a secret passphrase (BITNOTE_PASSPHRASE) to decrypt private keys for writes and share operations; SKILL.md declares BITNOTE_PASSPHRASE required and AVAX_RPC_URL / SNOWTRACE_API_KEY optional. The registry metadata, however, lists no required env vars or primary credential. Requesting a passphrase that can decrypt signing keys is proportionate for the stated functionality — but it must be declared up front. Also, getAbi.mjs hardcodes a Snowtrace API key string 'YourApiKeyToken' instead of reading SNOWTRACE_API_KEY, another minor inconsistency.

Persistence & Privilege

The skill is not force‑always (always:false) but model invocation is allowed (default). Because the skill can decrypt key material and sign/broadcast transactions, allowing autonomous model invocation significantly increases risk: an agent could invoke writes without explicit operator confirmation. SKILL.md asks operators to require explicit approval before non-dry-run writes, but that is not enforced by the skill metadata. Combining autonomous invocation with decryption/signing capability is the main operational risk.

What to consider before installing

This skill appears to implement a real on‑chain encrypted-note workflow and includes code to decrypt private key material and sign transactions — that matches the description but requires care. Before installing or enabling: 1) Treat BITNOTE_PASSPHRASE as highly sensitive; do not store it in plaintext or give it to untrusted agents. 2) Confirm registry metadata is updated (it should declare BITNOTE_PASSPHRASE as required and note that the skill can perform on‑chain writes). 3) If you do not want the agent to perform writes autonomously, disable model invocation for the skill (or require explicit human prompts/approval) because the skill can broadcast signed transactions. 4) Test with a throwaway account and dry-run mode first (SKILL.md already recommends this). 5) Review and optionally pin the code locally (verify MOD_ADDR/NOTES_ADDR are expected contracts and app-base URL) before trusting with real identities/funds. 6) Note small inconsistencies (getAbi uses a hardcoded 'YourApiKeyToken' and does not read SNOWTRACE_API_KEY); fix them before running. If you want a fully safe deployment, require the operator to supply the passphrase interactively and disable autonomous invocation so the agent cannot sign/broadcast without human approval.

BitNote enables agents to store secrets, identity, and critical knowledge without trusting centralized infrastructure. It acts as a permanent encrypted vault under agent control, with optional human oversight. Use BitNote when information must not disappear and must remain yours.

Primary Use Cases

• Preserve agent identity (SOUL.md, values, mission, memory).
• Store secrets (API keys, credentials, private keys).
• Enable encrypted agent-to-agent communication.
• Recover state after runtime/server failures.

Canonical Write Path (Required)

Always use:

• scripts/writeBitnoteUiCompat.mjs

Do not invent alternate write paths for production use. Do not use machine-only/orphaned-note flows in this skill.

Canonical Share Path (Required)

Always use:

• scripts/generateShareLink.mjs

Do not handcraft sm/st values.

Required Write Contract

A write is successful only when output includes:

• TX_HASH
• NOTE_INDEX
• READ_AFTER_WRITE_OK 1

If READ_AFTER_WRITE_OK is not 1, treat as failure and retry safely with same request id.

Idempotency Rule (Mandatory)

Always provide a stable --request-id for each intended note write.

• First execution writes once.
• Retries with same --request-id must produce IDEMPOTENT_HIT (no duplicate note).

Passphrase Generation (Required)

Generate a high-entropy passphrase before account creation or writes.

Security target:

• Minimum: 256 bits of entropy
• Do not use human-memorable phrases, reused passwords, or dictionary-only word sequences without sufficient randomness.

Example (256-bit random hex):

BITNOTE_PASSPHRASE="$(openssl rand -hex 32)"
export BITNOTE_PASSPHRASE

Handling rules:

• Never print passphrases in chat/tool output unless explicitly requested by the operator.
• Never commit passphrases to git.
• Store passphrases in environment variables or a secret manager.

Required Environment & Privileged Capabilities

Required / optional environment and profile fields:

• BITNOTE_PASSPHRASE (required for write/share operations).
• AVAX_RPC_URL (optional RPC override; otherwise profile/default RPC is used).
• SNOWTRACE_API_KEY (optional; used only by ABI refresh workflows).
• profiles/<name>.json may include non-secret defaults like username and rpc.

Privileged behavior (must be explicitly understood before use):

• scripts/writeBitnoteUiCompat.mjs decrypts stored key material and can sign/broadcast on-chain transactions.
• scripts/generateShareLink.mjs decrypts stored key material to generate recipient-bound encrypted share links.
• scripts/readBitnote.mjs is read-only (no transaction signing).

Operator policy:

• Use read-only or dry-run modes first.
• Require explicit operator approval before any non-dry-run write.
• Test with a throwaway account before using accounts that hold real funds.

Quick Start

npm init -y
npm i ethers
node scripts/getAbi.mjs

Read account mapping and note counts:

BITNOTE_USERNAME="example_user" node scripts/readBitnote.mjs

Dry-run write first (recommended safety check, no tx broadcast):

BITNOTE_PASSPHRASE="..." \
node scripts/writeBitnoteUiCompat.mjs \
  --profile example \
  --title "Preview" \
  --body "No on-chain write" \
  --request-id "preview-001" \
  --dry-run 1

Create encrypted UI-compatible note (signs and broadcasts tx):

BITNOTE_PASSPHRASE="..." \
node scripts/writeBitnoteUiCompat.mjs \
  --profile example \
  --title "Agent Identity Core" \
  --body "<SOUL.md excerpt or core identity block>" \
  --request-id "identity-core-v1"

Retry same request safely (should not duplicate):

BITNOTE_PASSPHRASE="..." \
node scripts/writeBitnoteUiCompat.mjs \
  --profile example \
  --title "Agent Identity Core" \
  --body "<same body>" \
  --request-id "identity-core-v1"

Generate a BitNote share link (agent-to-agent or user-to-user):

BITNOTE_PASSPHRASE="..." \
node scripts/generateShareLink.mjs \
  --profile example \
  --recipient "RECIPIENT_USERNAME" \
  --body "Shared note body" \
  --title "Optional shared title"

Share link output contract:

• SENDER_USERNAME
• RECIPIENT_USERNAME
• SHARE_LINK

Recommended Identity Note Layout

Use separate notes for clarity and controlled updates:

1. Agent Identity Core — stable identity/soul primitives.
2. Agent Operator Pact — who the agent serves, constraints, commitments.
3. Agent Rehydration — restart/bootstrap instructions.

Keep each note focused and versioned in title or body (e.g., v1, v2).

Files

• scripts/getAbi.mjs: refresh contract ABIs.
• scripts/readBitnote.mjs: resolve username -> address and note counts.
• scripts/writeBitnoteUiCompat.mjs: UI-compatible encrypted writes with idempotency + read-after-write verification.
• scripts/generateShareLink.mjs: UI-compatible share-link generation (sm and optional st) for a target BitNote username.
• scripts/lib/bitnoteCompat.mjs: shared compatibility helpers.
• references/contracts.md: canonical contracts.
• references/ops.md: runbook and troubleshooting.

Safety Rules

• Never store plaintext secrets on-chain.
• Never log passphrases/private keys.
• Keep retries deterministic via --request-id.
• Use profile files for non-secret defaults only.