Overview
This AIP defines prefixes in the Action Codes Protocol as a trust layer enabling branded, verifiable, and auditable prefixes while keeping user UX simple (prefixless codes). Key goals:- Ensure prefix authenticity and authority verification
- Enforce metadata integrity with signatures and hashes
- Support verifier-based approval with admin governance
- Enable dynamic fees and refunds
- Fully cross-chain ready and relayer-agnostic
Motivation
Prefixes provide namespaces, trust branding, and metadata routing in the Action Codes Protocol:- Allow apps, wallets, and relayers to verify code authenticity and trust
- Enable branding and metadata routing for organizations
- UX is simple: users enter prefixless codes; prefixes exist only for trust verification
- Cryptographically auditable and ready for governance
Specification
Prefix Structure
- Prefix: 3–12 uppercase alphanumeric characters
- PrefixAccount: On-chain representation of a registered prefix
- Purpose: Provide canonical trust for relayers/wallets and link prefix to owner, metadata, and fee reference
PrefixAccount Fields
| Field | Type | Description |
|---|---|---|
prefix | string | Uppercase alphanumeric prefix (3–12 chars) |
owner_pubkey | pubkey | Main wallet controlling prefix |
authority_keys | pubkey[] | Keys authorized to generate / sign codes for this prefix |
metadata_uri | string | URI to JSON metadata following Prefix Metadata Schema v1 |
metadata_hash | [u8;32] | SHA-256 hash of metadata JSON |
status | enum | pending, active, rejected, inactive |
created_at | u64 | Submission timestamp |
updated_at | u64 | Last update timestamp |
expiry_at | u64 | Expiry timestamp for pending submissions (max 14 days) |
bump | u8 | PDA bump for on-chain account |
authority_keysallow multiple servers, relayer programs, or delegated signing keys- Prefixes are validated against metadata + hash with Ed25519 signatures
Prefix Registration Flow
1. Submission (On-Chain)
- Anyone can submit a prefix by:
- Prefix name
- Owner pubkey
- Metadata URI (HTTPS/IPFS)
- Metadata hash (32 bytes)
- Authority keys (up to 10)
- Fee is paid immediately to prevent spam
- Owner must provide Ed25519 signature over
metadata_hash - Status =
pending, withexpiry_atset (max 14 days)
2. Verification
- Only registered verifiers can approve / reject
- Verifier checks:
- Metadata validity (schema v1)
- Brand / ownership criteria (optional off-chain checks)
- Status updated:
approved→ becomesactiverejected→ refund available
3. Updates
- Metadata updates: require new URI, hash, and Ed25519 signature
- Authority keys updates: owner may add/remove (max 10, no duplicates)
- Status transitions: admin may deactivate/reactivate prefixes
4. Refunds & Expiry
- If rejected or expired → owner can claim refund
- Active prefixes never expire (only pending ones have expiry)
FeeRegistry
| Field | Type | Description |
|---|---|---|
current_fee | u64 | Fee in lamports (SOL smallest unit) |
updated_at | u64 | Timestamp of last update |
admin_pubkey | pubkey | Admin / DAO wallet pubkey |
paused | bool | If true, submissions are disabled |
- Fees are paid on submission
- Refunds possible for rejected/expired
- Collected into Treasury PDA
Verifiers List
| Field | Type | Description |
|---|---|---|
verifier_pubkey | pubkey | Wallet authorized to approve / reject prefix |
added_at | u64 | Timestamp verifier added |
removed_at | u64 | Optional removal timestamp |
- Multiple verifiers supported
- Admin adds/removes verifiers
Prefix Metadata Schema v1
All prefix metadata must conform to the Prefix Metadata Schema v1: Required fields:title: Source of the action request (brand, app, or person) - max 50 charsicon: HTTPS/IPFS URL to icon image (SVG, PNG, or WebP)description: Info about the action - max 200 charslabel: Text for action button (verb + max 5 words) - max 30 charsintentCategories: Array of action categories (payment, stake, vote, etc.)contact: Object with key-value pairs (must includeemail)
website: Official websiteschemaVersion: Must be “1”
- On submission, metadata hash must match off-chain JSON
- Verifiers validate JSON matches schema v1
- Invalid metadata → rejection
Code Usage & Verification
User Side
- Users enter prefixless codes (e.g., 12345678)
- Prefix is metadata-only trust anchor
Relayer / Wallet Verification
- Fetch PrefixAccount for
pre=PREFIX - Verify:
status = active- Metadata hash matches JSON at
metadata_uri - Code signature matches any key in
authority_keys
- Optional: check metadata fields (categories, brand, etc.)
Security & Anti-Spam
- Fee on submission prevents spam
- Ed25519 signature ensures prefix-owner control
- Expiry cleans up abandoned submissions
- Max authority keys (10) prevents abuse
- Admin pause/deactivate/recover mechanisms
Status Transitions
| From | To | Trigger | Who |
|---|---|---|---|
| Pending | Active | Approve | Verifier |
| Pending | Rejected | Reject | Verifier |
| Pending | Closed | Refund | Owner |
| Active | Inactive | Deactivate | Admin |
| Inactive | Active | Reactivate | Admin |
| Rejected | Closed | Refund | Owner |
Key Principles
- Users never see prefixes: UX = one-time code entry
- Prefix = trust anchor only: verified by authority_keys
- Immediate fee on submission: anti-spam and refundable if rejected/expired
- Verifiers validate metadata + hash for integrity
- Auditability via events: logs for every action (submit, approve, reject, update, refund)
- Cross-chain ready: works across relayers/wallets
- Authority keys enable delegated backend signing
Notes
- Metadata is off-chain, anchored via hash on-chain
- Admin is managed via multisig (Squads recommended)
- Fully permissionless: anyone can submit, verifiers/admins gate activation
- SDK provides metadata validation helpers, account fetchers, and transaction builders