Access Control Permissions (ACP)

An Access Control Permission (ACP) is an EIP-712 signature that authorizes decryption of confidential data. The issuer field identifies who is reading the data, and that address must already have been granted access onchain with FHE.allow(handle, address). When you use an ACP, CoFHE validates it against the ACL contract to confirm the issuer really holds that access. Every ACP carries a sealing keypair. The public key goes to CoFHE so it can re-encrypt the result for the holder. The private key stays on the client and unseals the value when it comes back.

ACPs were called permits before 0.7. The name changed so they are not confused with an ERC-2612 permit, which is a different thing entirely. If you are upgrading, see migrating to 0.7. This page uses “ACP” throughout.

When you need one

decryptForView always requires an ACP.
decryptForTx depends on the contract’s ACL policy for that handle. If the policy lets anyone decrypt, use .withoutACP(). If it restricts decryption, use .withACP(...).

Prerequisites

Create and connect a client. ACPs are scoped to a chainId and account pair.

Quick start

client.acp is the recommended API. It signs with the connected wallet and manages the store for you. ACPUtils is the lower-level alternative when you want direct control over signing and storage. Note the namespace is singular: client.acp, not client.acps.

await client.connect(publicClient, walletClient);

// Returns the active self ACP if there is one, otherwise creates and signs it.
const acp = await client.acp.getOrCreateSelfACP();

import { ACPUtils, setACP, setActiveACPHash } from '@cofhe/sdk/acps';

const acp = await ACPUtils.createSelfAndSign(
  { issuer: walletClient.account.address },
  publicClient,
  walletClient
);

const chainId = await publicClient.getChainId();
const account = walletClient.account.address;
setACP(chainId, account, acp);
setActiveACPHash(chainId, account, acp.hash);

After this the active ACP is picked up automatically by decryptForView(...).execute() and by decryptForTx(...).withACP().execute().

The three types

Type	Who signs	Use for
`self`	Issuer only	Decrypting your own data. The common case.
`sharing`	Issuer only	A shareable offer the issuer creates for a recipient
`recipient`	Recipient, carrying the issuer signature	The imported ACP after the recipient signs it

expiration is a unix timestamp in seconds and defaults to 7 days from creation. The client-wide defaultACPExpiration config key is a separate setting that defaults to 30 days. Creating an ACP through client.acp.* stores it and makes it active.

Creating a self ACP

A self ACP lets you decrypt data that was allowed to your own address.

await client.connect(publicClient, walletClient);

const acp = await client.acp.createSelf({
  issuer: walletClient.account.address,
  name: 'My self ACP',
});

acp.type; // 'self'
acp.hash; // deterministic hash

createSelf always creates a new one. getOrCreateSelfACP() reuses the active ACP when there is one, which is what most applications want.

Narrowing what an ACP can read

0.7 adds a scope to every ACP. An unscoped ACP covers everything the issuer can read, which is rarely what you want to hand to someone else.

Scope	Value	Covers
`Global`	`0`	Every value the issuer can read
`Contract`	`1`	The issuer’s values readable by the listed `contracts`
`Handles`	`2`	Only the listed `handles`, as bytes32 hex strings

const acp = await client.acp.createSharing({
  issuer: walletClient.account.address,
  recipient,
  contracts: [auctionAddress],   // scope narrows to this contract
  name: 'Auction results',
});

A scope only ever narrows the issuer’s existing access. It cannot grant access the issuer does not already hold, so scoping is not a way to delegate something you were never allowed to read. It also does not retroactively narrow ACPs you already issued.

Handles are bytes32 hex strings here, not bigints. If you are carrying handle values around as bigints, convert before putting them in an ACP. An issuer can delegate their ACL access to a recipient, who can then decrypt the issuer’s data without holding their own FHE.allow grant. There are two routes: pass the offer yourself, or post it onchain.

Passing the offer yourself

Issuer creates a sharing ACP

const sharingAcp = await client.acp.createSharing({
  issuer: walletClient.account.address,
  recipient,
  name: 'Share with recipient',
});

Issuer exports it

import { ACPUtils } from '@cofhe/sdk/acps';

const exported = ACPUtils.export(sharingAcp);

The exported JSON holds no sensitive data and can travel over any channel.

