Migrating to 0.7

The 0.7 release renames permits to ACPs, replaces per-ciphertext input signatures with one signature per batch, and binds every encrypted input to the contract that will consume it. It also moves you to @fhenixprotocol/cofhe-contracts 0.2.0, which deletes the InEuintXX structs. Most projects need Solidity changes, not only TypeScript changes. There are no deprecation shims. Old names are removed, so the compiler finds most of the work for you.

Some of this migration produces no compile error at all. The silent changes section lists every case where the old code still builds and then misbehaves at runtime. Read it before you declare the upgrade finished.

Three packages move together

This is one migration across three independently versioned packages. Bumping a subset is the most common way to end up with errors that look like SDK bugs.

Package	Target	Notes
`@cofhe/*` (every package)	`0.7.1`	Keep them all on one version
`@fhenixprotocol/cofhe-contracts`	`0.2.0`	Use the stable release, not a `0.2.0-beta.*`
`fhenix-confidential-contracts`	`0.4.0`	Only if you use FHERC20 or confidential tokens

fhenix-confidential-contracts 0.4.0 depends on an exact @fhenixprotocol/cofhe-contracts@0.2.0. Leaving a beta pin in place resolves two copies of FHE.sol, and sharedEuint64 from one is not the same type as sharedEuint64 from the other. The resulting errors read like nonsense, so check the pin first. If you are coming from cofhejs rather than @cofhe/sdk, follow migrating from cofhejs first. If you are on 0.5.x, the Solidity work below is identical, because the InEuintXX structs did not change between 0.5 and 0.6.

Let the skill do the mechanical work

Most of this migration is mechanical, and the parts that are not deserve a conversation rather than a find and replace. Fhenix publishes an agent skill that drives the whole thing. It detects what your project uses, works in dependency order, shows you a diff before touching anything, and reports what it could not decide for you. The skill uses the open Agent Skill format, which Claude Code, Cursor, GitHub Copilot, VS Code, Codex, Gemini CLI, OpenCode, Roo, Kiro, and Goose all read. Drop the folder wherever your agent looks for skills, commonly .claude/skills/ or .cursor/skills/:

mkdir -p .claude/skills
curl -L https://github.com/FhenixProtocol/cofhesdk/archive/refs/heads/master.tar.gz \
  | tar -xz --strip-components=2 -C .claude/skills \
    '*/skills/cofhe-migrate-0-6-to-0-7'

You can also browse the skill on GitHub and copy the directory by hand. Then ask your agent to run it:

Migrate this project to @cofhe/sdk 0.7.1

It proposes each change as a diff and waits for your approval. Tell it to apply everything if you would rather review at the end. It stops and asks on the decisions that are genuinely yours:

A function taking two or more encrypted parameters.
Encrypted inputs produced in one place and consumed in another.
A contract you do not control on the other side of a handoff.
Persisted EncryptedItemInput records. They carry per-item signatures, which cannot be rebuilt from a batch signature.

Work contract-first

If you are doing this by hand, the order matters. The ABI you land on decides what every call site has to look like, so going backwards means rewriting the same call sites twice.

Bump the three packages

Resolve versions from the registry rather than copying them from a guide. Update the contract dependencies at the same time as the JavaScript ones.

Change your contracts

Move off the deleted InEuintXX structs, then decide which values cross a contract boundary.

Update config keys

These throw at client construction, so they surface the moment you boot.

Rename permits to ACPs

Sweeping the renames first makes every remaining TypeScript error a genuine shape problem rather than a missing identifier.

Update encrypt call sites

The batch result and the consuming contract land on the same lines, so do them together.

Contracts: inputs from a user

0.2.0 deletes the InEuintXX structs, the FHE.asEuint32(InEuint32) overloads, the Utils.inputFromEuint32 helpers, and ITaskManager.verifyInput. An encrypted value arriving from a user is now an externalEuintXX handle plus a bytes proof.

// Before
function setValue(InEuint32 memory inValue) public {
  _setStoredValue(FHE.asEuint32(inValue));   // the struct carried its own signature
}

// After
function setValue(externalEuint32 inValue, bytes memory proof) public {
  _setStoredValue(FHE.asEuint32(inValue, proof));
}

The signature moves out of the struct into a bytes parameter that immediately follows the handle it authenticates. This changes the ABI, so a contract coming from InEuintXX needs a redeploy. A contract that already takes (externalEuint32, bytes) for a single encrypted value needs no change and no redeploy. FHE.asEuint32(handle, proof) verifies that input as a batch of one, so a 0.7 signature works against the ABI you already deployed.

