snap-protocol
npx skills add https://github.com/williampenrose/snap-protocol --skill snap-protocol
Agent 安装分布
Skill 文档
SNAP Protocol
Decentralized agent-to-agent communication with self-sovereign identity.
Identity
Every agent is identified by a Bitcoin P2TR (Pay-to-Taproot) address derived from a private key using BIP-341 taproot tweak.
P2TR address rules:
- Exactly 62 characters
- Prefix:
bc1p(mainnet) ortb1p(testnet) - Bech32m encoded, witness version 1
- Encodes the BIP-341 tweaked output key (not the internal key)
Key derivation flow:
Private Key (32 bytes)
âââ Internal Key (P) â hex pubkey (used by Nostr)
âââ Internal Key (P) â Taproot Tweak â Output Key (Q) â Bech32m â P2TR address
Important: publicKeyToP2TR() and p2trToPublicKey() are NOT inverses. The taproot tweak is irreversible â you cannot recover the Nostr pubkey from a P2TR address.
Message Format
Every SNAP message is a JSON object with these fields:
| Field | Type | Description |
|---|---|---|
id |
string | Unique message ID (1-128 chars, [a-zA-Z0-9_-]) |
version |
string | Protocol version, must be "0.1" |
from |
string | Sender P2TR address |
to |
string | Recipient P2TR address |
type |
string | request, response, or event |
method |
string | Method name (e.g. message/send) |
payload |
object | Method-specific data (max 1 MB, max depth 10) |
timestamp |
integer | Unix seconds (UTC), must be within ±60s of current time |
sig |
string | 128 hex chars (64-byte BIP-340 Schnorr signature, signs with tweaked key) |
Authentication
Messages are signed using BIP-340 Schnorr signatures with the taproot-tweaked private key. The signature covers a canonical JSON serialization of all message fields (excluding sig).
Verification steps:
- Extract tweaked output key Q from the
fromP2TR address - Reconstruct canonical signing payload from message fields
- Verify BIP-340 Schnorr signature against Q
Methods
| Method | Type | Description |
|---|---|---|
message/send |
request-response | Single message exchange |
message/stream |
streaming | Streaming response (chunks) |
tasks/send |
request-response | Create a new task |
tasks/get |
request-response | Get task status |
tasks/cancel |
request-response | Cancel a running task |
tasks/resubscribe |
streaming | Resume a task stream |
agent/card |
request-response | Get agent’s capability card |
agent/ping |
request-response | Health check |
Task States
submitted â working â completed
â failed
â canceled
â input_required â working (after user responds)
| State | Description |
|---|---|
submitted |
Queued, not yet started |
working |
Currently processing |
input_required |
Waiting for user input |
completed |
Finished successfully |
failed |
Finished with error |
canceled |
Canceled by user |
Agent Card
An Agent Card describes an agent’s identity, capabilities, endpoints, and skills. Published as a Nostr replaceable event (kind 31337) for discovery.
Required fields: name, description, version, identity (P2TR), skills, defaultInputModes, defaultOutputModes.
Optional fields: endpoints (HTTP/WS URLs), nostrRelays, protocolVersion, capabilities (streaming, push), provider, trust, iconUrl.
Critical Constraints
| Field | Rule |
|---|---|
| P2TR address | Exactly 62 chars, prefix bc1p or tb1p |
| Message ID | 1-128 chars, [a-zA-Z0-9_-] only |
| Timestamp | Unix seconds, ±60s from current time |
| Signature | 128 lowercase hex chars (64-byte Schnorr, BIP-340) |
| Version | Must be "0.1" |
| Payload | Max 1 MB serialized, max depth 10 |
| Network | from and to must be same network (both mainnet or both testnet) |
For complete field constraints, see references/constraints.md.
Error Codes
| Range | Category |
|---|---|
| 1xxx | Task/Message errors (invalid format, unknown method) |
| 2xxx | Authentication errors (bad signature, expired timestamp, replay) |
| 3xxx | Discovery errors (agent not found, invalid card) |
| 4xxx | Transport errors (timeout, connection refused) |
| 5xxx | System errors (rate limit, maintenance) |
Errors are returned in the message payload, not as HTTP status codes. All SNAP responses use HTTP 200.
For complete error code listing, see references/error-codes.md.
Nostr Integration
Default relay: wss://snap.onspace.ai
| Kind | Type | Purpose |
|---|---|---|
| 31337 | Replaceable (NIP-33) | Agent Card publication |
| 21339 | Ephemeral (NIP-16) | Real-time encrypted SNAP message (default) |
| 4339 | Regular (storable) | Persistent/offline SNAP message |
Messages are encrypted end-to-end using NIP-44. The relay only sees ciphertext. By default, real-time messages use ephemeral kind 21339 (not stored). Set persist: true for storable kind 4339 (offline retrieval).
For Nostr event structure and offline messaging, see references/nostr-transport.md.
SDK Implementations
| Language | Skill |
|---|---|
| TypeScript | typescript/SKILL.md |