← Snippbot Architecture

Singularity Marketplace — System Architecture

Permission-first ecosystem · Publish · Vet · Transact · Enforce
Hover any layer to expand · hover a component for details · 1All 2Reveal All
①
Portal Layer
User-facing surface — browse, install, publish, transact
React 18
8 user actions
Browse & Search UI
/marketplace

Browse & Search UI

The storefront — paginated cards, filters, trending.

  • Full-text search · category tree · tag chips
  • Sort: trending · newest · top-rated · most-installed
  • Artifact-type tabs (skill · tool · agent · workflow · channel)
Package Detail Page
readme · changelog · deps

Package Detail

Everything you need to know before installing.

  • README · screenshots · demo video embed
  • Permissions requested · audit summary
  • Version history · changelog · dependencies
Install Flow
consent · audit · verify

Install Flow

Four-step consent path — nothing runs until you approve.

  • Show manifest permissions · trust level · audit findings
  • Per-permission consent checkboxes
  • Verify signature · extract · register
Publisher Dashboard
/publisher

Publisher Dashboard

Your listings, analytics, and revenue.

  • Version history per package
  • Install analytics · ratings · reviews feed
  • Revenue & escrow balance · payout requests
Installed Manager
/skills · /installed

Installed Manager

Your library — enable, update, revoke.

  • Enable/disable per package · per agent
  • Pin to version or auto-update
  • Revoke permissions at runtime (fail-closed on next call)
Wallet View
/snipp

Wallet View

Your SNIPP balance, transactions, and pending claims.

  • Per-agent balances · consolidated user total
  • Transaction history · receipt export
  • Address QR for transfers
Reviews & Ratings
verified-only

Reviews & Ratings

Only verified installers can leave a review.

  • 1-5 stars + written review · edit within 7 days
  • Moderation queue for abuse reports
  • Publisher responses threaded below
Disputes Portal
/disputes

Disputes Portal

File or respond to a dispute on a work contract.

  • Dispute types: INCOMPLETE · QUALITY · DEADLINE
  • Evidence upload · reputation weight on resolution
  • Auto-timeout → neutral arbitrator
②
Discovery Engine
Search · categorization · trending · recommendations
FTS5
trending · embeddings
Full-Text Search
FTS5 · BM25

Full-Text Search

Same SQLite FTS5 engine used by agent memory.

  • Searches name · description · readme · tags
  • BM25 scoring with recency boost
  • Phrase · boolean · prefix wildcards
Category Tree
hierarchical tags

Category Tree

Curated hierarchy — enforced taxonomy keeps navigation coherent.

  • Max 10 top-level categories
  • Publisher picks 1-3 at submission
  • Moderators can re-classify
Trending Index
rolling 7/30/90d

Trending Index

Recency-weighted install rate + rating momentum.

  • Rolling 7/30/90-day windows
  • Prevents stale "all-time popular" dominance
  • Separate trending feeds per category
Recommendations
collaborative filter

Recommendations

"Users who installed X also installed Y" — co-installation graph.

  • Lightweight collaborative filter
  • Cold-start via tag similarity
  • Privacy: aggregate-only, no user tracking
Semantic Search
MiniLM 384d

Semantic Search

Vector search over package descriptions for fuzzy-intent queries.

  • HNSW index over MiniLM embeddings
  • Fallback when keyword search returns nothing
  • Hybrid RRF with keyword results
③
Vetting Pipeline
Every package audited before it ever runs — 43 static checks + deps
43 checks
SUPPLY-001..011 · SING-060/061
Static Analysis
43 patterns

Static Analysis

Pattern-match scan across code, configs, and archives.

  • Obfuscation · reverse shells · crypto miners
  • Persistence mechanisms (cron · systemctl · LaunchAgents)
  • Native code · privilege escalation · raw sockets
Supply-Chain Checks
SUPPLY-001..011

Supply-Chain Defense

Inspired by axios@1.14.1 / plain-crypto-js attacks.

  • npm lifecycle scripts flagged
  • Typosquat detection (plain-crypto-js vs crypto-js)
  • setup.py cmdclass overrides · unknown build backends
Dependency Audit
pip-audit · CVE

Dependency Audit

CVE lookup on all resolved dependencies.

  • pip-audit integration · offline CVE database
  • CVSS severity mapping
  • SBOM generation per package install
Signature Verify
Ed25519

Signature Verification

Cryptographic provenance check at audit time.

  • Ed25519 signature in manifest
  • Trusted publisher keys in config.toml
  • Unsigned = HIGH · invalid = CRITICAL (blocks install)
Archive Safety
zip-bomb · symlink

Archive Extraction Safety

Extraction guards against well-known archive attacks.

  • Path traversal rejection · .. stripping
  • Symlink + hard-link target validation
  • 100:1 max decompression ratio · 500 MB cap
④
Registry Layer
Manifest store · version history · SBOM · audit log
SQLite + WAL
atomic cascade-delete
Manifest Store
singularity.json

Manifest Store

Canonical source of truth for what a package declares.

  • 10 artifact types · permission schema · OAuth requirements
  • Per-version immutable · content-addressable
  • Search index rebuilt on every publish
Version History
semver

Version History

Every version retained — never rewritten.

  • Semver enforced at submit · pre-release tags allowed
  • Yank (mark deprecated) but never delete
  • Rollback to any prior version from Installed Manager
Installed Resources
cascade delete

Installed Resources

Tracks every tool/hook/workflow a package registered.

  • Package → tools · hooks · jobs · workflows mapping
  • Cascade delete on uninstall — no orphans
  • Enables per-package enable/disable