The proof does not have to be the last parameter. It has to follow the external* handle as a pair. Extra plain arguments can come after it, which is how ERC-7984’s confidentialTransferAndCall is shaped.

More than one encrypted value

One signature now covers all the handles in the batch, computed over them together. You cannot keep two separate (handle, proof) pairs, because verifying one handle against a signature covering two reverts. You can still keep the parameter names, which most projects prefer to an array:

function transfer(
  address to,
  externalEuint32 amount,
  externalEuint32 fee,
  bytes calldata signature
) public {
  externalEuint32[] memory packed = new externalEuint32[](2);
  packed[0] = amount;
  packed[1] = fee;
  euint32[] memory values = FHE.asEuint32s(packed, signature);
  // values[0] is amount, values[1] is fee
}

The array form, function transfer(address to, externalEuint32[] calldata values, bytes calldata signature), is shorter but collapses named parameters into indices. Either way the encrypted parameters must be adjacent, because they share one signature and there is no other way to tell which bytes belongs to them. For a batch mixing types, such as a euint32 with an ebool, call ITaskManager.batchVerifyInputs directly.

Values that cross a contract boundary

0.2.0 adds a sharedEuintXX type for encrypted values passed between contracts. Both directions count: a value handed over as an argument, and a value returned by a function that is not view. A view function returning an encrypted value is unaffected, because it never granted anything. This is the part of the migration the compiler cannot help with. The 0.6 spelling, an FHE.allowTransient grant plus a bare euintXX parameter, still compiles and still runs while both sides stay on it. It is also the part with a security consequence. A function taking a bare euintXX from outside can be turned into an oracle over every ciphertext the contract holds. FHE operations check the permission of the contract performing them, not of whoever called it. An attacker passes a handle the contract is allowed on, such as one read from its own storage, and gets back a value derived from it.

// Before: permission granted out of band, and the sharer cannot be verified
FHE.allowTransient(amount, address(token));
token.pull(amount);

// After: the type carries the permission, and the sharer is checked
token.pull(FHE.shareEuint64(amount, address(token)));

// On the receiving side
function pull(sharedEuint64 shared) external {
  euint64 amount = FHE.receiveEuint64Param(shared);
  ...
}

Both sides have to move in the same change. pull(euint64) and pull(sharedEuint64) are both bytes32 on the wire, so an unmigrated caller compiles against a migrated callee and then reverts at runtime with NotShared. Pick the receive form by how the value reached you. receiveEuint64Param checks the sharer against msg.sender and suits a value that arrived as an argument. receiveEuint64FromCall(shared, callee) checks it against the contract you called, and callee must be the address called in that same expression. Returning an encrypted value works the same way in reverse. Share the result with msg.sender, and unwrap it with the FromCall form:

// In Token
function swap(sharedEuint64 shared) external returns (sharedEuint64) {
  euint64 amountIn = FHE.receiveEuint64Param(shared);
  return FHE.shareEuint64(FHE.div(amountIn, FHE.asEuint64(2)), msg.sender);
}

// In Vault
euint64 out = FHE.receiveEuint64FromCall(token.swap(shared), address(token));
FHE.allowThis(out);

FHE.shareEuint64 reverts with SenderNotAllowed unless your contract is itself allowed on the handle. You cannot share what you cannot use. Sharing is single-use and transaction-scoped, so a share cannot be stored, replayed, or reconstructed from an event. To keep a received value past the transaction, call FHE.allowThis on the unwrapped euintXX. Anything you derive from it produces a new handle that needs its own FHE.allowThis before you store it.

Config keys

Five keys were renamed. In 0.6 an unknown key was silently dropped and the setting fell back to its default. Both schemas now reject unknown keys and name the replacement, so a stale key throws when you construct the client.

Before	After
`defaultPermitExpiration`	`defaultACPExpiration`
`react.shareablePermits`	`react.shareableACPs`
`react.autogeneratePermits`	`react.autogenerateACPs`
`react.permitExpirationOptions`	`react.acpExpirationOptions`
`react.defaultPermitExpirationSeconds`	`react.defaultACPExpirationSeconds`

If your 0.6 app set any of these, the setting was already being ignored and the default was in force. Behavior can change once it starts applying again. An expiration you believed was one day may have been running at the 30 day default.

Permits are now ACPs

“Permit” is now “ACP”, short for Access Control Permission, so that it is not confused with an ERC-2612 permit. The entry point moves and the client namespace is singular:

// Before
import { PermitUtils, type Permit, type Permission } from '@cofhe/sdk/permits';
const permit = await client.permits.createSelf();

