Releases · zama-ai/relayer-sdk

Documentation - release 0.4.x by @paulo-zama in #433
docs: sync delegate decryption documentation to release/0.4.x by @poppyseedDev in #437
docs: update LICENSE by @poppyseedDev in #443
fix: update package.json by @poppyseedDev in #444

Full Changelog: v0.4.2...v0.4.3

Contributors

poppyseedDev and paulo-zama

Assets 2

10 Apr 13:31

geoxel

v0.5.0-alpha.3

2cb48f6

v0.5.0-alpha.3 Pre-release

Pre-release

What's Changed

fix: remove v1 route and update tests for devnet v0.12 by @geoxel in #439
Deprecated FhevmInstanceConfig.relayerRouteVersion

New Contributors

@geoxel made their first contribution in #439

Full Changelog: v0.5.0-alpha.2...v0.5.0-alpha.3

Contributors

geoxel

Assets 2

30 Mar 11:04

isaacdecoded

v0.5.0-alpha.2

e833b38

v0.5.0-alpha.2 Pre-release

Pre-release

What's Changed

feat: construct extraData and add context signer fetching by @isaacdecoded in #418
fix: update license by @poppyseedDev in #419
docs: add mainnet relayer API key guide (#1193) by @paulo-zama in #425
docs(common): update the mainnet API key doc by @yuxizama in #427
docs: add delegate decryption documentation by @poppyseedDev in #428
fix: bind external signature verification to request by @isaacdecoded in #431

New Contributors

@paulo-zama made their first contribution in #425

Full Changelog: v0.4.2...v0.5.0-alpha.2

Contributors

isaacdecoded, poppyseedDev, and 2 other contributors

Assets 2

20 Mar 10:14

poppyseedDev

v0.5.0-alpha.1

7dd9c27

v0.5.0-alpha.1 Pre-release

Pre-release

Breaking Change: Context-Aware `extraData` for User Decryption (v0.5.0-alpha.1)

Starting with v0.5.0-alpha.1, the relayer SDK introduces KMS context-aware decryption. The extraData field — previously managed internally by the SDK — now carries a versioned context identifier that ties each decryption request to a specific KMS signer set. This enables the KMS to rotate its signer configuration (context switches) without breaking in-flight requests: each request and its verification are bound to the exact signer set that was active when the request was built.

What you need to change for user decrypt and delegated user decrypt flows:

The new fhevmInstance.getExtraData() method fetches the current KMS context and returns the properly formatted extraData value. You must pass the same extraData to both the EIP-712 builder and the decrypt call so that the signature and the request reference the same context.

// 1. Fetch extraData and build the EIP-712 message
const extraData = await fhevmInstance.getExtraData();

const eip712 = fhevmInstance.createEIP712(
  publicKey, contractAddresses, startTimestamp, durationDays,
  extraData,  // ← new required parameter
);

// 2. Have the user sign the EIP-712 message
const signature = await wallet.signTypedData(/* ... */);

// 3. Cache the signature + extraData pair for later use

Handling context rotation:

The KMS context rotates approximately every two weeks. You can cache the signature, but before submitting the decrypt request you should check whether the context has changed:

// 4. When ready to decrypt, fetch extraData again
const currentExtraData = await fhevmInstance.getExtraData();

// 5. If the context changed, the cached signature is invalid — re-sign
if (currentExtraData !== extraData) {
  // Context has rotated — rebuild EIP-712 with new extraData and re-sign
  const newEip712 = fhevmInstance.createEIP712(
    publicKey, contractAddresses, startTimestamp, durationDays,
    currentExtraData,
  );
  signature = await wallet.signTypedData(/* ... with newEip712 ... */);
  extraData = currentExtraData;
}

// 6. Submit the decrypt request with matching extraData + signature
const results = await fhevmInstance.userDecrypt(
  handleContractPairs, publicKey, privateKey, signature,
  userAddress, startTimestamp, durationDays,
  extraData,  // ← must match what was signed
);

The same pattern applies to the delegated user decrypt flow — call getExtraData(), pass it to createDelegatedUserDecryptEIP712(), and then to delegatedUserDecrypt().

Public decryptions are not affected. Since publicDecrypt does not involve a user signature, the SDK resolves the context internally — no code changes needed on your side.

Migration summary:

Method	Change
`getExtraData()`	New — call before building EIP-712 and again before decrypting
`createEIP712()`	New `extraData` parameter (6th argument)
`createDelegatedUserDecryptEIP712()`	New `extraData` parameter (7th argument)
`userDecrypt()`	New `extraData` parameter (8th argument, before `options`)
`delegatedUserDecrypt()`	New `extraData` parameter (9th argument, before `options`)
`publicDecrypt()`	No change — handled internally

The key rule: the extraData used in the EIP-712 signature must match the extraData passed to the decrypt call. Cache the signature freely, but re-check getExtraData() before submitting — if the context rotated, re-sign.