@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
• Machine roster — which machines a motebit runs unattended work on, as a set the sovereign signs and a relay only transports: HostEnrollment and HostRetirement (spec id HOST_ROSTER_SPEC_ID). Each entry is identified by the SHA-256 of its signed body — every field except signature, never the whole artifact, because a signature's spelling is the one thing nothing signs. The roster is every machine with an enrolment no retirement ends, so merging copies is set union and removal is terminal. Both bodies carry a signed domain tag (HOST_ENROLLMENT_TYPE / HOST_RETIREMENT_TYPE) and are frozen for major version 1. A device_id is a label under the motebit's one key, not a principal — the roster's job is completeness (an offline machine is still a line), never security between machines. isHostEnrollment / isHostRetirement narrow inbound wire values (shape only — signatures are @motebit/crypto's verifyHostEnrollment / verifyHostRetirement, and membership is verifyHostRoster against a key chain the consumer verified). See docs/doctrine/machine-roster.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, and TASK_DISPATCH_AUDIENCE — the relay-signed per-task admission artifact a priced worker requires before running motebit_task; mid = worker, sub = relay task id), 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
• Run evidence — RunEvidenceEntry + RunEvidenceSink keep the pointers a single unattended run produced, so a returning owner can re-check what it read rather than take its word. A pointer is minted by the code path that retrieved the bytes, never by a model summarizing afterwards. RunEvidenceWithheldReason (credential_in_span | credential_in_source, with ALL_RUN_EVIDENCE_WITHHELD_REASONS for iteration and isRunEvidenceWithheldReason for narrowing) marks a row that records a REFUSAL rather than a pointer: the guard that declines to store credential-class content writes what it declined and why, carrying no digest, no span and no source. Without it a refusal and a tool that retrieved nothing were the same absence — the ambiguity this vocabulary exists to remove, reproduced inside the guard meant to uphold it
• 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.