@motebit/protocol

Wire-format types for the Motebit agent identity standard. Zero dependencies. Pure TypeScript.

Why this exists

Motebit is an open protocol for sovereign AI agents — persistent cryptographic identity, signed execution receipts, verifiable credentials, and trust algebra. This package is the type-level contract any system needs to interoperate with motebits: verify an agent's identity, validate an execution receipt, issue a reputation credential, compute a trust score, settle a payment. Binding to these types instead of a BSL implementation is what makes an alternative runtime possible.

Install

npm install @motebit/protocol

Example

import type { MotebitId, ExecutionReceipt } from "@motebit/protocol";
import { asMotebitId, PLATFORM_FEE_RATE } from "@motebit/protocol";

// Branded IDs — compile-time guardrail against mixing ID spaces.
const agent: MotebitId = asMotebitId("01234567-89ab-cdef-0123-456789abcdef");

// Receipts are pure data. Pair with @motebit/crypto to sign or verify.
function auditsPass(receipt: ExecutionReceipt): boolean {
  return receipt.status === "completed" && receipt.tools_used.length > 0;
}

// Protocol constants.
const relayFee = PLATFORM_FEE_RATE; // 0.05 — the reference relay's default fee rate; relays configure their own.

What's included

• Branded ID types — MotebitId, DeviceId, GoalId, AllocationId, etc.
• Identity — MotebitIdentity, KeySuccessionRecord, DeviceRegistration
• Execution receipts — ExecutionReceipt with nested delegation chains
• Credentials — W3C VC 2.0 types (ReputationCredentialSubject, TrustCredentialSubject)
• Routing transcript — RoutingDecisionTranscript + TranscriptCandidate + ROUTING_TRANSCRIPT_SPEC_ID (motebit/[email protected]): the delegator-signed record of why a worker won a paid hire — frozen candidate set with per-candidate posterior reads and draws, decision parameters as literals, seed provenance, pinned algorithm_version. Envelope law in @motebit/crypto; faithfulness recomputation in @motebit/semiring (source-available, not published to npm). See spec/routing-transcript-v1.md.
• Settlement — BudgetAllocation, SettlementRecord, PLATFORM_FEE_RATE; computeP2pFeeMicro(netCostMicro, feeRate) for the canonical P2P fee-leg amount in micro-units (gross - net) — the relay's proof validator and the delegator client building the proof share it so the fee can't drift; computeFederatedFeeSplit(budgetMicro, feeRate) for the cross-operator fee-from-budget split (origin-fee / executor-fee / worker-net legs, spec §7.1), shared the same way; roundSettlementSplitMicro(netExact, feeExact) → SettlementSplitMicro for rounding a settlement's two legs to whole micro-units without breaking conservation (net + fee still equals the gross) — rounding each leg independently over-states the fee by one micro on 5% of grosses, and the recorded pair is signed dispute-grade history feeding the treasury reconciler, so the relay-custody lane consumes this rather than Math.round per leg; SettlementMode closed union ("relay" | "p2p") with ALL_SETTLEMENT_MODES for iteration and isSettlementMode for narrowing wire-format payloads pulled from discovery / peer-negotiation responses; SettlementAsset closed union ("USDC" at sub-phase A) with ALL_SETTLEMENT_ASSETS for iteration and isSettlementAsset for narrowing; EvalKind closed union ("verification_audit") with ALL_EVAL_KINDS for iteration and isEvalKind for fail-closed wire intake of EvalAttestation.eval_kind — the measurement-family discriminator of the signed third-party-measurement artifact (eleventh registered registry; see spec/eval-attestation-v1.md) — the typed vocabulary of stablecoin assets the protocol clears settlement in; SovereignRail.asset is structurally tightened to this union so a peer announcing an unknown asset fails closed. Guest-rail capability marker interfaces + type guards — GuestRail carries supportsDeposit / supportsWithdraw / supportsBatch discriminants; DepositableGuestRail / WithdrawableGuestRail / BatchableGuestRail add the corresponding methods; isDepositableRail / isWithdrawableRail / isBatchableRail narrow at the call site. The marker on WithdrawableGuestRail is the structural enforcement of the off-ramp doctrine: rails that don't opt in (e.g., Bridge, treasury-only) cannot drive user-facing withdrawals because withdraw does not exist on the base type
• Sovereign wallet port — SovereignWalletRail (extends SovereignRail with send / isAvailable) + SovereignSendResult; the rail interface the interior consumes so a runtime can use a sovereign rail without depending on a settlement-rail provider package
• Encoding — base58Encode, a pure chain-agnostic base58btc codec (Bitcoin alphabet; the encoding behind Solana address derivation), and hexToBytes32, a fail-closed fixed-width hex decoder (the single shared prelude to the identity-binding checks in the runtime and wallet-solana); siblings to the money converters
• Trust algebra — semiring operations for delegation-chain trust computation
• Policy — ToolDefinition, PolicyDecision, RiskLevel, SensitivityLevel (the 5-tier privacy ladder, the most load-bearing closed registry; ALL_SENSITIVITY_LEVELS for iteration, isSensitivityLevel for narrowing unknown payloads, rankSensitivity / maxSensitivity / sensitivityPermits for the algebra; CONTEXT_SAFE_SENSITIVITY for the external-egress-safe tier set)
• Event-log vocabulary — EventType closed enum spanning identity / memory / goals / approvals / plans / consolidation / co-browse / agents; ALL_EVENT_TYPES for iteration, isEventType for narrowing wire-format payloads pulled from sync peers or federation
• Memory provenance — MemorySource closed registry (user_stated / agent_inferred / tool_derived / peer_agent / consolidation_derived): who contributed a remembered fact, assigned by the forming code path — never the model, never the peer. ALL_MEMORY_SOURCES for iteration, isMemorySource for narrowing inbound wire values (unknown degrades to undefined, never fails open to a trusted tier), MEMORY_SOURCE_MARKERS / MEMORY_SOURCE_MARKER_UNKNOWN for the canonical [from:X] render labels (Record<MemorySource, string> — a registry append without a marker is a compile error). AttributedMemoryCandidate makes unattributed formation a compile error at the entry points. See docs/doctrine/memory-provenance.md
• Agent revocation — the operator's de-list power, made sovereign-verifiable: AgentRevocationRecord / AgentRevocationFeed (signed under AGENT_REVOCATION_SUITE, spec id AGENT_REVOCATION_SPEC_ID) are the wire types for a relay's public, append-only moderation history at GET /api/v1/agents/revocations; AgentRevocationReason closed registry (ALL_AGENT_REVOCATION_REASONS for iteration, isAgentRevocationReason for narrowing — operator_test_cleanup / spam / abuse / malware / policy_violation / dmca / reinstated) keeps the feed legible. De-list, never de-identify; verify with @motebit/state-export-client::verifyAgentRevocationFeed. See spec/agent-revocation-v1.md
• Commitment bond — an agent's anti-sybil staked signal: BondCommitment (spec id BOND_COMMITMENT_SPEC_ID) is a self-signed proof-of-funds at the agent's OWN sovereign Solana address — bonded_address MUST equal deriveSolanaAddress(bonded_public_key), so one wallet can't back many identities. isBondCommitment narrows inbound wire values (shape only — the cryptographic signature + the address binding are @motebit/crypto's verifyBondCommitment). RPC-verified, never custodied; phase 1 is a signal, NOT collateral / escrow / recourse. See spec/bond-v1.md and docs/doctrine/commitment-bond.md
• Content provenance — ContentArtifactType closed registry of artifact_type values for the C2PA-shape ContentArtifactManifest (the manifest type itself ships in @motebit/crypto; protocol owns the registry); named constants per category, incl. SETTLEMENT_SUMMARY_ARTIFACT for the per-peer economic projection a relay emits at GET /api/v1/agents/:motebitId/settlements (wire body SettlementSummaryExport / SettlementSummaryPeer / SettlementSummaryUnattributed). The money side of the first-person trust graph — a materialized projection over the signed settlement ledger, never a denormalized balance; verify with @motebit/state-export-client::verifiedSettlementSummaryFetch
• Storage adapters — pluggable persistence contracts for any backend
• Cryptosuite registry — SuiteId union for crypto-agile wire artifacts
• Token-audience registry — TokenAudience closed union of aud claim values for the audience-bound signed-token primitive (ALL_TOKEN_AUDIENCES for iteration, isTokenAudience for narrowing); named constants per audience — task routing (TASK_SUBMIT_AUDIENCE, TASK_QUERY_AUDIENCE, TASK_RESULT_AUDIENCE), agent-registry reads (MARKET_LISTING_AUDIENCE, MARKET_QUERY_AUDIENCE, CREDENTIALS_AUDIENCE, CREDENTIALS_PRESENT_AUDIENCE), and incl. RUNTIME_ATTACH_AUDIENCE — the machine-local frontend→coordinator attach handshake on the runtime-host socket, verified by the local coordinator only and never accepted by a relay or any network verifier
• Merkle tree-hash registry — MerkleTreeVersion closed union (RFC 6962 §2.1 leaf/node domain separation as an agility axis) with MERKLE_TREE_VERSION_REGISTRY + ALL_MERKLE_TREE_VERSIONS for iteration, isMerkleTreeVersion / getMerkleTreeVersionEntry for narrowing/lookup, and DEFAULT_MERKLE_TREE_VERSION — the absent ⇒ v1 downgrade-safety default for a proof's optional tree_hash_version field
• Evidence provenance — EvidenceRef (the verdict's evidenceBasis element) + an optional EvidenceProvenance ({ digest, projection?, projectionClass?, span, locator?, binding? }) make a verdict's evidence axis re-verifiable down to the primary record — verifiable-locality extended from signatures to EVIDENCE. DigestAlgorithm (sha-256 today, hashed-not-signed so it rides its own role, not SuiteId) with ALL_DIGEST_ALGORITHMS for iteration and isDigestAlgorithm for narrowing. ProjectionClass (spec-reproducible | tool-pinned) names a present projection's assurance class — independently reimplementable from spec (§7) vs reproducible only by the recipe's content-addressed pinned tool (§7-tool); absent ⇒ spec-reproducible, so the weaker class is opt-in. ALL_PROJECTION_CLASSES iterates it and isProjectionClass narrows. Re-checked by @motebit/crypto::verifyEvidenceProvenance (the named span is an exact substring of projection(bytes) content-addressed by digest; presence, never truth) — the class is carried-but-law-advisory, the assurance level the consumer policies on. See docs/doctrine/evidence-provenance.md
• Accrual basis — the leverage register of the felt interior, the typed shape of "more capable over time" felt as an act drawing on accrued state. AccrualKind (closed local union — recalled_memory / trust_edge / consolidated_fact / prior_approval_pattern / standing_delegation) with ALL_ACCRUAL_KINDS for iteration, isAccrualKind for narrowing locally-re-read values, and ACCRUAL_KIND_MARKERS (Record<AccrualKind, string> — a registry append without a render anchor is a compile error). AccrualBasis ({ kind, sourceRef, sensitivity }) is the leverage moment an act carries when accrued state shaped it — PRODUCED by the accrual code path, never model-authored (the honesty floor); AccrualAttributed is the optional carrier (absence = fail-closed, no attribution). Owner-facing and never synced, so a structural-lock union rather than a registered wire registry. See docs/doctrine/felt-accumulation.md
• Auto-router registry — TaskShape closed union (ALL_TASK_SHAPES, isTaskShape) for the model-selection primitive; named constants QUICK_TASK_SHAPE, CHAT_TASK_SHAPE, REASONING_TASK_SHAPE, CODE_TASK_SHAPE, RESEARCH_TASK_SHAPE, CREATIVE_TASK_SHAPE, MATH_TASK_SHAPE. Paired with ProviderCapability + RoutingConstraint + RoutingDecision types consumed by @motebit/policy::dispatchRouting (source-available, not published to npm)

Product-level types (state vectors, creature behavior, rendering spec) live in @motebit/sdk, which re-exports everything here plus the product vocabulary.

Related

• @motebit/sdk — superset with product types for building on Motebit
• @motebit/crypto — sign and verify every artifact this package types
• @motebit/verifier — offline third-party verifier library
• @motebit/verify — the canonical motebit-verify CLI
• create-motebit — scaffold a signed agent identity
• motebit — reference runtime and operator console (BUSL-1.1)
• Motebit docs — protocol and developer documentation

License

Apache-2.0 — see LICENSE.

"Motebit" is a trademark. The Apache License grants rights to this software, not to any Motebit trademarks, logos, or branding. You may not use Motebit branding in a way that suggests endorsement or affiliation without written permission.