ACPUtils.export throws unless the ACP is a signed sharing ACP. In 0.6 the equivalent call serialized anything you gave it. A call that used to always work, such as one made during a render, now always throws on a self ACP. Gate it on acp.type === 'sharing'.Never share the output of serialize(acp). That is for local persistence and contains the sealing private key.

Recipient imports and signs

const recipientAcp = await client.acp.importShared(exported);

recipientAcp.type; // 'recipient'

Importing generates a fresh sealing key for the recipient.

The issuer can instead post the signed offer to a registry, so the recipient discovers it without a side channel.

// Issuer
await client.acp.shareOnChain(sharingAcp);

// Recipient
const shares = await client.acp.getIncomingShares();
const recipientAcp = await client.acp.importFromChain(shares[0]);

dismissShare(shareId) clears an entry the recipient does not want, and cancelShare withdraws one the issuer posted.

Revoking access

An issuer can revoke an ACP they created, which matters when a sharing ACP has left their control.

await client.acp.revokeACP(acp.hash);
await client.acp.revokeAllACPs();

const revoked = await client.acp.isACPRevoked(acp.hash);

Revocation is checked when the ACP is used, so it applies to copies the issuer no longer holds.

Managing stored ACPs

The SDK keeps every stored ACP and one active ACP hash per chainId and account.

const acps = client.acp.getACPs();
Object.keys(acps); // ACP hashes

const active = client.acp.getActiveACP();
client.acp.selectActiveACP(someACPHash);

client.acp.removeACP(acpHash);
client.acp.removeActiveACP();

Validating

ACPUtils.validate enforces the full check: schema, signed, and not expired. The decrypt flows call it for you and surface failures as typed errors, so validate manually only when you want to inspect or filter ACPs first.

Function	Checks	On failure
`ACPUtils.validate(acp)`	Schema, signed, and not expired	Throws
`ACPUtils.validateSchema(acp)`	Schema only	Throws on schema failure, ignores expiry and signatures

Use validateSchema on an ACP that arrived over the wire, when you want to reject a malformed payload before caring about expiry. For inspection without exception handling, ValidationUtils returns a typed result:

import { ValidationUtils } from '@cofhe/sdk/acps';

const result = ValidationUtils.isValid(acp);

result.valid; // boolean
result.error; // 'invalid-schema' | 'expired' | 'not-signed' | null

Function	Returns	Use for
`ValidationUtils.isValid(acp)`	`ValidationResult`	The full check without throwing
`ValidationUtils.isSignedAndNotExpired(acp)`	`ValidationResult`	Skipping the schema parse when you already validated shape
`ValidationUtils.isSigned(acp)`	`boolean`	Whether it carries a signature on the appropriate side
`ValidationUtils.isExpired(acp)`	`boolean`	Comparing `acp.expiration` to now

Match on result.error to render a precise message:

switch (ValidationUtils.isValid(acp).error) {
  case 'expired':        return 'This ACP has expired. Please sign again.';
  case 'not-signed':     return 'ACP is awaiting signature.';
  case 'invalid-schema': return 'Imported ACP is malformed.';
  case null:             return null;
}

Persistence and security

ACPs are stored per chainId and account. On the web the store is localStorage under the key cofhesdk-acps.
A stored ACP contains the sealing private key. Treat it as a secret, and never hand a serialized ACP to another user.
To share access, use ACPUtils.export, which strips the sensitive fields.

Permits stored by 0.6 are dropped on upgrade. They were signed with EIP-712 types the upgraded ACL no longer accepts, so they cannot verify and are discarded when the store loads. Your users are prompted to sign again. Nothing needs migrating, but it looks like data loss if you are not expecting it.

Introduction

Quick Start

Guides

Hardhat Plugin

Foundry Plugin

Examples

Reference

When you need one

Prerequisites

Quick start

The three types

Creating a self ACP

Narrowing what an ACP can read

Passing the offer yourself

Revoking access

Managing stored ACPs

Validating

Persistence and security

​When you need one

​Prerequisites

​Quick start

​The three types

​Creating a self ACP

​Narrowing what an ACP can read

​Sharing with another account

​Passing the offer yourself

​Sharing onchain

​Revoking access

​Managing stored ACPs

​Validating

​Persistence and security

When you need one

Prerequisites

Quick start

The three types

Creating a self ACP

Narrowing what an ACP can read

Sharing with another account

Passing the offer yourself

Sharing onchain

Revoking access

Managing stored ACPs

Validating

Persistence and security