Repository navigation
feat: scoped decryption with shared ACPs - #388
Merged
Merged
Conversation
importShared and importFromChain always made the imported ACP the active
one, so every decrypt that uses the active ACP switched to the issuer's
data. Apps that show a shared view next to the user's own balances had
to rebuild the import from ACPUtils.importSharedAndSign + setACP.
Both now take `{ activate?: boolean }` (default true). With
`activate: false` the ACP is stored and the active hash is left alone.
The internal createACPWithSign already had the flag; this exposes it.
importShared's second argument widens from `clients` to
`{ activate?, publicClient?, walletClient? }`; passing
`{ publicClient, walletClient }` keeps working.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The React read and decrypt hooks could only decrypt with the active ACP,
so showing data shared through another ACP meant switching the active
ACP for the whole app, or rebuilding the hooks on top of the SDK
decrypt builder, which already takes `.withACP(acp)`.
- `<CofheACPScope acp={acp | hash}>` sets the ACP for everything below;
`useCofheACPScope()` reads it. Innermost scope wins.
- `useCofheReadContractAndDecrypt`, `useCofheReadContract`,
`useCofheReadContracts` and `useCofheTokenDecryptedBalance` take an
`acp` option that wins over the scope.
- Decrypts pass the chosen ACP with `.withACP(acp)`; ACP gating and
`disabledDueToMissingValidACP` check the chosen ACP. A hash that is not
stored, or an expired ACP, disables the scope instead of falling back
to the active ACP.
- Inside a scope `useCofheTokenDecryptedBalance` reads the ACP issuer
balance unless given an account.
- The decrypt cache key gains a fifth segment, the chosen ACP hash
(`undefined` for the active ACP). Without it a scoped decrypt answered
an unscoped read of the same handle from cache, showing shared data
outside the scope.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Decrypts were persisted to storage and stayed readable from cache after the ACP that produced them was removed or expired. For a shared ACP that meant the issuer data stayed on the recipient device after access ended. - Decrypts made with a non-self ACP are not persisted (`meta.persist`). - `CofheProvider` watches the ACP store and drops every decrypt cached under the hash of an ACP that leaves it (`removeACP`, `resetStore`). - A chosen ACP that turns invalid while in use drops its decrypts too. `<CofheACPScope>` and the per-hook `acp` option re-render at the ACP expiry, so that happens while the view stays mounted. Revocation is not detected here: that needs an on-chain check. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…AllACPs` (R10)
`useCofheAllACPs` returned only the connected account ACPs on the
connected chain, not all ACPs, and took no chain, unlike
`useCofheActiveACP(chainId)`. Listing received shares meant filtering
its result by type.
`useCofheACPs({ chainId?, type? })` returns the same list on the given
chain (connected by default), optionally narrowed to one type.
`useCofheAllACPs` stays as a deprecated alias of `useCofheACPs()`.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
A section on the ACP page that walks through the recipient side: import
a share with `activate: false`, find it later with
`useCofheACPs({ type: 'recipient' })`, and wrap the view in
`<CofheACPScope>`. Examples cover a scoped token balance, a scoped
contract read that uses `useCofheACPScope()` for the issuer, the
per-hook `acp` option next to the user own balance, and what happens to
decrypted values on removal, expiry and revocation. The short React note
under "Recipient imports and signs" now links here.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Open the React section with one AccessPage that places every piece: the import, the received-shares list, the scope around the shared view, and the per-hook `acp` option outside it. The steps below then define each component. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The persistence rule looked only at explicitly chosen ACPs, so a shared ACP made active (the default import, or activation in a UI) still had its plaintext written to storage. The rule now checks the type of the ACP the decrypt actually uses: only a self ACP persists. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The shared-view guide is React-specific, so it moves from the SDK ACP
page to a new React page, /react/acp ("ACPs in React"), listed in the
React sidebar. The SDK page keeps a one-line link under "Recipient
imports and signs".
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…a revert (R4) The ACL reverts for an expired, revoked or wrongly signed ACP, and the only SDK helper (`checkValidityOnChain`) turned that into a thrown error, so apps had to catch and interpret reverts to tell the user why an ACP does not work. - `client.acp.checkAccess(acp, handle?)` and `ACPUtils.checkAccessOnChain` return an `ACPAccessStatus`: `valid`, `expired`, `revoked` or an invalid signature; with a handle, `allowed`, `out-of-scope` or `issuer-not-allowed` (one extra `isAllowed` read tells the last two apart). Network errors still throw. - ACL reverts are recognized by error name instead of `instanceof`: a public client from another copy of viem (an app bringing its own) never matched the class check, so the revert name was lost. This also fixes `checkValidityOnChain` in that setup. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Some transports drop the structured error data of a failed eth_call and
report the revert only in the message ("custom error 0xcbd3a966"). The
revert parser knew only the Hardhat "return data: 0x..." form, so
`checkAccess` threw instead of returning `revoked`. It now also
decodes the selector from that message.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
A scoped view kept decrypting with a revoked share until the ACP expired or was removed, and a SNAPSHOT share still sent values it does not list to the threshold network, where they could only fail. - `<CofheACPScope>` and the per-hook `acp` option check the chosen ACP with `client.acp.checkAccess` when mounted, every minute and on window focus. `useCofheACPScope()` exposes `status`; the scope decrypts only while it is `valid`, so a revocation disables it and drops its values (R3 cleanup). After a failed re-check an earlier `valid` is not trusted (`unverified`). - For a SNAPSHOT (handle-scope) ACP, a value the share does not list is reported as `isOutOfScope` and never sent for decryption. LIVE shares are not pre-checked. - The React guide covers both. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
A sharing ACP held by its issuer carries no recipient signature until the recipient imports it, so the ACL validity check rejected every one of them with `invalid-recipient-signature`. For that copy the check now answers what can change for the issuer: `expired`, `revoked` (via the revoker) or `valid`. Handle checks are unchanged. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The registry hooks (`useIncomingShares`, `useShareOnChain`,
`useImportFromChain`, `useRemoveShare`) existed for the package UI but were
not exported, and there were no hooks for revoking an ACP or reading its
status, so apps rebuilt all of them.
- `useCofheIncomingShares`: the registry inbox, polled; shares already
imported by the connected account are left out; `enabled` and
`refetchIntervalMs` options.
- `useCofheImportShared({ activate })`: exported JSON or an `IncomingShare`;
returns the imported ACP.
- `useCofheShareOnChain`, `useCofheRemoveShare`, `useCofheRevokeACP`: resolve
once mined; a revoke invalidates the ACP status so it re-reads at once.
- `useCofheACPStatus(acp | hash)`: the on-chain status used by
`<CofheACPScope>`, for any ACP.
- The package-internal names stay as deprecated aliases.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… (R7) The share registry and revoker ABIs, the registry payload of a sharing ACP (`toChainShare`) and its id (`computeShareId`) were private to the client, so an app sending those writes through its own transaction path had to keep a copy of each and hope it stayed in sync. The ACL-served address lookup was private too. They move to `acps/registry.ts` and `acps/onchain-utils.ts` and are exported from `@cofhe/sdk/acps`; the client uses the same functions. The revoker ABI is renamed `ACP_REVOKER_ABI` (was the internal `ACP_VALIDATOR_ABI`). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Only reads that go through a contract call could be decrypted with the package hooks; a bare ciphertext handle (e.g. a transfer amount listed in a handle-scope share) needed the SDK builder directly, outside the cache, the ACP gating and the scope. The hook is now exported, with the same `acp` option and scope behaviour as `useCofheReadContractAndDecrypt`. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
There was a problem hiding this comment.
Claude Code Review
This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.
Tip: disable this comment in your organization's Code Review settings.
🦋 Changeset detectedLatest commit: b7c7915 The changes in this PR will be included in the next version bump. This PR includes changesets to release 9 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
|
Vercel previews (commit
|
The page stays at /react/acp, reachable by link, until the React docs are finalized for the public site. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The ACPAccessStatus comment had been inserted between the IncomingShare comment and its declaration, so IncomingShare lost its description. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Only decrypts made with a chosen ACP carried its hash in the cache key; decrypts made with the active ACP shared one key whatever the active ACP was. After the active ACP changed (e.g. a received share made active, then the user own ACP again) the cached value decrypted with the previous ACP was served to the new one, and removing an active received ACP left its values in memory. The key now always holds the hash of the ACP that decrypts. Removing an ACP drops its values whether it was chosen or active; an invalid ACP drops its values unless it is the user own active ACP. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`useCofheIncomingShares` returned a copy of the query result with its own `data`. Copying reads every property of react-query's result, which turns off its tracked-property optimisation, so every consumer re-rendered on any change to the query. The already-imported shares are now filtered in the query's `select` and the result is returned as is. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Oct 2, 2026
architect-dev
approved these changes
Oct 2, 2026
architect-dev
left a comment
Collaborator
There was a problem hiding this comment.
I think we should merge these changesets into a single changeset.
I didn't look at the react stuff, but the sdk acp changes look good to me.
One changeset for the scoped-sharing work: @cofhe/sdk patch, @cofhe/react minor, the nine former entries kept as one bullet each, grouped by package. The cache entry now says decrypts are keyed by the ACP that made them, as the later cache fix does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4 tasks done
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
An app that shows a user data shared with them through an ACP hits four problems today:
importSharedandimportFromChainalways make the imported ACP the active one, so every decrypt in the app starts showing the sharer's data instead of the user's own..withACP(acp), but no hook can pass one through, so a scoped view has to be built outside the hooks, without their cache, gating and invalidation.Alongside these, the sharing hooks already in the package weren't exported, and the registry helpers apps need for their own transaction paths were private.
What
@cofhe/sdkclient.acp.importShared(input, { activate: false })andimportFromChain(share, { activate: false })store a share without making it active.{ publicClient, walletClient }as the second argument keeps working.client.acp.checkAccess(acp, handle?)returns an ACP's on-chain status as a value:valid/expired/revoked/ an invalid signature, and per handleallowed/out-of-scope/issuer-not-allowed. For the issuer's copy of a share it reports expiry and revocation.custom error 0x…); this also fixescheckValidityOnChainin those setups.@cofhe/sdk/acpsexports the on-chain sharing pieces: registry and revoker ABIs,toChainShare,computeShareId,shareIdOfChainShare,getAclServedAddresses.@cofhe/react<CofheACPScope acp>and a per-hookacpoption onuseCofheReadContractAndDecrypt,useCofheReadContract(s)anduseCofheTokenDecryptedBalancedecrypt with a chosen ACP while the active ACP stays untouched. The scope checks its ACP on-chain on mount, every minute and on window focus;useCofheACPScope().statusreports it, and SNAPSHOT shares flag values they don't list withisOutOfScope.useCofheIncomingShares,useCofheShareOnChain,useCofheImportShared({ activate }),useCofheRemoveShare,useCofheRevokeACP,useCofheACPStatus.useCofheDecryptis exported.useCofheACPs({ chainId?, type? })replacesuseCofheAllACPs, which stays as a deprecated alias.Docs
A new React page, "ACPs in React" (
/react/acp), andcheckAccesson the SDK ACP page.Compatibility
useCofheAllACPs, and the package-internaluseIncomingShares,useShareOnChain,useImportFromChain,useRemoveShare.@cofhe/sdkpatch ×3,@cofhe/reactminor ×2 and patch ×4.Tests
checkAccessand the revert parsing, 8 for the import option).react-acp-scope(scope, cache, expiry, revocation, out-of-scope) andreact-sharing-hooks(share → discover → import → status → dismiss → revoke).acp-check-accesscovers every status.🤖 Generated with Claude Code