Skip to content

[DOCS] client-sdk/guides: migrate the SDK guides to 0.7 - #56

Merged
alexandrecarvalheira merged 5 commits into
mainfrom
docs/sweep-client-sdk-guides
Aug 26, 2026
Merged

[DOCS] client-sdk/guides: migrate the SDK guides to 0.7#56
alexandrecarvalheira merged 5 commits into
mainfrom
docs/sweep-client-sdk-guides

Conversation

@alexandrecarvalheira

Copy link
Copy Markdown
Collaborator

Stacked on #53. First batch of the code sweep: the seven guides that teach the SDK API, where wrong code costs the most.

Verified against the published SDK docs, not just my rename table

You were right to push back on the scripted rename. I pulled https://cofhesdk.fhenix.io/llms-full.txt and checked each page against it, and the script had produced five real bugs that source-checking alone would not have caught:

.withPermit(permit) became .withACP(ACP) in four places, because the regex capitalised the variable, not just the type. The correct call is .withACP(acp). A reader copying that example gets an undefined identifier.

It also rewrote the literal error strings 'Permit is expired' / 'Permit is not signed'. That one happened to be right, but only by luck: I confirmed against acps/validation.ts that 'ACP is expired' and 'ACP is not signed' are the actual strings in 0.7.1.

What the official docs confirmed: the three withACP overloads, the exactly-one-of rule on decryptForTx, the { ctHash, decryptedValue, signature } return shape, the [...hashes, signature] batch, the Encryptable to Solidity table row for row, the 2048-bit limit, and // defaultACPExpiration: 60 * 60 * 24 * 30 verbatim.

What changed

encrypting-inputs is rewritten. Every example was wrong: execute() now returns [...hashes, signature], which is inputs.length + 1 elements, and setConsumingContract is required before execute() exists at all. Also documents the trap with no compile-time signal, that the consuming contract is whichever contract runs FHE.asEuint* and not necessarily the one you call, and adds setSecurityZone, which was never documented.

writing-encrypted-data moves off the deleted InEuint32 struct to externalEuint32 plus a bytes proof. The hand-written viem ABI changes from the (ctHash, securityZone, utype, signature) tuple to bytes32 and bytes, and assertCorrectEncryptedItemInput is dropped (zero files in 0.7.1).

error-handling had two error codes that no longer exist. PermitNotFound and PermitInvalid are ACPNotFound and ACPInvalid, and the enum gained ACPExpired, ACPRevoked, ACPDenied, ACPRequired, so callers no longer infer the condition from the message. Added ConsumingContractUninitialized.

decrypt-to-view, decrypt-to-tx, client-setup take the renames.

Housekeeping

Drops the {#validating-permits} anchor I added to the ACP guide in #53. It existed only to keep this page's deep link alive across the rename; that link now points at the natural slug, so the workaround is gone rather than left to rot.

Vale and lint-docs.py exit 0 on all eight guides. mint validate and mint broken-links --check-anchors --check-redirects pass.

🤖 Generated with Claude Code

alexandrecarvalheira and others added 5 commits August 25, 2026 21:59
… consuming contract

0.7 returns one batch instead of per-item structs, so every example on
this page was wrong. execute() now yields [...hashes, signature], which
is inputs.length + 1 elements, and setConsumingContract is required
before it exists at all.

Documents the trap that has no compile-time signal: the consuming
contract is whichever contract runs FHE.asEuint*, not necessarily the
one you call. Adds setSecurityZone, which was never documented, and the
Encryptable factories now map to externalEuintXX rather than InEuintXX.

Verified against the 0.7.1 tarball and the published SDK docs: the
factory to Solidity table matches row for row, EncryptedItemInput and
asHashPlusProof resolve to zero files, and the 2048-bit limit stands.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
withPermit becomes withACP, withoutPermit becomes withoutACP, and
client.permits becomes the singular client.acp.

Checked against the published decryptForView and decryptForTx pages
rather than trusting the rename: the three withACP overloads, the
exactly-one-of rule on decryptForTx, and the { ctHash, decryptedValue,
signature } return shape all match.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
PermitNotFound and PermitInvalid no longer exist. They are ACPNotFound
and ACPInvalid, and the enum gained ACPExpired, ACPRevoked, ACPDenied and
ACPRequired, so callers no longer have to read the message to tell which
condition applied. Adds ConsumingContractUninitialized, which is what an
encryptInputs call now throws when the contract is not declared.

Codes taken from CofheErrorCode in the 0.7.1 tarball.

Drops the {#validating-permits} anchor from the ACP guide. It existed
only to keep this page's deep link alive across the rename, and that
link now points at the natural slug.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…eleted input structs

Every example on this page passed an InEuint32 struct, which 0.2.0
deletes. The contract now takes externalEuint32 plus a bytes proof, and
the hand-written viem ABI takes bytes32 and bytes rather than the
(ctHash, securityZone, utype, signature) tuple.

Drops assertCorrectEncryptedItemInput, which resolves to zero files in
0.7.1, and threads setConsumingContract through both client examples.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
defaultPermitExpiration is defaultACPExpiration in 0.7. Both schemas now
reject unknown keys, so the old spelling throws at client construction
rather than being silently dropped.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@alexandrecarvalheira
alexandrecarvalheira changed the base branch from docs/acp-guide to main August 26, 2026 02:32
@alexandrecarvalheira
alexandrecarvalheira merged commit 5850bb5 into main Aug 26, 2026
3 checks passed
@alexandrecarvalheira
alexandrecarvalheira deleted the docs/sweep-client-sdk-guides branch August 26, 2026 02:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant