pft-chatbot-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AGTI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,461 @@
+# PFT Chatbot MCP
+
+MCP server for building bots on the Post Fiat (PFTL) network.
+
+This is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives LLMs the ability to send and receive encrypted on-chain messages on the PFTL network. It enables building bots that can scan for incoming messages, process them, and respond -- similar to Telegram Bots but chain-based, encrypted by default, and LLM-native.
+
+## Version Compatibility
+
+| Component | Version | Notes |
+|-----------|---------|-------|
+| pft-chatbot-mcp | 0.1.0 | This package |
+| Keystone Protocol | v1 | Proto schema version |
+| pf.ptr Pointer | v4 | On-chain memo format |
+| Keystone gRPC server | >= 0.1.0 | Backend service |
+
+When the Keystone protocol is updated, a new MCP release will be published with matching compatibility. Check `src/version.ts` for the exact version constraints.
+
+## How It Works
+
+### Architecture
+
+```
+Bot Operator's Machine                  Post Fiat Infrastructure
+┌──────────────────────────┐            ┌─────────────────────────┐
+│  LLM Client              │            │ Keystone gRPC Service   │
+│  (Cursor, Claude, etc.)  │            │  ┌───────────────────┐  │
+│     │                    │            │  │ IPFS write gate   │  │
+│     │ MCP protocol       │            │  │ Agent registry    │  │
+│     │ (stdio)            │            │  │ Envelope storage  │  │
+│     ▼                    │   gRPC     │  │ Auth + rate limits│  │
+│  ┌──────────────────┐    │◄──────────►│  └───────────────────┘  │
+│  │ pft-chatbot-mcp  │    │   TLS      │                         │
+│  │                  │    │            │  ┌───────────────────┐  │
+│  │ • Signs txs      │    │            │  │ PostgreSQL        │  │
+│  │ • Decrypts msgs  │    │            │  └───────────────────┘  │
+│  │ • Encrypts msgs  │    │            │                         │
+│  └──────┬───────────┘    │            │  ┌───────────────────┐  │
+│         │                │            │  │ IPFS Cluster      │  │
+│         │ JSON-RPC/WSS   │            │  │ (public gateways) │  │
+│         ▼                │            │  └───────────────────┘  │
+│  PFTL Chain (testnet)    │            └─────────────────────────┘
+└──────────────────────────┘
+```
+
+**Key security property**: Private keys never leave your machine. All signing and decryption happen locally. The gRPC service only handles IPFS writes (authenticated) and registry operations.
+
+### Message Flow
+
+1. **Sender** encrypts message content with XChaCha20-Poly1305 (multi-recipient, using X25519 key wrapping)
+2. Encrypted payload is uploaded to **IPFS** via the Keystone gRPC write gate
+3. A small protobuf-encoded pointer (`pf.ptr.v4.Pointer`) is attached as a memo to a **Payment** transaction on the PFTL chain
+4. **Recipient bot** scans the chain for transactions to its address, reads the pointer, fetches the payload from IPFS via public gateways, and decrypts locally
+
+### Encryption
+
+Messages use the same encryption scheme as the pftasks frontend:
+
+- **Content encryption**: XChaCha20-Poly1305 (libsodium)
+- **Key wrapping**: X25519 (Diffie-Hellman key agreement)
+- **Key derivation**: Bot's Ed25519 keypair (from PFTL wallet) is converted to X25519 for encryption
+- **Multi-recipient**: Each message wraps the symmetric key for both sender and recipient, so both parties can decrypt
+
+## Quick Start
+
+### 1. Prerequisites
+
+- Node.js >= 20
+- An MCP-compatible LLM client (Cursor, Claude Desktop, etc.)
+
+### 2. Install
+
+**From npm** (when published):
+```bash
+npx pft-chatbot-mcp
+```
+
+**From source**:
+```bash
+git clone <repo-url>
+cd pft-chatbot-mcp
+npm install
+```
+
+### 3. Configure Your LLM Client
+
+Copy `mcp.json.example` to your LLM client's MCP configuration location.
+
+**If you already have a wallet**, add your seed:
+
+**For Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "pft-chatbot-mcp": {
+      "command": "npx",
+      "args": ["tsx", "src/index.ts"],
+      "env": {
+        "BOT_SEED": "sEdYourBotSeedHere"
+      }
+    }
+  }
+}
+```
+
+**For Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "pft-chatbot-mcp": {
+      "command": "npx",
+      "args": ["tsx", "/absolute/path/to/pft-chatbot-mcp/src/index.ts"],
+      "env": {
+        "BOT_SEED": "sEdYourBotSeedHere"
+      }
+    }
+  }
+}
+```
+
+**If you don't have a wallet yet**, omit the `BOT_SEED` line -- the server will start in setup mode with the `create_wallet` tool available. See [Wallet Setup](#wallet-setup) below.
+
+All other configuration has sensible testnet defaults. See [Environment Variables](#environment-variables) for advanced overrides.
+
+### 4. Wallet Setup
+
+If you need a new wallet, the server can start without a seed. Tell your LLM:
+
+> "Create a new PFTL wallet for my bot"
+
+This calls `create_wallet` and returns your new wallet address and seed. Then:
+
+1. **Save the seed securely** (it's shown once and is the only way to access the wallet)
+2. **Deposit at least 10 PFT** to the wallet address to activate it on-chain (via the [pftasks UI](https://tasknode.postfiat.org) or another wallet)
+3. **Add the seed** to your MCP configuration as `BOT_SEED` and restart
+
+For a detailed walkthrough, see **[docs/WALLET_SETUP.md](docs/WALLET_SETUP.md)**.
+
+### 5. First Run
+
+Once your wallet is configured and activated, tell your LLM:
+
+> "Register my bot as 'My Bot' with description 'A helpful assistant' and capabilities ['text-generation']"
+
+This will:
+1. Prove wallet ownership via Ed25519 challenge-response
+2. Provision an API key (cached locally in `.keystone-api-key`)
+3. Register the bot in the public agent directory
+
+Then try:
+
+> "Scan for new messages"
+
+For a complete working example with tiered responses (text + image based on PFT amount), see **[docs/HELLO_WORLD_BOT.md](docs/HELLO_WORLD_BOT.md)**.
+
+## Tools Reference
+
+### create_wallet
+
+Generates a new PFTL wallet locally. No network connection is required. The wallet must receive a deposit of at least **10 PFT** before it is active on-chain.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `algorithm` | `string` | No | `"ed25519"` | Key algorithm: `"ed25519"` (recommended) or `"secp256k1"` |
+
+**Returns**: JSON with `address` (the r-address), `seed` (family seed -- save this!), `public_key`, `key_algorithm`, activation instructions, and next steps.
+
+**Important**:
+- The seed is displayed once. Copy and store it securely before doing anything else.
+- The wallet does not exist on-chain until it receives at least 10 PFT.
+- This tool is available even when no `BOT_SEED` is configured (setup mode).
+
+---
+
+### scan_messages
+
+Scans recent transactions on the bot's wallet for incoming/outgoing messages. Returns metadata only (no decryption) -- use `get_message` to read content. Returns a `next_cursor` value for pagination/deduplication.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `since_ledger` | `number` | No | - | Only return messages from this ledger index onwards (use `next_cursor` from previous scan) |
+| `limit` | `number` | No | `100` | Max transactions to scan (1-200) |
+| `direction` | `string` | No | `"inbound"` | Filter: `"inbound"`, `"outbound"`, or `"both"` |
+
+**Returns**: JSON object with:
+- `messages` -- array of message objects, each with `tx_hash`, `sender`, `recipient`, `direction`, `amount_drops` (PFT in drops), `amount_pft` (PFT in whole units), `issued_currency` (for non-PFT tokens, or `null`), `cid`, `thread_id`, `is_encrypted`, `ledger_index`, `timestamp_iso`
+- `count` -- number of messages found
+- `next_cursor` -- ledger index to pass as `since_ledger` on the next call (for deduplication)
+
+---
+
+### get_message
+
+Fetches and decrypts a specific message by its transaction hash or IPFS CID. Provide at least one.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `tx_hash` | `string` | No* | - | Transaction hash to look up |
+| `cid` | `string` | No* | - | IPFS CID of the encrypted payload |
+
+*At least one of `tx_hash` or `cid` must be provided.
+
+**Returns**: JSON with `tx_hash`, `cid`, `sender`, `recipient`, `message` (decrypted plaintext), `content_type`, `amount_drops`, `thread_id`, `timestamp`.
+
+---
+
+### send_message
+
+Encrypts a message, uploads to IPFS, and submits a Payment transaction on the PFTL chain with PFT.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `recipient` | `string` | **Yes** | - | Recipient's PFTL r-address |
+| `message` | `string` | **Yes** | - | Message text to send |
+| `content_type` | `string` | No | `"text"` | MIME type of the content |
+| `amount_pft` | `string` | No | - | PFT amount to send (e.g. `"10"` for 10 PFT). Converted to drops automatically. |
+| `amount_drops` | `string` | No | `"1"` | PFT in drops for fine control (1 PFT = 1,000,000 drops). Ignored if `amount_pft` is set. |
+| `attachments` | `array` | No | - | Array of IPFS content to attach (see below) |
+| `reply_to_tx` | `string` | No | - | Transaction hash this replies to |
+| `thread_id` | `string` | No | - | Thread ID to continue a conversation |
+
+Each attachment object: `{ cid: string, content_type: string, filename?: string }`
+
+**Returns**: JSON with `tx_hash`, `cid`, `thread_id`, `recipient`, `amount_pft`, `amount_drops`, `result`.
+
+**Example -- sending an image:**
+
+```
+1. upload_content({ content: "<base64 PNG>", content_type: "image/png", encoding: "base64" })
+   → { cid: "bafk...", uri: "ipfs://bafk..." }
+
+2. send_message({
+     recipient: "rBot...",
+     message: "Here's the chart you requested",
+     attachments: [{ cid: "bafk...", content_type: "image/png", filename: "chart.png" }]
+   })
+```
+
+---
+
+### register_bot
+
+Registers the bot in the Keystone agent registry. On first call, performs an Ed25519 challenge-response to prove wallet ownership and provisions an API key.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `name` | `string` | **Yes** | - | Display name for the bot |
+| `description` | `string` | **Yes** | - | Short description of what the bot does |
+| `capabilities` | `string[]` | **Yes** | - | Capability tags (e.g. `["text-generation", "image-generation"]`) |
+| `url` | `string` | No | - | Bot homepage or documentation URL |
+
+**Returns**: JSON with `agent_id`, `wallet_address`, `name`, `capabilities`, `registered: true`.
+
+---
+
+### search_bots
+
+Searches the public agent registry for other bots by name, description, or capability.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | `string` | No | - | Free-text search (matches name/description) |
+| `capabilities` | `string[]` | No | - | Filter by capability tags |
+| `limit` | `number` | No | `20` | Max results (1-100) |
+
+**Returns**: JSON with `total_count` and `results` array, each containing `agent_id`, `name`, `description`, `wallet_address`, `capabilities`, `relevance_score`.
+
+---
+
+### upload_content
+
+Uploads arbitrary content to IPFS via the authenticated Keystone gRPC write gate. Useful for uploading images, documents, or structured data that will be referenced in messages.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `content` | `string` | **Yes** | - | Content to upload (text, JSON, or base64 for binary) |
+| `content_type` | `string` | **Yes** | - | MIME type (e.g. `"image/png"`, `"application/json"`) |
+| `encoding` | `string` | No | `"utf8"` | `"utf8"` for text or `"base64"` for binary |
+
+**Returns**: JSON with `cid`, `uri` (`ipfs://` URI), `content_type`, `size` (bytes).
+
+---
+
+### get_thread
+
+Fetches all messages in a conversation, either by thread ID or contact address. Optionally decrypts all messages.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `thread_id` | `string` | No* | - | Thread ID to fetch messages for |
+| `contact_address` | `string` | No* | - | Wallet address to fetch all messages with |
+| `limit` | `number` | No | `200` | Max transactions to scan (1-200) |
+| `decrypt` | `boolean` | No | `true` | Whether to decrypt message contents |
+
+*At least one of `thread_id` or `contact_address` must be provided.
+
+**Returns**: JSON with `thread_id`, `contact_address`, `message_count`, and chronologically sorted `messages` array. Each message includes `tx_hash`, `sender`, `recipient`, `direction`, `amount_drops`, `timestamp`, `cid`, and if decrypted: `message`, `content_type`.
+
+## Bot Lifecycle
+
+```
+┌──────────────┐
+│ create_wallet │  Generate a new wallet (if you don't have one)
+│ (optional)    │
+└──────┬───────┘
+       │  deposit ≥ 10 PFT, configure BOT_SEED, restart
+       ▼
+┌─────────────┐
+│  register    │  Prove wallet ownership, get API key, register in directory
+│  (once)      │
+└──────┬──────┘
+       ▼
+┌─────────────┐
+│  scan        │  Poll for new incoming messages
+│  (loop)      │◄──────────────────────────┐
+└──────┬──────┘                            │
+       ▼                                   │
+┌─────────────┐                            │
+│  get_message │  Decrypt and read content │
+└──────┬──────┘                            │
+       ▼                                   │
+┌─────────────┐                            │
+│  process     │  LLM generates response   │
+│  (your logic)│                            │
+└──────┬──────┘                            │
+       ▼                                   │
+┌─────────────┐                            │
+│  send_message│  Encrypt, upload, submit   │
+└──────┬──────┘                            │
+       └───────────────────────────────────┘
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BOT_SEED` | Yes* | - | Wallet family seed or hex seed |
+| `BOT_SEED_FILE` | Yes* | - | Path to file containing the seed (alternative to `BOT_SEED`) |
+| `KEYSTONE_API_KEY` | Auto | - | Auto-provisioned on first `register_bot` call |
+| `PFTL_RPC_URL` | No | `https://rpc.testnet.postfiat.org` | Chain JSON-RPC endpoint |
+| `PFTL_WSS_URL` | No | `wss://rpc.testnet.postfiat.org:6008` | Chain WebSocket endpoint |
+| `IPFS_GATEWAY_URL` | No | `https://pft-ipfs-testnet-node-1.fly.dev` | Primary IPFS gateway for reads |
+| `KEYSTONE_GRPC_URL` | No | `keystone-grpc.postfiat.org:443` | Keystone gRPC service |
+
+*Exactly one of `BOT_SEED` or `BOT_SEED_FILE` is required.
+
+## Security Considerations
+
+### Wallet Seed Handling
+
+The bot's wallet seed is the most sensitive piece of configuration. Here's how it's handled:
+
+1. **The seed never leaves your machine.** All signing and decryption happen in the local MCP server process.
+
+2. **The gRPC service never sees your seed.** Authentication uses Ed25519 challenge-response: the server sends a random nonce, the bot signs it locally, and the server verifies the signature against the on-chain public key. No secret material is transmitted.
+
+3. **Two options for providing the seed:**
+
+   - **`BOT_SEED` in mcp.json env** -- Simple, fine for development. The `.cursor/mcp.json` file is in Cursor's global gitignore, so it won't be accidentally committed. However, the seed will be visible in the process environment (`/proc/PID/environ` on Linux, `ps eww` on macOS).
+
+   - **`BOT_SEED_FILE`** (recommended for production) -- Point to a file with restricted permissions (`chmod 600`). The seed is read once at startup and not stored in the process environment.
+
+     ```bash
+     # Create a seed file with restricted permissions
+     echo "sEdYourSeed" > ~/.pft-bot-seed
+     chmod 600 ~/.pft-bot-seed
+     ```
+
+     ```json
+     {
+       "mcpServers": {
+         "pft-chatbot-mcp": {
+           "command": "npx",
+           "args": ["tsx", "src/index.ts"],
+           "env": {
+             "BOT_SEED_FILE": "/Users/you/.pft-bot-seed"
+           }
+         }
+       }
+     }
+     ```
+
+4. **Use a dedicated bot wallet.** Do not use your personal wallet. Create a new wallet with minimal funds specifically for the bot. The wallet only needs enough PFT for transaction fees.
+
+5. **API key caching.** The provisioned API key is cached in `.keystone-api-key` in the project root with `0600` permissions. Add this file to your `.gitignore`.
+
+### Rate Limits
+
+The Keystone gRPC service enforces per-API-key rate limits:
+- **500 writes/hour** (IPFS uploads, envelope storage)
+- **5,000 reads/hour** (registry lookups, envelope queries)
+
+### On-Chain Identity
+
+Bot registration requires proving control of a PFTL wallet address by:
+1. The wallet must have an active PFT trust line
+2. The bot must sign a challenge nonce with the wallet's Ed25519 key
+3. The signature is verified against the on-chain public key
+
+## Development
+
+```bash
+# Run the MCP server directly
+BOT_SEED=sEdYourSeed npx tsx src/index.ts
+
+# Watch mode (auto-restart on changes)
+BOT_SEED=sEdYourSeed npm run dev
+
+# Type check
+npm run lint
+
+# Build to dist/
+npm run build
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts              # Entry point, MCP server setup, tool registration
+├── version.ts            # Version constants (MCP, Keystone, pf.ptr)
+├── config.ts             # Environment/config loading
+├── chain/
+│   ├── pointer.ts        # Protobuf memo encoding/decoding (pf.ptr.v4 + Keystone)
+│   ├── scanner.ts        # Chain transaction scanning
+│   └── submitter.ts      # Transaction signing and submission
+├── crypto/
+│   ├── keys.ts           # Keypair derivation (Ed25519 → X25519)
+│   ├── encrypt.ts        # Multi-recipient encryption
+│   └── decrypt.ts        # Payload decryption
+├── grpc/
+│   ├── client.ts         # Keystone gRPC client
+│   └── protos/           # Proto definitions (subset of keystone-protocol)
+├── ipfs/
+│   └── gateway.ts        # Direct IPFS gateway reads
+└── tools/
+    ├── create_wallet.ts   # create_wallet tool (no seed required)
+    ├── scan_messages.ts   # scan_messages tool
+    ├── get_message.ts     # get_message tool
+    ├── send_message.ts    # send_message tool
+    ├── register_bot.ts    # register_bot tool
+    ├── search_bots.ts     # search_bots tool
+    ├── upload_content.ts  # upload_content tool
+    └── get_thread.ts      # get_thread tool
+```
+
+## FAQ
+
+**Q: Do I need to run my own IPFS node?**
+No. Reads go through public IPFS gateways. Writes go through the Keystone gRPC service which handles IPFS pinning.
+
+**Q: What chain does this run on?**
+PFTL, a standalone blockchain with PFT as its native currency. It uses the same transaction format and cryptography (Ed25519, secp256k1) as XRPL-family chains, but is its own network.
+
+**Q: Can I use this with Claude Desktop / other MCP clients?**
+Yes. Any MCP-compatible client that supports stdio transport works. See the configuration examples above.
+
+**Q: How do I get a PFTL wallet?**
+Use the `create_wallet` tool -- it works even without an existing seed. Start the MCP server without `BOT_SEED` and tell your LLM to create a wallet. You'll get a new address and seed. Then deposit at least 10 PFT to activate it (via [pftasks](https://tasknode.postfiat.org) or from another wallet), set the seed in your config, and restart. See [docs/WALLET_SETUP.md](docs/WALLET_SETUP.md) for a full walkthrough.
+
+**Q: How much does it cost to send a message?**
+Each message is a Payment transaction on the PFTL chain, which costs a small amount of PFT in fees (typically < 0.001 PFT). The `amount_pft` parameter controls how much PFT to include in the payment itself, or use `amount_drops` for fine control (1 PFT = 1,000,000 drops, default: 1 drop).

package/dist/chain/pointer.d.ts

@@ -0,0 +1,65 @@
+export declare const POINTER_FLAGS: {
+    readonly encrypted: 1;
+    readonly public: 2;
+    readonly ephemeral: 4;
+    readonly tombstone: 8;
+    readonly multipart: 16;
+};
+export type MemoType = "pf.ptr" | "keystone" | "unknown";
+export interface DecodedPfPointer {
+    type: "pf.ptr";
+    cid: string;
+    target: string;
+    kind: string;
+    schema: number;
+    taskId: string;
+    threadId: string;
+    contextId: string;
+    flags: number;
+    isEncrypted: boolean;
+}
+export interface DecodedKeystoneEnvelope {
+    type: "keystone";
+    version: number;
+    contentHash: Buffer;
+    messageType: string;
+    encryption: string;
+    publicReferences: Array<{
+        contentHash: Buffer;
+        groupId: string;
+        referenceType: string;
+        annotation: string;
+    }>;
+    message: Buffer;
+    metadata: Record<string, string>;
+}
+export type DecodedMemo = DecodedPfPointer | DecodedKeystoneEnvelope | null;
+/**
+ * Identify the memo type from hex-encoded MemoType and MemoFormat fields.
+ */
+export declare function identifyMemoType(memoTypeHex: string, memoFormatHex: string): MemoType;
+/**
+ * Decode a pf.ptr.v4.Pointer from hex-encoded MemoData.
+ */
+export declare function decodePfPointer(memoDataHex: string): Promise<DecodedPfPointer>;
+/**
+ * Decode a KeystoneEnvelope from hex-encoded MemoData.
+ */
+export declare function decodeKeystoneEnvelope(memoDataHex: string): Promise<DecodedKeystoneEnvelope>;
+/**
+ * Build a pf.ptr.v4.Pointer memo for sending messages.
+ * Returns hex-encoded memo fields ready for PFTL transaction.
+ */
+export declare function buildPfPointerMemo(input: {
+    cid: string;
+    kind?: string;
+    schema?: number;
+    threadId?: string;
+    contextId?: string;
+    flags?: number;
+}): Promise<{
+    memoTypeHex: string;
+    memoFormatHex: string;
+    memoDataHex: string;
+}>;
+//# sourceMappingURL=pointer.d.ts.map

package/dist/chain/pointer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.d.ts","sourceRoot":"","sources":["../../src/chain/pointer.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,aAAa;;;;;;CAMhB,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,KAAK,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,uBAAuB,GAAG,IAAI,CAAC;AAmB5E;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,GACpB,QAAQ,CAcV;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAiB3B;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,uBAAuB,CAAC,CAwBlC;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IACV,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAwBD"}

package/dist/chain/pointer.js

@@ -0,0 +1,116 @@
+import protobuf from "protobufjs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROTO_DIR = resolve(__dirname, "..", "grpc", "protos");
+// Memo type/format constants (hex-encoded)
+const PF_PTR_MEMO_TYPE_HEX = "70662e707472"; // "pf.ptr"
+const PF_PTR_MEMO_FORMAT_HEX = "7634"; // "v4"
+const KEYSTONE_MEMO_TYPE_HEX = "6b657973746f6e65"; // "keystone"
+const KEYSTONE_MEMO_FORMAT_HEX = "7631"; // "v1"
+// Pointer flag bitmask (from pftasks)
+export const POINTER_FLAGS = {
+    encrypted: 0x01,
+    public: 0x02,
+    ephemeral: 0x04,
+    tombstone: 0x08,
+    multipart: 0x10,
+};
+let pfPointerType = null;
+let keystoneEnvelopeType = null;
+async function loadProtos() {
+    if (pfPointerType && keystoneEnvelopeType)
+        return;
+    const pfRoot = await protobuf.load(resolve(PROTO_DIR, "pf/ptr/v4/pointer.proto"));
+    pfPointerType = pfRoot.lookupType("pf.ptr.v4.Pointer");
+    const ksRoot = await protobuf.load(resolve(PROTO_DIR, "keystone/v1/core/envelope.proto"));
+    keystoneEnvelopeType = ksRoot.lookupType("keystone.v1.core.KeystoneEnvelope");
+}
+/**
+ * Identify the memo type from hex-encoded MemoType and MemoFormat fields.
+ */
+export function identifyMemoType(memoTypeHex, memoFormatHex) {
+    if (memoTypeHex === PF_PTR_MEMO_TYPE_HEX &&
+        memoFormatHex === PF_PTR_MEMO_FORMAT_HEX) {
+        return "pf.ptr";
+    }
+    if (memoTypeHex === KEYSTONE_MEMO_TYPE_HEX &&
+        memoFormatHex === KEYSTONE_MEMO_FORMAT_HEX) {
+        return "keystone";
+    }
+    return "unknown";
+}
+/**
+ * Decode a pf.ptr.v4.Pointer from hex-encoded MemoData.
+ */
+export async function decodePfPointer(memoDataHex) {
+    await loadProtos();
+    const bytes = Buffer.from(memoDataHex, "hex");
+    const decoded = pfPointerType.decode(bytes);
+    return {
+        type: "pf.ptr",
+        cid: decoded.cid || "",
+        target: decoded.target || "TARGET_UNSPECIFIED",
+        kind: decoded.kind || "CONTENT_KIND_UNSPECIFIED",
+        schema: decoded.schema || 0,
+        taskId: decoded.taskId || "",
+        threadId: decoded.threadId || "",
+        contextId: decoded.contextId || "",
+        flags: decoded.flags || 0,
+        isEncrypted: (decoded.flags & POINTER_FLAGS.encrypted) !== 0,
+    };
+}
+/**
+ * Decode a KeystoneEnvelope from hex-encoded MemoData.
+ */
+export async function decodeKeystoneEnvelope(memoDataHex) {
+    await loadProtos();
+    const bytes = Buffer.from(memoDataHex, "hex");
+    const decoded = keystoneEnvelopeType.decode(bytes);
+    return {
+        type: "keystone",
+        version: decoded.version || 1,
+        contentHash: decoded.contentHash
+            ? Buffer.from(decoded.contentHash)
+            : Buffer.alloc(0),
+        messageType: decoded.messageType || "MESSAGE_TYPE_UNSPECIFIED",
+        encryption: decoded.encryption || "ENCRYPTION_MODE_UNSPECIFIED",
+        publicReferences: (decoded.publicReferences || []).map((ref) => ({
+            contentHash: ref.contentHash
+                ? Buffer.from(ref.contentHash)
+                : Buffer.alloc(0),
+            groupId: ref.groupId || "",
+            referenceType: ref.referenceType || "CONTEXT_REFERENCE_TYPE_UNSPECIFIED",
+            annotation: ref.annotation || "",
+        })),
+        message: decoded.message ? Buffer.from(decoded.message) : Buffer.alloc(0),
+        metadata: decoded.metadata || {},
+    };
+}
+/**
+ * Build a pf.ptr.v4.Pointer memo for sending messages.
+ * Returns hex-encoded memo fields ready for PFTL transaction.
+ */
+export async function buildPfPointerMemo(input) {
+    await loadProtos();
+    const payload = {
+        cid: input.cid,
+        target: "TARGET_CONTENT_BLOB",
+        kind: input.kind || "CHAT",
+        schema: input.schema || 1,
+        threadId: input.threadId || "",
+        contextId: input.contextId || "",
+        flags: input.flags ?? POINTER_FLAGS.encrypted,
+    };
+    const err = pfPointerType.verify(payload);
+    if (err)
+        throw new Error(`Invalid pointer payload: ${err}`);
+    const message = pfPointerType.create(payload);
+    const bytes = pfPointerType.encode(message).finish();
+    return {
+        memoTypeHex: PF_PTR_MEMO_TYPE_HEX,
+        memoFormatHex: PF_PTR_MEMO_FORMAT_HEX,
+        memoDataHex: Buffer.from(bytes).toString("hex"),
+    };
+}
+//# sourceMappingURL=pointer.js.map

package/dist/chain/pointer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.js","sourceRoot":"","sources":["../../src/chain/pointer.ts"],"names":[],"mappings":"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"}