Skip to content

docs(readme): Cost — when to use the enclave #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FiscalMindset merged 1 commit into from
Jul 12, 2026
Merged

docs(readme): Cost — when to use the enclave #29

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ npm i -g @fiscalmindset/blindfold && blindfold signup --email you@example.com
[🧪 Proof — the demo](#proof-of-blindness--the-side-by-side-demo)<br/>
[🔌 Integration styles](#two-integration-styles)<br/>
[🧩 Supported integrations](#supported-integrations)<br/>
[💸 Cost — when to use it](#cost)<br/>
[⌨️ CLI at a glance](#cli-at-a-glance)<br/>
[🤖 Agent skill](#agent-skill--let-your-coding-agent-seal-keys-for-you)

Expand Down Expand Up @@ -484,6 +485,46 @@ impact writeup: [`integration-stack.md`](integration-stack.md).

---

<a id="cost"></a>

## 💸 Cost — when to use the enclave (and when not to)

Every time a key is *used*, it's a metered Terminal 3 enclave operation — a real
(tiny) cost, unlike reading a plaintext env var. That's the trade-off of
confidential compute: an `env` var is free but leakable; an enclave-substituted
key costs a fraction but **can't leak**.

**How small?** Measured live: **~20 tokens per operation** (a `use`/release or a
proxy forward). The self-serve `signup` grant (~20,000 tokens) is roughly
**1,000 secret-uses**, free, on testnet.
Comment on lines +497 to +499

@qodo-code-review qodo-code-review Bot Jul 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Informational

1. Token/credit ambiguity 🐞 Bug ⚙ Maintainability

The new Cost section calls the signup grant “~20,000 tokens” while the Installation section
describes the same grant as “~20,000 credits,” leaving it unclear whether these are synonyms or
different units. This can confuse users comparing the cost math with the balance shown by `blindfold
credit`.
Agent Prompt 
## Issue description
The README uses inconsistent terminology for the same signup grant amount: it’s described as “credits” in one place and “tokens” in another. This makes the pricing/balance units ambiguous.

## Issue Context
Other docs/CLI help text uses combined wording (“token/credit”), suggesting these terms may be synonymous, but the README should be explicit and consistent.

## Fix Focus Areas
- README.md[127-135]
- README.md[492-500]
- docs/AGENTS.md[83-93]

## Suggested fix
Pick one term and use it consistently throughout README (and ideally match the CLI wording), e.g.:
- Change both places to “tokens (credits)” if both terms are in use, **or**
- Standardize on “tokens” everywhere (including the earlier “~20,000 credits” mention), **or**
- Standardize on “credits” everywhere and adjust the new Cost section accordingly.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Whether that's cheap depends on **frequency × value**:

| Key | Fit |
|---|---|
| Deploy tokens, Stripe/payment keys, admin creds, keys handed to **autonomous agents** — used occasionally, catastrophic if leaked | ✅ **Ideal** — the cost is a rounding error next to a breach |
| A key hit **thousands of times a second**, low value per call | ⚠️ Per-call enclave cost adds up — use the pattern below |

**Three levers to keep it cheap:**

1. **Release once, reuse.** `release()` hands the plaintext to *your* process —
cache it for a burst/session and pay **one op for N calls** instead of N ops.
*(Trade-off: the key sits in your memory for that window — your choice, per
workload.)*
2. **Seal selectively.** Only route the keys that would hurt if leaked through
the enclave; leave low-value, high-frequency traffic alone.
3. **Proxy where it matters.** The per-call proxy gives the strongest guarantee —
spend the ~20 tokens where the guarantee is worth it, and release-and-reuse
where volume dominates.

**Bottom line:** for the high-value secrets Blindfold is built for — the ones you
hand to AI agents — ~20 tokens per use is trivial insurance against a leak that
could cost thousands. It's not meant to wrap every low-value call at massive
scale; for that, release-and-reuse collapses the cost. And on testnet, you build
for free.

---

## CLI at a glance

```bash
Expand Down
Loading