Immutable, self-sovereign account infrastructure for Ethereum.
Loom is the immutable account layer beneath wallets, fintech platforms, institutions, and developer applications. It fixes the account's security model and leaves every product free to build its own experience on top: a fintech can embed it behind passkeys, and a privacy wallet can offer a fully self-sovereign experience — both inherit the same guarantees.
A user's account should outlive every product and infrastructure provider built around it.
- Immutable core — no admin, no upgrade proxy, no developer or factory authority.
- Passkey-native — WebAuthn / P-256 validation with multi-passkey MFA.
- Guardian recovery — threshold guardians, visible delay, and freeze, with no guardian spending power.
- Sovereign migration — move an account forward with no custodian in the loop.
- Walkaway guarantee — the account stays usable and recoverable even if every Loom service disappears.
- SDK-first — headless packages that choose no default RPC, bundler, or paymaster.
Custodial platforms simplify onboarding by reintroducing trust. Traditional self-custody preserves ownership but pushes seed phrases, fragmented tooling, and fragile recovery onto users. Replacing seed phrases with company accounts or mandatory infrastructure does not remove trust — it only changes who users are forced to trust.
Loom treats this as an architectural problem: applications should compete on experience, not on owning user accounts, and users should be able to change wallets, providers, authentication, and recovery models without replacing the account they trust. The deeper rationale is in Design foundations and Product principles.
- Users own accounts — not applications, companies, or infrastructure.
- Security before convenience — convenience may improve; guarantees may not weaken.
- Keep the trusted core small — everything else evolves independently.
- Modular over monolithic — capabilities compose through narrowly scoped modules.
- Infrastructure is replaceable — wallets, SDKs, bundlers, paymasters, RPCs, and recovery coordinators can all be swapped without changing the account.
- Explicit authority — nothing receives more authority than it requires, and every scope is auditable.
- Privacy is part of security — achieved through explicit, auditable mechanisms, not trusted intermediaries.
- Exit must always remain possible — no provider or organization becomes a permanent dependency.
Each principle is expanded in Product principles.
Loom is account infrastructure for Ethereum: immutable smart accounts and a deliberately small trusted foundation. Authentication, authorization, recovery, spending policies, privacy, and future extensions are independent modules that evolve without changing the account itself.
Loom is not a wallet application, a hosted service, or a required frontend, SDK, bundler, paymaster, RPC provider, or recovery coordinator. It defines the account — builders create the experience, and users remain in control.
Loom is built for individuals, wallet developers, fintechs, institutions, infrastructure providers, and autonomous agents; see Who Loom is for.
Loom is designed around a small immutable account core. Long-term authority belongs to the account itself; capabilities that naturally evolve — authentication, recovery, permissions, privacy — remain independent from it.
- Immutable account layer — the permanent trust anchor. Defines ownership, execution, and the security boundaries that stay stable for the account's lifetime.
- Authorization layer — validators, passkeys, session permissions, and spending policies as narrowly scoped components. New authentication methods do not require redesigning the account.
- Recovery layer — a bounded security policy, not an ownership transfer: explicit authority, observable state transitions, no guardian spending power.
Full detail lives in Architecture, Execution model, Recovery, and Privacy adapters.
A LoomAccount is deliberately not a single linear state machine. Its
observable state is the product of several mostly-orthogonal dimensions, tied
together by a monotonic configVersion that invalidates any stale pending
operation. An account can be frozen while a migration and a recovery are both
pending.
stateDiagram-v2
direction TB
[*] --> Uninitialized
Uninitialized --> Operational: initialize() · configVersion 0→1
Operational --> Frozen: guardian freeze() · 2d window
Frozen --> Operational: unfreeze() once the window lapses
Operational --> MigrationPending: scheduleMigration()
MigrationPending --> Operational: cancel · or executeMigration · migrationNonce++
Operational --> RecoveryPending: proposeRecovery() · threshold guardians
RecoveryPending --> Operational: cancel · or executeRecovery · configVersion++
Frozen, MigrationPending, and RecoveryPending overlay Operational
independently. The authoritative, code-derived model — including the freeze
carve-out for recovery and the invariants that enforce it — is in
docs/design/lifecycle.md.
This repository contains the on-chain account and authorization layer plus early local SDK packages. It does not contain the future mobile wallet, production private transfer system, light client, cross-chain router, or hosted infrastructure.
Account — immutable smart accounts with no developer, factory, admin, or proxy-upgrade authority; ERC-4337 v0.9 validation with atomic single/batch execution; ERC-1271 routing, though every bundled validator declines arbitrary hash signing, so this account signs no off-chain messages today; provider-independent direct execution; a limited ERC-7579 adapter surface with unsupported modes rejected.
Authentication — WebAuthn / P-256 passkeys and multi-passkey threshold (MFA) validation.
Authorization — bounded and granular session permissions, granular execution policies, spending policies, and paymaster restrictions.
Recovery — guardian recovery with visible delay, cancellation, and expiry; complete validator-set replacement; single-guardian emergency freeze without spending authority.
Migration — delayed sovereign migration with destination code/config binding, cancellation, expiry, and atomic execution under hook enforcement.
SDK — local account SDK (@loom/account), wallet engine SDK (@loom/sdk),
and privacy SDK foundations (@loom/privacy). The SDK deliberately chooses no
default RPC, bundler, paymaster, relayer, signer, recovery coordinator, or
privacy provider; those adapters are supplied by the developer or user.
See the Roadmap for direction beyond what ships today.
The examples/ directory shows the same account powering
different products under the same security model:
- Embedded fintech — self-sovereign accounts inside an existing app, behind
passkey authentication:
enterprise-onboarding.mjs(integration guide). - Consumer wallet — a privacy-first wallet with modular recovery:
individual-passkey-wallet.mjs.
Each script is runnable and self-verifying: it installs a global-fetch trap, so
a hidden default-provider call would fail the run — the walkaway guarantee,
demonstrated.
Loom keeps source, tests, operational evidence, and developer tooling separate so review boundaries stay clear:
src/contains production Solidity contracts.script/contains Foundry deployment scripts only.test/contains Solidity and wallet-engine tests, split by unit, integration, evidence, invariant, regression, formal-style, and E2E scopes.packages/contains the headless TypeScript SDK packages.tools/contains repository maintenance, CI, evidence, formal, quality, SDK, keystore, and site tooling.fixtures/contains reviewed test fixtures; real-device WebAuthn corpus fixtures are release evidence, not user telemetry.evidence/contains public, reproducible release-candidate evidence only.formal/contains Certora, Kontrol, Lean, and refinement specifications.docs/contains design, security, operations, decisions, reviews, and the documentation site.
Generated outputs, local virtual environments, private configs, logs, caches, and secret-bearing rehearsal inputs must stay out of the repository.
npm ci
npm run verify:quickNode.js 22 and Foundry v1.7.1 are the supported baseline. verify:quick runs
formatting, linting, size checks, gas-snapshot checks, tests, and source-policy
checks; npm run verify additionally runs the CI fuzz and invariant profile.
Every change is expected to include appropriate testing, documentation, and review. Contributions that simplify the trusted core, improve auditability, strengthen modularity, or reduce trust assumptions are strongly encouraged. See Contributing.
Loom is pre-audit software. Do not use it to secure production assets.
Current evidence includes unit and EntryPoint-integration tests, fuzz tests, stateful invariants, gas snapshots, static analysis, and selected Halmos formal properties — useful evidence, not a claim of complete correctness. Before production use, Loom needs independent audit, live multi-bundler testing, browser and hardware passkey fixtures, public deployment rehearsals, stronger formal coverage, and a funded bug bounty. See the threat model and production readiness gates.
- Documentation index
- Product principles · Design foundations · Who Loom is for · Roadmap
- Architecture · Account lifecycle · Execution model · Authentication · Permissions · Recovery
- Threat model · Assumptions and residual risks · Production readiness
- Contributing · Security policy
Licensed under the MIT License.