> ## Documentation Index
> Fetch the complete documentation index at: https://docs.actioncodes.org/llms.txt
> Use this file to discover all available pages before exploring further.

# AIP-4: Prefix System

> Defines Code Prefix System

## 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                            |

**Notes:**

* `authority_keys` allow 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`, with `expiry_at` set (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` → becomes `active`
  * `rejected` → 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 chars
* `icon`: HTTPS/IPFS URL to icon image (SVG, PNG, or WebP)
* `description`: Info about the action - max 200 chars
* `label`: Text for action button (verb + max 5 words) - max 30 chars
* `intentCategories`: Array of action categories (payment, stake, vote, etc.)
* `contact`: Object with key-value pairs (must include `email`)

**Optional fields:**

* `website`: Official website
* `schemaVersion`: Must be "1"

**Schema validation:**

* 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

1. Fetch PrefixAccount for `pre=PREFIX`
2. Verify:
   * `status = active`
   * Metadata hash matches JSON at `metadata_uri`
   * Code signature matches any key in `authority_keys`
3. Optional: check metadata fields (categories, brand, etc.)

**Cross-chain ready**: PrefixAccount + authority keys validate codes from any blockchain relayer

### 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

1. **Users never see prefixes**: UX = one-time code entry
2. **Prefix = trust anchor only**: verified by authority\_keys
3. **Immediate fee on submission**: anti-spam and refundable if rejected/expired
4. **Verifiers validate metadata + hash** for integrity
5. **Auditability via events**: logs for every action (submit, approve, reject, update, refund)
6. **Cross-chain ready**: works across relayers/wallets
7. **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