Skip to content

feat: scoped decryption with shared ACPs - #388

Merged
alexshchur merged 20 commits into
masterfrom
feat/acp-scoped-sharing
Oct 2, 2026
Merged

alexshchur merged 20 commits into
masterfrom
feat/acp-scoped-sharing

Conversation

@alexshchur

Copy link
Copy Markdown
Contributor

Why

An app that shows a user data shared with them through an ACP hits four problems today:

  • Importing a share switches the whole app. importShared and importFromChain always 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.
  • The React hooks decrypt only with the active ACP. The SDK builder takes .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.
  • Shared plaintext outlives the share. Decrypted values are persisted under a key that ignores the ACP, so a value stays readable from cache after the share is revoked or expires, and the sharer's data ends up in the recipient's persisted store.
  • Validity checks revert instead of answering. The only way to learn why an ACP doesn't work is to catch and decode ACL reverts; revocation is invisible until expiry.

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/sdk

  • client.acp.importShared(input, { activate: false }) and importFromChain(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 handle allowed / out-of-scope / issuer-not-allowed. For the issuer's copy of a share it reports expiry and revocation.
  • ACL reverts are recognised across viem copies and when reported only as text (custom error 0x…); this also fixes checkValidityOnChain in those setups.
  • @cofhe/sdk/acps exports the on-chain sharing pieces: registry and revoker ABIs, toChainShare, computeShareId, shareIdOfChainShare, getAclServedAddresses.

@cofhe/react

  • <CofheACPScope acp> and a per-hook acp option on useCofheReadContractAndDecrypt, useCofheReadContract(s) and useCofheTokenDecryptedBalance decrypt 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().status reports it, and SNAPSHOT shares flag values they don't list with isOutOfScope.
  • The decrypt cache key gains the chosen ACP's hash; plaintext decrypted with a non-self ACP is never persisted and is dropped when the ACP is removed or expires.
  • Sharing hooks are exported: useCofheIncomingShares, useCofheShareOnChain, useCofheImportShared({ activate }), useCofheRemoveShare, useCofheRevokeACP, useCofheACPStatus. useCofheDecrypt is exported.
  • useCofheACPs({ chainId?, type? }) replaces useCofheAllACPs, which stays as a deprecated alias.

Docs

A new React page, "ACPs in React" (/react/acp), and checkAccess on the SDK ACP page.

Compatibility

  • The decrypt cache key has a fifth segment; entries persisted under the old key are refetched once.
  • Deprecated, still exported: useCofheAllACPs, and the package-internal useIncomingShares, useShareOnChain, useImportFromChain, useRemoveShare.
  • Changesets: @cofhe/sdk patch ×3, @cofhe/react minor ×2 and patch ×4.

Tests

  • SDK: 453 unit tests pass (10 new for checkAccess and the revert parsing, 8 for the import option).
  • React: 50 unit tests; Anvil end-to-end suite 24/24 including two new files, react-acp-scope (scope, cache, expiry, revocation, out-of-scope) and react-sharing-hooks (share → discover → import → status → dismiss → revoke).
  • Node end-to-end on Anvil: acp-check-access covers every status.
  • The docs site builds; every example on the React page typechecks against the package exports.

🤖 Generated with Claude Code

alexshchur and others added 15 commits September 29, 2026 10:32
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>

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

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-bot

changeset-bot Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: b7c7915

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages
Name Type
@cofhe/sdk Minor
@cofhe/react Minor
@cofhe/abi Minor
@cofhe/hardhat-3-plugin Minor
@cofhe/hardhat-plugin Minor
@cofhe/mock-contracts Minor
@cofhe/site Minor
@cofhe/example-react Minor
@cofhe/foundry-plugin Minor

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

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Vercel previews (commit b7c7915)

Project Deployment Updated
docs Visit Preview Oct 2, 2026 16:30 UTC
react Visit Preview Oct 2, 2026 16:32 UTC

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>
alexshchur and others added 3 commits October 1, 2026 14:39
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>

@architect-dev architect-dev left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

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>

This branch was successfully deployed

2 active deployments
Preview – react — b7c79156 Deployed Oct 2, 2026 by github-actions[bot]
Preview – docs — b7c79156 Deployed Oct 2, 2026 by github-actions[bot]
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.

2 participants