// After
import { ACPUtils, type ACP, type ACPPublic } from '@cofhe/sdk/acps';
const acp = await client.acp.createSelf();

Decrypt builders follow the same rename: .withPermit() becomes .withACP() and .withoutPermit() becomes .withoutACP(). React hooks rename the same way. useCofhePermits becomes useCofheACPs, useCofheActivePermit becomes useCofheActiveACP, and the rest of the family follows the pattern. Rename only identifiers that resolve to a @cofhe/* import. A blind replace of Permit corrupts unrelated code, and the English words permitted and permitting are not renames. isPermittedCofheEnvironment and isAllowedWithPermission keep their names. For the full type table, the new scope model, and what the client gained, see Access Control Permissions.

Stored permits are dropped. They were signed with retired EIP-712 types and cannot verify against the upgraded ACL, so your users are prompted to sign again on first use. Nothing needs migrating, but it looks like data loss if you are not expecting it.

Encrypt call sites

Two changes land on the same lines. execute() returns a different shape, and you must now declare the consuming contract.

// Before
const [encA, encB] = await client.encryptInputs([a, b]).execute();
await contract.f(encA, encB);

// After
const [handleA, handleB, signature] = await client
  .encryptInputs([a, b])
  .setConsumingContract(contractAddress)
  .execute();
await contract.f([handleA, handleB], signature);

The result now holds one handle per input followed by a single signature, so it has inputs.length + 1 elements. Code that assumed the result matched the input count is off by one. setConsumingContract is required because the verifier binds the target contract into the signed digest, which stops a batch signed for one contract being replayed into another. Omitting it is a compile error in TypeScript, since encryptInputs() returns a builder without an execute() method.

The consuming contract is the contract that runs FHE.asEuint*, which is not always the contract you call. If your app calls vault.deposit(...) and the vault is what converts the value, the consuming contract is the vault. Naming the wrong one compiles, typechecks, and reverts at runtime. Trace the value to the FHE.asEuint* call.

The per-item input types are gone: EncryptedItemInput, EncryptedUint64Input, and the rest of that family. A value that used to be one of them is now a handle. These also break on your own helpers, where a fixture typed (encAmount: EncryptedUint64Input) fails at its definition rather than at the call site. asHashPlusProof() is removed, because its output is what execute() always returns now.

Silent changes

A clean build proves very little in this migration. Each of these compiles and then behaves differently:

Change	What happens
A bare `euintXX` parameter left unmigrated	Compiles, and keeps running while both sides stay on it. Can be a live disclosure path, not a style issue.
Only one side moved to `sharedEuintXX`	Both spellings are `bytes32` on the wire, so the call compiles and reverts with `NotShared`.
`receiveEuintXXFromCall` naming a trusted address instead of the callee	Checks who created the share rather than who handed it over. Exploitable.
A wrong-length destructure of the `execute()` result	Typechecks, then fails at runtime on the trailing signature.
A reordered or partial batch	The signature covers the exact ordered set that `execute()` produced. Compiles, then fails verification.
`ACPUtils.export()` on a self ACP	`0.6` serialized anything; `0.7` throws unless the ACP is a signed sharing ACP.
A transient allowance relied on across transactions	Mock transient storage is now real EIP-1153, so it expires with its own transaction rather than the block.
Overload selector strings and ERC-165 interface ids	`InEuint64` was a tuple; `externalEuint64` is a `bytes32`, so ids change. Recompute them.

Verify by exercising a round trip, not by compiling. For every bare-handle function you kept, ask whether an arbitrary caller can reach it with a handle the contract is allowed on. If they can, guard it with FHE.isAllowed(value, msg.sender).

Next steps

Check every version against the compatibility page.
Read the Access Control Permissions guide for the permission model in full.
Review encrypting inputs for the current builder API.

Introduction

Quick Start

Guides

Hardhat Plugin

Foundry Plugin

Examples

Reference

Three packages move together

Let the skill do the mechanical work

Work contract-first

Contracts: inputs from a user

More than one encrypted value

Values that cross a contract boundary

Config keys

Permits are now ACPs

Encrypt call sites

Silent changes

Next steps

​Three packages move together

​Let the skill do the mechanical work

​Work contract-first

​Contracts: inputs from a user

​More than one encrypted value

​Values that cross a contract boundary

​Config keys

​Permits are now ACPs

​Encrypt call sites

​Silent changes

​Next steps

Three packages move together

Let the skill do the mechanical work

Work contract-first

Contracts: inputs from a user

More than one encrypted value

Values that cross a contract boundary

Config keys

Permits are now ACPs

Encrypt call sites

Silent changes

Next steps