Skip to content

docs(faq): real numbers in the cost Q&A #30

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(faq): real numbers in the cost Q&A #30

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
6 changes: 4 additions & 2 deletions FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,8 +214,10 @@ The proxy currently returns the full upstream response (the enclave's `http.resp
- **Any HTTP SDK** via the proxy + `__BLINDFOLD__` sentinel (one-line base-URL swap).
- **TypeScript/JS** also have `release()` and `wrap()` for in-code use. (A Python `release()` is on the roadmap.)

### Is there a cost?
T3 runs on credits (testnet credits are free to request). Writes (seal, publish, grant) and contract executes consume credits; reads are cheap. `blindfold doctor` flags an out-of-credit tenant (403) explicitly.
### Is there a cost? Isn't hitting an enclave every time expensive?
Fair question. Every *use* of a key is a metered Terminal 3 enclave op — unlike reading a plaintext env var (free but leakable). But it's small: measured live, **~20 tokens per operation** (a `use`/release or a proxy forward). The self-serve `signup` grant (~20,000 tokens) is **~1,000 uses**, free, on testnet. `blindfold credit` shows your balance; `blindfold doctor` flags an out-of-credit tenant explicitly.

@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

2. Tokens/credits ambiguity 🐞 Bug ⚙ Maintainability

FAQ.md describes cost in “tokens” but also uses “out-of-credit” wording, while other docs and the
CLI use both “tokens” and “credits” without clearly stating they’re the same balance/unit. This
inconsistency can confuse users about what blindfold credit reports and what resource they need to
top up.
Agent Prompt 
### Issue description
Terminology around metered units fluctuates between “tokens” and “credits” in user-facing docs and CLI output. The updated FAQ leans on “tokens” while still saying “out-of-credit,” which can read like two separate things.

### Issue Context
- README uses both terms in different sections.
- The CLI `blindfold credit` output shows “tokens” while the UI/title/top-up text says “credit/credits.”

### Fix Focus Areas
- FAQ.md[217-218]

### Suggested change
Add a one-liner in the FAQ clarifying equivalence, e.g. “Terminal 3 calls these metered units tokens (aka credits); `blindfold credit` shows this balance.”
Optionally, standardize on one term across docs in a follow-up PR.

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


Whether that's "expensive" is **frequency × value**: for the high-value keys Blindfold is built for (deploy tokens, payment/admin creds, keys you hand to autonomous agents), ~20 tokens per use is a rounding error next to a breach. For a low-value key hit thousands of times a second, use **release-once-reuse** — `release()` hands the plaintext to your process, so you cache it for a burst and pay **one op for N calls** instead of N ops. Also: **seal selectively** (only what would hurt if leaked) and use the **proxy where the guarantee is worth it**. See the [Cost section in the README](README.md#cost) for the full breakdown.

@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.

Remediation recommended

1. Plaintext caching risk 🐞 Bug ⛨ Security

FAQ.md recommends caching plaintext returned by release() (“release-once-reuse”) to reduce
per-call enclave ops, but it omits the explicit security trade-off that the secret now resides
in-process for that cache window. Readers may over-cache and unintentionally weaken the “agent never
had the key” posture.
Agent Prompt 
### Issue description
The FAQ’s “release-once-reuse” guidance encourages caching plaintext returned by `release()` but doesn’t explicitly warn that this increases plaintext residency in the application process, which is a deliberate security trade-off.

### Issue Context
The project already documents this trade-off elsewhere (README cost section + `release()` source-level security note), but the new FAQ text currently reads as purely a cost optimization.

### Fix Focus Areas
- FAQ.md[217-220]

### Suggested change
Add a short parenthetical immediately after the “release-once-reuse” sentence, e.g.:
- note that caching keeps the secret in your process memory for that window,
- recommend keeping the cache scope/lifetime minimal,
- remind not to log/persist the plaintext,
- optionally link to README Cost section for the trade-off wording.

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


### Where does my key physically live (for compliance)?
Only inside the Intel TDX enclave on Terminal 3's infrastructure, sealed to your tenant's `secrets` map. It is never written to your disk, your logs, or your git history. You're extending trust to Intel TDX + T3 — the same shape as trusting a KMS/HSM vendor.
Expand Down
Loading