diff --git a/public/bloom-mark.svg b/public/bloom-mark.svg index 51bd683..ce01cc1 100644 --- a/public/bloom-mark.svg +++ b/public/bloom-mark.svg @@ -1,9 +1,10 @@ - - - - - - - + + + + + + + + + - diff --git a/public/favicon.svg b/public/favicon.svg new file mode 100644 index 0000000..ce01cc1 --- /dev/null +++ b/public/favicon.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/public/og.png b/public/og.png new file mode 100644 index 0000000..aeac8f3 Binary files /dev/null and b/public/og.png differ diff --git a/src/pages/getting-started/agent-setup.mdx b/src/pages/getting-started/agent-setup.mdx index 60763eb..4fafd12 100644 --- a/src/pages/getting-started/agent-setup.mdx +++ b/src/pages/getting-started/agent-setup.mdx @@ -10,14 +10,13 @@ An agent should then: 1. Install or build the `bloom` binary. 2. Run `bloom init`. -3. Prefer a mounted filesystem when available. -4. Fall back to `bloom vfs cat|ls|write` when mounting is blocked. -5. Inspect `/docs/README.md`, `/status/`, and the top-level tree before taking actions. -6. Explain what it can do and ask before confirming any transaction. +3. Mount Bloom at `/bloom` or the configured mount path. +4. Inspect `/bloom/docs/README.md`, `/bloom/status/`, and the top-level tree before taking actions. +5. Explain what it can do and ask before confirming any transaction. ## Rules for agents -- Do not write custom signing or broadcast code unless Bloom cannot satisfy the task. +- Do not write or use custom signing or broadcast code. - Read generated plans before asking the user to approve anything. - Treat missing config, disabled broadcasts, and policy failures as safety signals, not obstacles to bypass. - Keep live mainnet and L2 sends opt-in. @@ -25,10 +24,10 @@ An agent should then: ## Useful discovery commands ```sh -bloom vfs ls / -bloom vfs cat /docs/README.md -bloom vfs cat /status/daemon.json -bloom vfs cat /status/backends/summary.json -bloom vfs ls /chains -bloom vfs ls /tools +ls /bloom/ +cat /bloom/docs/README.md +cat /bloom/status/daemon.json +cat /bloom/status/backends/summary.json +ls /bloom/chains +ls /bloom/tools ``` diff --git a/src/pages/getting-started/quickstart.mdx b/src/pages/getting-started/quickstart.mdx index cd76238..84a03b2 100644 --- a/src/pages/getting-started/quickstart.mdx +++ b/src/pages/getting-started/quickstart.mdx @@ -1,6 +1,6 @@ # Quickstart -This walkthrough uses the CLI fallback. If the mount is available, the same paths work through `/bloom` or your selected mount directory. +This walkthrough uses the mounted `/bloom` filesystem. Bloom’s command-specific fallbacks exist for constrained environments, but normal shell tools against the mount are the default interface. ## Prerequisites @@ -14,33 +14,25 @@ cargo build -p bloom --all-features cargo run -p bloom -- init ``` -`bloom init` creates the Bloom home directory, writes the default config, and registers read-ready chain defaults. - -## Inspect chain state - -```sh -cargo run -p bloom -- vfs ls / -cargo run -p bloom -- vfs cat /docs/README.md -cargo run -p bloom -- vfs cat /chains/ethereum/head/number -cargo run -p bloom -- vfs cat /prices/spot/eth.usd -``` +`bloom init` creates the Bloom home directory, writes the default config, and registers read-ready chain defaults. The default mount path is `/bloom`. ## Mount the filesystem -Create a mount directory and start the daemon: +Create the mount directory and start the daemon: ```sh -mkdir -p "$HOME/bloom" -cargo run -p bloom -- serve --mount "$HOME/bloom" +sudo mkdir -p /bloom +cargo run -p bloom -- serve --mount /bloom ``` Then inspect it like any other directory: ```sh -ls ~/bloom -cat ~/bloom/docs/README.md -ls ~/bloom/chains -cat ~/bloom/chains/ethereum/head/number +ls /bloom/ +cat /bloom/docs/README.md +ls /bloom/chains +cat /bloom/chains/ethereum/head/number +cat /bloom/prices/spot/eth.usd ``` ## Create a demo wallet @@ -57,16 +49,15 @@ The key is encrypted in the keystore. The filesystem exposes address and public With Anvil running on `127.0.0.1:8545`: ```sh -bloom vfs write \ - /wallets/alice/chains/anvil/outbox/new.tx \ - --data 'send 0.01 eth to 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 on anvil' +echo 'send 0.01 eth to 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 on anvil' \ + > /bloom/wallets/alice/chains/anvil/outbox/new.tx ``` Review the pending entry: ```sh -bloom vfs ls /wallets/alice/chains/anvil/outbox/pending -bloom vfs cat /wallets/alice/chains/anvil/outbox/pending//plan.md +ls /bloom/wallets/alice/chains/anvil/outbox/pending +cat /bloom/wallets/alice/chains/anvil/outbox/pending//plan.md ``` Confirm only after reading the plan. diff --git a/src/pages/index.mdx b/src/pages/index.mdx index b473e29..5647589 100644 --- a/src/pages/index.mdx +++ b/src/pages/index.mdx @@ -1,4 +1,36 @@ -# Bloom Docs +--- +title: /bloom | Documentation +description: Documentation for Bloom, the agentic Ethereum wallet mounted as a virtual filesystem. +--- + +
+ /bloom +
+ + Bloom is an **agentic Ethereum wallet mounted as a virtual filesystem**. @@ -29,4 +61,4 @@ For the shortest onboarding path, tell your agent: Read https://bloom.directory/SKILL.md and set up Bloom. ``` -The agent should then mount Bloom or use the `bloom vfs` fallback, inspect the in-tree docs, explain the capabilities it found, and use Bloom instead of writing bespoke Web3 SDK code. +The agent should then mount Bloom at `/bloom`, inspect the in-tree docs, explain the capabilities it found, and use Bloom instead of writing bespoke Web3 SDK code. diff --git a/src/pages/introduction/benefits.mdx b/src/pages/introduction/benefits.mdx index f74bc59..16ea79b 100644 --- a/src/pages/introduction/benefits.mdx +++ b/src/pages/introduction/benefits.mdx @@ -12,10 +12,10 @@ Bloom is designed around the operating model agents already understand: files. ## For agents -- **No custom Web3 loop.** Agents can use `ls`, `cat`, and writes rather than assembling RPC calls and signing flows from scratch. +- **No custom Web3 loop.** Agents can use `ls`, `cat`, and file writes under `/bloom` rather than assembling RPC calls and signing flows from scratch. - **Discoverable capabilities.** The mounted tree exposes docs, status, supported chains, wallets, tools, and control files in one place. - **Plans before actions.** Every write-oriented workflow is staged into readable artifacts such as `plan.md`, `intent.json`, and `policy_check.json`. -- **Lower integration cost.** The same paths work through the mounted filesystem and through the `bloom vfs cat|ls|write` fallback. +- **Lower integration cost.** The same paths work through ordinary shell tools, scripts, and file-aware agent runtimes once `/bloom` is mounted. ## For developers and integrators diff --git a/src/pages/introduction/core-concepts.mdx b/src/pages/introduction/core-concepts.mdx index 2edaf2f..f0191d2 100644 --- a/src/pages/introduction/core-concepts.mdx +++ b/src/pages/introduction/core-concepts.mdx @@ -6,16 +6,12 @@ Bloom exposes blockchain and wallet operations as paths. Reading a file performs ## Mounted directory -The preferred interface is a mounted directory such as `~/bloom`, `/bloom`, or `/Volumes/bloom`. The mount lets any agent or shell tool interact with Bloom using ordinary filesystem operations. - -## `bloom vfs` fallback - -When mounting is unavailable, the CLI exposes the same paths: +The preferred interface is the mounted `/bloom` directory. The mount lets any agent or shell tool interact with Bloom using ordinary filesystem operations. ```sh -bloom vfs ls / -bloom vfs cat /docs/README.md -bloom vfs write /wallets/new --data alice +ls /bloom/ +cat /bloom/docs/README.md +echo alice > /bloom/wallets/new ``` ## Stage-confirm flow @@ -28,4 +24,4 @@ Policies live per wallet and enforce caps, recipient rules, contract-call gates, ## Audit log -Bloom appends writes and side-effecting reads to a hash-chained audit log under the Bloom home directory. The current head is exposed through `status/audit/head`. +Bloom appends writes and side-effecting reads to a hash-chained audit log under the Bloom home directory. The current head is exposed through `/bloom/status/audit/head`. diff --git a/src/pages/petals/overview.mdx b/src/pages/petals/overview.mdx index 94d1d81..43e3600 100644 --- a/src/pages/petals/overview.mdx +++ b/src/pages/petals/overview.mdx @@ -1,31 +1,28 @@ # Petals -A petal is a Bloom application module compiled to WebAssembly. A deployed petal -is content-addressed by its wasm hash and bound to a human-readable path such as -`/bloom/core/fungible` or `/bloom/dex/pool`. +## ⚠️ WARNING - EARLY / UNFINISHED -Petals are invoked through programmable transaction blocks, or PTBs. A PTB can -call multiple petal functions, pass outputs from one command into later -commands, transfer objects, split and merge coins, and commit or revert -atomically. +Petals are not ready for prime-time use. They are in active development, the APIs and runtime model may change, and the current documentation is primarily for Bloom developers rather than end users. + +Today, Petals should be understood as the path toward safe extensions to WalletFS: small, reviewable modules that can add capabilities behind Bloom’s policy, planning, and filesystem boundaries without asking agents to write custom signing or broadcast code. + +For an early example of a custom petal, see [`bloombook`](https://github.com/bloom-directory/bloombook). It is useful as a developer reference for how Petals can package new filesystem-backed capabilities, but it should be treated as experimental alongside the Petals runtime itself. + +A petal is a Bloom application module compiled to WebAssembly. A deployed petal is content-addressed by its wasm hash and bound to a human-readable path such as `/bloom/core/fungible` or `/bloom/dex/pool`. + +Petals are invoked through programmable transaction blocks, or PTBs. A PTB can call multiple petal functions, pass outputs from one command into later commands, transfer objects, split and merge coins, and commit or revert atomically. ## What Petal Authors Write -Petal authors should start in their own Rust project, not inside the Bloom -monorepo. Today, depend on the Bloom repo by git URL, build your crate to wasm, -and use the Bloom CLI to deploy the resulting `.wasm`. +Petal authors should start in their own Rust project, not inside the Bloom monorepo. Today, depend on the Bloom repo by git URL, build your crate to wasm, and use the Bloom CLI to deploy the resulting `.wasm`. Petal authors write Rust crates that depend on the Bloom runtime and macros: -- `bloom-resource`: guest-side runtime types such as `Resource`, `Coin`, - `Capability`, `Signer`, `UID`, `BloomType`, and host wrappers. -- `bloom-resource-macros`: `#[bloom::petal]`, `#[bloom::object]`, - `#[bloom::capability]`, `#[derive(BloomType)]`, and - `#[bloom::invariant]`. +- `bloom-resource`: guest-side runtime types such as `Resource`, `Coin`, `Capability`, `Signer`, `UID`, `BloomType`, and host wrappers. +- `bloom-resource-macros`: `#[bloom::petal]`, `#[bloom::object]`, `#[bloom::capability]`, `#[derive(BloomType)]`, and `#[bloom::invariant]`. - `bloom-objects`: object IDs, owners, access modes, and type tags. -Every public function inside a `#[bloom::petal]` module becomes a callable -entry point. The macro emits: +Every public function inside a `#[bloom::petal]` module becomes a callable entry point. The macro emits: - one wasm export named `__petal_`; - a `bloom_petal_manifest_v0` custom section; @@ -33,12 +30,6 @@ entry point. The macro emits: ## What The Chain Uses -At deploy time, Bloom checks that the wasm contains a manifest section, that the -manifest path matches the deploy path, and that every manifest function has a -matching wasm export. +At deploy time, Bloom checks that the wasm contains a manifest section, that the manifest path matches the deploy path, and that every manifest function has a matching wasm export. -At call time, the PTB validator loads the manifest, checks argument kinds and -object access modes, then the executor runs the wasm under a deterministic -chain VM. Constants, returns, and object payloads use Bloom's canonical, -manifest-driven value codec; old ad hoc petal payload layouts are not the -supported authoring model. +At call time, the PTB validator loads the manifest, checks argument kinds and object access modes, then the executor runs the wasm under a deterministic chain VM. Constants, returns, and object payloads use Bloom's canonical, manifest-driven value codec; old ad hoc petal payload layouts are not the supported authoring model. diff --git a/src/pages/reference/deployment.mdx b/src/pages/reference/deployment.mdx deleted file mode 100644 index 811a208..0000000 --- a/src/pages/reference/deployment.mdx +++ /dev/null @@ -1,50 +0,0 @@ -# Deployment - -The docs are configured for Cloudflare Pages. Vocs does **not** require Cloudflare Workers when it is built with full-static output. - -## Pages settings - -Use the existing Cloudflare Pages project for this repository with custom build settings: - -| Setting | Value | -| --- | --- | -| Framework preset | `None` / custom | -| Root directory | repository root | -| Build command | `npm ci && npm run build` | -| Build output directory | `dist/public` | -| Node version | `22`, or Cloudflare Pages' current LTS if 22 is unavailable | - -The Vocs config uses: - -```ts -renderStrategy: 'full-static' -``` - -That makes `vocs build` emit HTML and assets under `dist/public`, which Pages can serve directly. - -## Production deploys - -Connect the Pages project to `bloom-directory/docs` and configure production deployments from `master`. - -When a PR merges into `master`, Cloudflare Pages should run the build command and publish `dist/public`. - -## Pull request previews - -Cloudflare Pages supports automatic preview deployments for GitHub pull requests. - -To enable them: - -1. Open the Cloudflare dashboard. -2. Go to **Workers & Pages → docs Pages project → Settings → Builds & deployments**. -3. Ensure the project is connected to `bloom-directory/docs`. -4. Set production branch to `master`. -5. Enable preview deployments for pull requests / non-production branches. -6. Confirm the build settings above. - -After that, each PR should get a Cloudflare Pages preview URL and a GitHub deployment/check attached to the PR. - -## When would Workers be needed? - -Use Workers only if the docs need custom edge logic: auth, redirects that Pages cannot express, headers/caching beyond Pages config, API endpoints, or server-side rendering. - -For the current Bloom docs site, static Pages hosting is enough and simpler. diff --git a/src/pages/reference/supported-chains.mdx b/src/pages/reference/supported-chains.mdx index d166f61..472b41f 100644 --- a/src/pages/reference/supported-chains.mdx +++ b/src/pages/reference/supported-chains.mdx @@ -19,14 +19,61 @@ Reads, simulations, and planning work with zero configuration when public RPC de ## Chain paths ```txt -/chains//head/number -/chains//head/hash -/chains//blocks/ -/chains//addresses/
/... -/chains//contracts/
/... -/chains//tx//... +/bloom/chains//head/number +/bloom/chains//head/hash +/bloom/chains//blocks/ +/bloom/chains//addresses/
/... +/bloom/chains//contracts/
/... +/bloom/chains//tx//... ``` +## Adding custom chains + +Custom EVM chains are added to `~/.bloom/config.toml` under `[chains.]`. The name becomes the filesystem path segment under `/bloom/chains//`, so keep it lowercase and shell-friendly. + +A minimal read-only chain entry needs a display name, numeric EVM `chain_id`, native token metadata, and at least one RPC endpoint: + +```toml +[chains.mychain] +name = "mychain" +chain_id = 12345 +display_name = "My Chain" +native_symbol = "MYC" +native_decimals = 18 +rpc_urls = ["https://rpc.mychain.example"] +allow_broadcast = false +``` + +For richer endpoint selection, use `rpc_endpoints` instead of `rpc_urls`: + +```toml +[[chains.mychain.rpc_endpoints]] +url = "https://rpc-primary.mychain.example" +weight = 100 +max_rps = 25 +http_only = true + +[[chains.mychain.rpc_endpoints]] +url = "https://rpc-backup.mychain.example" +weight = 50 +``` + +Optional fields: + +- `etherscan_api_url` — Etherscan-compatible explorer API base URL for ABI/source/address-history surfaces. +- `legacy_tx = true` — use legacy `gas_price` transactions instead of EIP-1559 fee fields. +- `allow_broadcast = true` — permit live sends on this chain. Keep this `false` until the chain is tested and policy is configured. + +After editing config, restart the daemon and verify the mounted paths: + +```sh +bloom serve --mount /bloom +ls /bloom/chains/mychain +cat /bloom/chains/mychain/head/number +``` + +If reads fail, check `/bloom/status/backends/summary.json` and the daemon logs first. Custom chains must provide at least one usable `rpc_urls` or `rpc_endpoints` entry. + ## Etherscan-backed surfaces Address history and contract source/ABI metadata use Etherscan v2 with a TTL cache when configured. diff --git a/src/pages/reference/technical-architecture.mdx b/src/pages/reference/technical-architecture.mdx index 1273e60..ecbd825 100644 --- a/src/pages/reference/technical-architecture.mdx +++ b/src/pages/reference/technical-architecture.mdx @@ -7,23 +7,37 @@ Bloom is a Rust workspace split into focused crates around a daemon, virtual fil ```txt agent or user │ - ├─ mounted filesystem: ~/bloom, /bloom, /Volumes/bloom + ├─ mounted filesystem: /bloom + │ │ + │ ├─ shell reads: ls /bloom/chains, cat /bloom/status/daemon.json + │ └─ shell writes: echo ... > /bloom/wallets//chains//outbox/new.tx │ - └─ CLI fallback: bloom vfs cat|ls|write - │ - ▼ - bloom daemon - │ - ├─ VFS router and handlers - ├─ wallet transaction engine - ├─ encrypted keystore and signer - ├─ chain RPC pool and Etherscan-backed metadata - ├─ DeFi routing via Enso - ├─ watch executor - └─ audit log and policy enforcement + ▼ +bloom daemon + │ + ├─ VFS router and handlers + ├─ wallet transaction engine + ├─ encrypted keystore and signer + ├─ chain RPC pool and Etherscan-backed metadata + ├─ DeFi routing via Enso + ├─ watch executor + └─ audit log and policy enforcement ``` -`bloom serve` runs a long-lived daemon and listens on a Unix-domain JSON-RPC socket at `~/.bloom/run/bloom.sock`. Later `bloom vfs` calls auto-route through the socket when it exists, sharing unlock cache, watches, DeFi sessions, Etherscan cache, and daemon state. +`bloom serve --mount /bloom` runs a long-lived daemon and exposes the mounted filesystem. Standard shell reads and writes share daemon state including unlock cache, watches, DeFi sessions, Etherscan cache, and policy/audit state. + +## NFS mount surface + +Bloom exposes the VFS over NFS v4.1. The local `/bloom` mount is not a separate API from the VFS router; it is the normal filesystem surface backed by Bloom's daemon, handlers, policy checks, and audit model. + +This matters because Bloom should fit into ordinary Unix and infrastructure workflows rather than asking every agent or app to speak a custom CLI protocol. Over time, Bloom expects to rely more on this NFS layer for: + +- Unix permission boundaries and familiar file ownership/mode semantics; +- Docker and hypervisor use cases where `/bloom` can be shared into containers, VMs, or sandboxes as a mounted volume; +- multi-process workflows where different tools read plans, inspect state, and stage intents through the same mounted tree; +- safer automation patterns that can be constrained with standard filesystem access controls before Bloom's own policy layer evaluates an action. + +This area is still active work. Examples, experiments, and contributions around NFS permissions, container/VM volume sharing, and operational deployment patterns are welcome. ## Core crates @@ -47,7 +61,7 @@ agent or user ## Data flow for a transaction -1. Agent writes an intent to a wallet outbox path. +1. Agent writes an intent to a wallet outbox path under `/bloom`. 2. The VFS router dispatches to wallet handlers. 3. The transaction engine parses the intent and resolves chain, recipient, gas, value, calldata, and nonce defaults. 4. Simulation and policy checks run. @@ -58,6 +72,6 @@ agent or user ## Backend boundaries -Some surfaces are direct RPC reads. Others use Etherscan v2 where an indexer is required today. The live backend declaration is exposed under `status/backends/` and `status/backends/summary.json`. +Some surfaces are direct RPC reads. Others use Etherscan v2 where an indexer is required today. The live backend declaration is exposed under `/bloom/status/backends/` and `/bloom/status/backends/summary.json`. The future `indexer` backend is reserved but intentionally returns a clear not-implemented error today. diff --git a/src/pages/wallet/defi-intents.mdx b/src/pages/wallet/defi-intents.mdx index 36848f7..ca55b71 100644 --- a/src/pages/wallet/defi-intents.mdx +++ b/src/pages/wallet/defi-intents.mdx @@ -1,14 +1,14 @@ # DeFi intents -Bloom exposes DeFi routing under `defi/intents//`. The current implementation uses Enso Shortcuts. +Bloom exposes DeFi routing under `/bloom/defi/intents//`. The current implementation uses Enso Shortcuts. ## Natural-language flow ```sh -bloom vfs write /defi/intents/alice/new --data 'swap 100 usdc to eth on ethereum' -bloom vfs ls /defi/intents/alice -bloom vfs cat /defi/intents/alice//plan.md -bloom vfs cat /defi/intents/alice//route.json +echo 'swap 100 usdc to eth on ethereum' > /bloom/defi/intents/alice/new +ls /bloom/defi/intents/alice +cat /bloom/defi/intents/alice//plan.md +cat /bloom/defi/intents/alice//route.json ``` A session may include: diff --git a/src/pages/wallet/filesystem-guide.mdx b/src/pages/wallet/filesystem-guide.mdx index cd0a9a3..8ffac34 100644 --- a/src/pages/wallet/filesystem-guide.mdx +++ b/src/pages/wallet/filesystem-guide.mdx @@ -1,39 +1,40 @@ # Filesystem guide -Bloom’s VFS is rooted at the selected mount path or at `/` when addressed through `bloom vfs`. +Bloom’s VFS is normally mounted at `/bloom`. Use standard shell tools against that mount: reads are `cat`/`ls`, writes are file writes. ## Top-level layout | Path | Purpose | | --- | --- | -| `chains//` | Chain heads, blocks, addresses, contracts, gas, txs, receipts, mempool, and Etherscan-backed history. | -| `wallets//` | Managed wallets, balances, nonce, outbox, and signing surfaces. | -| `defi/intents//` | Natural-language and structured DeFi routing through Enso. | -| `watch//` | Polling subscriptions for balances, blocks, gas, and events. | -| `simulate//` | `eth_call` and state-override sandboxes without signing or broadcast. | -| `tools/` | Hashes, ABI, RLP, base64, hex, units, EIP-712, and address helpers. | -| `prices/` | DefiLlama spot prices and 24h changes. | -| `addressbook/` | Local petname directory. | -| `ens/` | ENS forward resolution. | -| `status/` | Daemon health, backend declarations, audit state, cache counts, and policy flags. | -| `docs/` | In-tree operational docs vendored into the VFS. | +| `/bloom/chains//` | Chain heads, blocks, addresses, contracts, gas, txs, receipts, mempool, and Etherscan-backed history. | +| `/bloom/wallets//` | Managed wallets, balances, nonce, outbox, and signing surfaces. | +| `/bloom/defi/intents//` | Natural-language and structured DeFi routing through Enso. | +| `/bloom/watch//` | Polling subscriptions for balances, blocks, gas, and events. | +| `/bloom/simulate//` | `eth_call` and state-override sandboxes without signing or broadcast. | +| `/bloom/tools/` | Hashes, ABI, RLP, base64, hex, units, EIP-712, and address helpers. | +| `/bloom/prices/` | DefiLlama spot prices and 24h changes. | +| `/bloom/addressbook/` | Local petname directory. | +| `/bloom/ens/` | ENS forward resolution. | +| `/bloom/status/` | Daemon health, backend declarations, audit state, cache counts, and policy flags. | +| `/bloom/docs/` | In-tree operational docs vendored into the VFS. | ## Read examples ```sh -bloom vfs cat /chains/base/head/number -bloom vfs cat /chains/ethereum/gas -bloom vfs cat /chains/ethereum/contracts/
/abi -bloom vfs cat /prices/spot/eth.usd -bloom vfs cat /ens/vitalik.eth +cat /bloom/chains/base/head/number +cat /bloom/chains/ethereum/gas +cat /bloom/chains/ethereum/contracts/
/abi +cat /bloom/prices/spot/eth.usd +cat /bloom/ens/vitalik.eth ``` ## Write examples ```sh -bloom vfs write /wallets/new --data alice -bloom vfs write /addressbook/treasury --data 0x... -bloom vfs write /wallets/alice/chains/anvil/outbox/new.tx --data 'send 0.01 eth to 0x... on anvil' +echo alice > /bloom/wallets/new +echo 0x... > /bloom/addressbook/treasury +echo 'send 0.01 eth to 0x... on anvil' \ + > /bloom/wallets/alice/chains/anvil/outbox/new.tx ``` Every write surface should produce inspectable state rather than surprising side effects. diff --git a/src/pages/wallet/wallets-and-transactions.mdx b/src/pages/wallet/wallets-and-transactions.mdx index b192e62..f02a4f9 100644 --- a/src/pages/wallet/wallets-and-transactions.mdx +++ b/src/pages/wallet/wallets-and-transactions.mdx @@ -7,7 +7,7 @@ Bloom wallets are local encrypted keys or watch-only addresses exposed through t Plain text creates a local wallet: ```sh -bloom vfs write /wallets/new --data alice +echo alice > /bloom/wallets/new ``` TOML supports explicit forms: @@ -25,9 +25,8 @@ passphrase = "..." # optional; falls back to BLOOM_PASSPHRASE Write to the wallet outbox: ```sh -bloom vfs write \ - /wallets/alice/chains/anvil/outbox/new.tx \ - --data 'send 0.01 eth to 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 on anvil' +echo 'send 0.01 eth to 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 on anvil' \ + > /bloom/wallets/alice/chains/anvil/outbox/new.tx ``` Bloom parses the intent, fills defaults, simulates where possible, runs policy checks, and creates a pending directory. @@ -35,9 +34,9 @@ Bloom parses the intent, fills defaults, simulates where possible, runs policy c ## Review and confirm ```sh -bloom vfs ls /wallets/alice/chains/anvil/outbox/pending -bloom vfs cat /wallets/alice/chains/anvil/outbox/pending//plan.md -bloom vfs cat /wallets/alice/chains/anvil/outbox/pending//policy_check.json +ls /bloom/wallets/alice/chains/anvil/outbox/pending +cat /bloom/wallets/alice/chains/anvil/outbox/pending//plan.md +cat /bloom/wallets/alice/chains/anvil/outbox/pending//policy_check.json ``` When running the long-lived daemon, confirm by writing non-empty content to `confirm`. For one-shot CLI flows, `bloom wallet confirm` unlocks and broadcasts in one command. diff --git a/src/pages/wallet/watches-and-simulation.mdx b/src/pages/wallet/watches-and-simulation.mdx index eb66df4..f351304 100644 --- a/src/pages/wallet/watches-and-simulation.mdx +++ b/src/pages/wallet/watches-and-simulation.mdx @@ -11,13 +11,16 @@ Kinds include: - `gas_price` - `event` -Write a TOML spec to `watch/new`, then inspect the watch directory: +Write a TOML spec to `/bloom/watch/new`, then inspect the watch directory: ```sh -bloom vfs write /watch/new --data 'kind = "block"\nchain = "base"' -bloom vfs ls /watch/ -bloom vfs cat /watch//live -bloom vfs cat /watch//history.jsonl +cat > /bloom/watch/new <<'EOF' +kind = "block" +chain = "base" +EOF +ls /bloom/watch/ +cat /bloom/watch//live +cat /bloom/watch//history.jsonl ``` Live files rotate at 1 MiB. @@ -29,7 +32,7 @@ Simulation sessions expose `eth_call` and state override workflows without signi Use simulation when an agent needs to inspect call effects, debug calldata, or prepare a plan before staging a wallet transaction. ```sh -bloom vfs write /simulate/new --data '{"chain":"anvil","to":"0x...","data":"0x..."}' -bloom vfs cat /simulate//result.json -bloom vfs cat /simulate//plan.md +echo '{"chain":"anvil","to":"0x...","data":"0x..."}' > /bloom/simulate/new +cat /bloom/simulate//result.json +cat /bloom/simulate//plan.md ``` diff --git a/vocs.config.ts b/vocs.config.ts index b43d5f0..d0ab29e 100644 --- a/vocs.config.ts +++ b/vocs.config.ts @@ -1,13 +1,24 @@ import { defineConfig } from 'vocs/config' +const env = (globalThis as typeof globalThis & { + process?: { env?: Record } +}).process?.env ?? {} + +const siteUrl = + env.CF_PAGES_BRANCH === 'master' + ? 'https://docs.bloom.directory' + : env.CF_PAGES_URL + export default defineConfig({ - title: 'Bloom Docs', - description: 'Agentic Ethereum wallet documentation for Bloom.', - logoUrl: '/bloom-mark.svg', - iconUrl: '/bloom-mark.svg', + title: '/bloom | Documentation', + description: + 'Documentation for Bloom, the agentic Ethereum wallet mounted as a virtual filesystem.', + logoUrl: '/favicon.svg', + iconUrl: '/favicon.svg', + ogImageUrl: siteUrl ? `${siteUrl}/og.png` : '/og.png', + baseUrl: siteUrl, rootDir: 'src/pages', renderStrategy: 'full-static', - baseUrl: 'https://docs.bloom.directory', socials: [ { icon: 'github', link: 'https://github.com/bloom-directory' }, { icon: 'x', link: 'https://x.com/bloomdirectory' }, @@ -50,7 +61,6 @@ export default defineConfig({ { text: 'Supported chains', link: '/reference/supported-chains' }, { text: 'Project map', link: '/reference/project-map' }, { text: 'Development', link: '/reference/development' }, - { text: 'Deployment', link: '/reference/deployment' }, { text: 'Limitations', link: '/reference/limitations' }, ], },