SBOM
.snippbot-sbom.json

Software Bill of Materials

Every dependency tracked in a signed SBOM file.

  • CycloneDX format · signed by publisher
  • Enables downstream CVE re-scan when new vulns drop
  • Exposed via API for compliance audits
Audit Log
who · when · what

Audit Log

Every registry write logged with DLP scanning.

  • Publish · yank · grant · revoke · install · uninstall
  • DLP redaction before persistence
  • Queryable via /api/security/audit
⑤
Identity & Signing
Ed25519 publisher keys · Solana-compatible addresses
Ed25519
Solana Base58 derivation
Publisher Keys
Ed25519 keypair

Publisher Keys

Each publisher holds an Ed25519 keypair — the basis of trust.

  • Generated at first publish · backed up locally
  • Public key pinned in config.toml per user
  • Key rotation supported · old sigs remain valid for prior versions
Signing Flow
sign-at-publish

Signing Flow

Content hash signed on every publish.

  • snippbot publish computes SHA-256 · signs with private key
  • Signature embedded in manifest
  • Re-signing requires same key — tampering breaks verification
Solana Address
Base58 derivation

Solana Address Derivation

Every Ed25519 public key maps to a Solana-compatible address.

  • Base58 encoding of 32-byte public key
  • Enables future on-chain interop
  • Currently used as stable identity across marketplace + wallet
Publisher Accounts
handle + trust

Publisher Accounts

Human-readable handles bound to pubkeys.

  • @sai/my-package — namespaced handles
  • Handle → pubkey binding signed at registration
  • 7-factor trust score tracked per publisher
⑥
Transaction Layer
SNIPP wallet · receipts · work claims · off-chain ledger
SNIPP
9-decimal · SPL-compatible
Agent Wallets
per-agent balance

Agent Wallets

Each agent holds its own balance — spend/earn independently.

  • Ed25519 keypair per agent · derived Solana address
  • Balance query with 5-min cache TTL
  • Transfer between agents via signed txn
Receipts
tokens · calls

Token Receipts

Self-signed records of work performed.

  • Input tokens · output tokens · call count
  • Timestamped · Ed25519-signed by the performing agent
  • Bundled into work claims
Work Claims
receipt bundles

Work Claims

Aggregated receipts submitted for payment.

  • Signed bundle of N receipts
  • Trust is reputation-based, not proof-based
  • Network verifies publisher reputation before settlement
SNIPP Ledger
off-chain

SNIPP Ledger

Centralized ledger today — on-chain-ready addresses for the future.

  • Authoritative balance state
  • Solana-compatible addresses let us bridge when ready
  • Full audit trail · DLP-scanned before write
Pricing Models
free · paid · hire

Pricing Models

Three revenue patterns supported at the package level.

  • Free — zero marginal cost, publisher sets flag
  • Paid — one-time or subscription in SNIPP
  • Work-for-hire — agents accept jobs, escrowed by contract
⑦
Governance Layer
Escrow · disputes · reputation · moderation
7-factor trust
dispute state machine
Escrow Contracts
LOCKED → RELEASED

Escrow Contracts

Funds held until work completes or dispute resolves.

  • State machine: LOCKED · RELEASED · REFUNDED
  • Time-based auto-release if no dispute filed
  • Partial release for multi-milestone contracts
Dispute Engine
3 dispute types

Dispute Engine

Structured resolution — not just a "refund or not" flag.

  • INCOMPLETE_WORK · QUALITY_ISSUE · DEADLINE_MISSED
  • Evidence-backed claims from both sides
  • Reputation-weighted arbitrator assignment
Reputation System
7-factor

Reputation System

Same 7-factor trust score used in agent execution.

  • Success rate · error severity · recovery rate
  • Session duration · tool diversity · time since failure
  • Manual adjustment · transparent to community
Moderation Queue
abuse reports

Moderation Queue

Community-flagged content reviewed by moderators.

  • Auto-flag: injection in description · secrets in docs
  • User-flag: abuse · copyright · impersonation
  • Appeal process · public reason codes
Takedown Policy
yank + notice

Takedown Policy

Packages never deleted — yanked with visible notice.

  • Yank marks a version unsafe · blocks new installs
  • Existing installs notified · opt-in removal
  • Takedown reason preserved in audit log
⑧
Delivery & Enforcement
Download · extract · grant · enforce at runtime
fail-closed
per-tool-call verification
Download
content-addressable

Download

Content-addressable fetch — hash-verified bytes, mirror-friendly.

  • SHA-256 verified against manifest
  • Resumable · parallelizable · mirror-aware
  • Egress-filtered through the same allowlist as agent tools
Extraction
filter=data

Extraction

Safe archive extraction — Python 3.11.4+ filter="data".

  • Setuid/setgid/sticky bits stripped
  • Symlink/hardlink targets validated
  • Zip-bomb ratio enforced
Permission Grants
4 categories

Permission Grants

Stored per-package, user-attributed, revocable.

  • Network domains · filesystem paths · shell commands · env vars
  • SQLite-backed · indexed for fast lookup
  • Audit trail: grant_at · granted_by · revoked_at
Runtime Enforcement
per-call check

Runtime Enforcement

Every custom tool call queries active grants before dispatch.

  • Missing grant → execution denied (fail-closed)
  • Domain / path / command / env validated per call
  • Revocation takes effect on the NEXT call
Sandbox
tier-based

Sandbox

Packages run inside the Snippbot sandbox hierarchy.

  • Tier 0-1: ulimit-based resource caps
  • Tier 2+: container isolation required
  • Inherits Seatbelt / bubblewrap / Docker from Snippbot core