Skip to main content

keyManagement

cifer-sdk API Reference v0.3.1

cifer-sdk API Reference / keyManagement

keyManagement

Key management operations for the SecretsController contract.

Remarks​

This namespace provides functions for:

  • Reading secret state and fees
  • Building transaction intents for secret creation and management
  • Parsing events from transaction receipts

Interfaces​

ParsedSecretCreatedEvent​

Defined in: keyManagement/events.ts:17

Parsed SecretCreated event

Properties​

secretId​

secretId: bigint

Defined in: keyManagement/events.ts:19

The new secret ID

owner​

owner: `0x${string}`

Defined in: keyManagement/events.ts:21

The owner address

secretType​

secretType: number

Defined in: keyManagement/events.ts:23

The secret type

log​

log: Log

Defined in: keyManagement/events.ts:25

Original log for reference

ParsedSecretSyncedEvent​

Defined in: keyManagement/events.ts:73

Parsed SecretSynced event

Properties​

secretId​

secretId: bigint

Defined in: keyManagement/events.ts:75

The secret ID that was synced

clusterId​

clusterId: number

Defined in: keyManagement/events.ts:77

The cluster ID where the secret is stored

publicKeyCid​

publicKeyCid: string

Defined in: keyManagement/events.ts:79

The IPFS CID of the public key

log​

log: Log

Defined in: keyManagement/events.ts:81

Original log for reference

ParsedDelegateUpdatedEvent​

Defined in: keyManagement/events.ts:118

Parsed DelegateUpdated event

Properties​

secretId​

secretId: bigint

Defined in: keyManagement/events.ts:120

The secret ID

newDelegate​

newDelegate: `0x${string}`

Defined in: keyManagement/events.ts:122

The new delegate address

log​

log: Log

Defined in: keyManagement/events.ts:124

Original log for reference

ReadParams​

Defined in: keyManagement/reads.ts:27

Parameters for read operations

Properties​

chainId​

chainId: number

Defined in: keyManagement/reads.ts:29

Chain ID

controllerAddress​

controllerAddress: `0x${string}`

Defined in: keyManagement/reads.ts:31

SecretsController contract address

readClient​

readClient: ReadClient

Defined in: keyManagement/reads.ts:33

Read client for making RPC calls

SecretsByWallet​

Defined in: keyManagement/reads.ts:229

Result of getSecretsByWallet

Properties​

owned​

owned: bigint[]

Defined in: keyManagement/reads.ts:231

Secret IDs owned by the wallet

delegated​

delegated: bigint[]

Defined in: keyManagement/reads.ts:233

Secret IDs delegated to the wallet

SecretsCountByWallet​

Defined in: keyManagement/reads.ts:288

Result of getSecretsCountByWallet

Properties​

ownedCount​

ownedCount: bigint

Defined in: keyManagement/reads.ts:290

Number of secrets owned

delegatedCount​

delegatedCount: bigint

Defined in: keyManagement/reads.ts:292

Number of secrets delegated

Functions​

parseSecretCreatedLog()​

parseSecretCreatedLog(log): ParsedSecretCreatedEvent

Defined in: keyManagement/events.ts:47

Parse a SecretCreated event from a transaction receipt log

Parameters​

log​

Log

The log entry to parse

Returns​

ParsedSecretCreatedEvent

Parsed event data

Throws​

KeyManagementError if the log is not a SecretCreated event

Example​

const receipt = await waitForReceipt(txHash);
const secretCreatedLog = receipt.logs.find(
  log => log.topics[0] === SECRETS_CONTROLLER_TOPICS.SecretCreated
);
if (secretCreatedLog) {
  const event = parseSecretCreatedLog(secretCreatedLog);
  console.log('New secret ID:', event.secretId);
}

parseSecretSyncedLog()​

parseSecretSyncedLog(log): ParsedSecretSyncedEvent

Defined in: keyManagement/events.ts:92

Parse a SecretSynced event from a log

This event indicates that a secret is now ready for use.

Parameters​

log​

Log

The log entry to parse

Returns​

ParsedSecretSyncedEvent

Parsed event data

parseDelegateUpdatedLog()​

parseDelegateUpdatedLog(log): ParsedDelegateUpdatedEvent

Defined in: keyManagement/events.ts:133

Parse a DelegateUpdated event from a log

Parameters​

log​

Log

The log entry to parse

Returns​

ParsedDelegateUpdatedEvent

Parsed event data

extractSecretIdFromReceipt()​

extractSecretIdFromReceipt(logs): bigint

Defined in: keyManagement/events.ts:172

Extract the secret ID from a createSecret transaction receipt

This is a convenience function that finds the SecretCreated event in a transaction receipt and extracts the secret ID.

Parameters​

logs​

Log[]

The logs from the transaction receipt

Returns​

bigint

The new secret ID

Throws​

KeyManagementError if no SecretCreated event is found

Example​

const receipt = await waitForReceipt(txHash);
const secretId = extractSecretIdFromReceipt(receipt.logs);
console.log('Created secret:', secretId);

getSecretCreationFee()​

getSecretCreationFee(params): Promise<bigint>

Defined in: keyManagement/reads.ts:54

Get the secret creation fee

This is the amount of native token (in wei) required to create a new secret.

Parameters​

params​

ReadParams

Read parameters

Returns​

Promise<bigint>

The fee in wei

Example​

const fee = await getSecretCreationFee({
  chainId: 752025,
  controllerAddress: '0x...',
  readClient,
});
console.log('Fee:', fee, 'wei');

getSecret()​

getSecret(params, secretId): Promise<SecretState>

Defined in: keyManagement/reads.ts:99

Get the full state of a secret

Parameters​

params​

ReadParams

Read parameters

secretId​

bigint

The secret ID to query

Returns​

Promise<SecretState>

The secret state

Throws​

SecretNotFoundError if the secret doesn't exist

Example​

const state = await getSecret({
  chainId: 752025,
  controllerAddress: '0x...',
  readClient,
}, 123n);

console.log('Owner:', state.owner);
console.log('Is syncing:', state.isSyncing);
console.log('Public key CID:', state.publicKeyCid);

getSecretOwner()​

getSecretOwner(params, secretId): Promise<`0x${string}`>

Defined in: keyManagement/reads.ts:158

Get the owner of a secret

Parameters​

params​

ReadParams

Read parameters

secretId​

bigint

The secret ID to query

Returns​

Promise<`0x${string}`>

The owner address

Throws​

SecretNotFoundError if the secret doesn't exist

getDelegate()​

getDelegate(params, secretId): Promise<`0x${string}`>

Defined in: keyManagement/reads.ts:196

Get the delegate of a secret

Parameters​

params​

ReadParams

Read parameters

secretId​

bigint

The secret ID to query

Returns​

Promise<`0x${string}`>

The delegate address (zero address if no delegate)

Throws​

SecretNotFoundError if the secret doesn't exist

getSecretsByWallet()​

getSecretsByWallet(params, wallet): Promise<SecretsByWallet>

Defined in: keyManagement/reads.ts:258

Get all secrets owned by or delegated to a wallet

Note: The returned arrays are unordered sets. The contract uses swap-and-pop for removals, so order is not stable.

Parameters​

params​

ReadParams

Read parameters

wallet​

`0x${string}`

The wallet address to query

Returns​

Promise<SecretsByWallet>

Object containing owned and delegated secret IDs

Example​

const secrets = await getSecretsByWallet({
  chainId: 752025,
  controllerAddress: '0x...',
  readClient,
}, '0xUser...');

console.log('Owned:', secrets.owned);
console.log('Delegated:', secrets.delegated);

getSecretsCountByWallet()​

getSecretsCountByWallet(params, wallet): Promise<SecretsCountByWallet>

Defined in: keyManagement/reads.ts:304

Get the count of secrets owned by or delegated to a wallet

This is more gas-efficient than getSecretsByWallet when you only need counts.

Parameters​

params​

ReadParams

Read parameters

wallet​

`0x${string}`

The wallet address to query

Returns​

Promise<SecretsCountByWallet>

Object containing owned and delegated counts

isSecretReady()​

isSecretReady(params, secretId): Promise<boolean>

Defined in: keyManagement/reads.ts:340

Check if a secret is ready (not syncing)

A secret is ready when isSyncing is false and publicKeyCid is set.

Parameters​

params​

ReadParams

Read parameters

secretId​

bigint

The secret ID to check

Returns​

Promise<boolean>

True if the secret is ready for encryption/decryption

isAuthorized()​

isAuthorized(params, secretId, address): Promise<boolean>

Defined in: keyManagement/reads.ts:356

Check if an address is authorized for a secret (owner or delegate)

Parameters​

params​

ReadParams

Read parameters

secretId​

bigint

The secret ID to check

address​

`0x${string}`

The address to check authorization for

Returns​

Promise<boolean>

True if the address is owner or delegate

buildCreateSecretTx()​

buildCreateSecretTx(params): TxIntentWithMeta

Defined in: keyManagement/tx-builders.ts:46

Build a transaction to create a new secret

The transaction must be sent with value equal to the secretCreationFee. Use getSecretCreationFee() to get the current fee before calling this.

Parameters​

params​

Transaction parameters

chainId​

number

Chain ID

controllerAddress​

`0x${string}`

SecretsController contract address

fee​

bigint

Secret creation fee (from getSecretCreationFee)

Returns​

TxIntentWithMeta

Transaction intent

Example​

// Get the fee first
const fee = await getSecretCreationFee({ chainId, controllerAddress, readClient });

// Build the transaction
const txIntent = buildCreateSecretTx({
  chainId: 752025,
  controllerAddress: '0x...',
  fee,
});

// Execute with your preferred method
const hash = await wallet.sendTransaction({
  to: txIntent.to,
  data: txIntent.data,
  value: txIntent.value,
});

buildSetDelegateTx()​

buildSetDelegateTx(params): TxIntentWithMeta

Defined in: keyManagement/tx-builders.ts:86

Build a transaction to set or update a delegate for a secret

Only the secret owner can set a delegate. Setting the delegate to the zero address removes the delegation.

Parameters​

params​

Transaction parameters

chainId​

number

Chain ID

controllerAddress​

`0x${string}`

SecretsController contract address

secretId​

bigint

Secret ID

newDelegate​

`0x${string}`

New delegate address

Returns​

TxIntentWithMeta

Transaction intent

Example​

const txIntent = buildSetDelegateTx({
  chainId: 752025,
  controllerAddress: '0x...',
  secretId: 123n,
  newDelegate: '0xDelegateAddress...',
});

buildRemoveDelegationTx()​

buildRemoveDelegationTx(params): TxIntentWithMeta

Defined in: keyManagement/tx-builders.ts:117

Build a transaction to remove a delegate from a secret

This is a convenience wrapper around buildSetDelegateTx that sets the delegate to the zero address.

Parameters​

params​

Transaction parameters

chainId​

number

Chain ID

controllerAddress​

`0x${string}`

SecretsController contract address

secretId​

bigint

Secret ID

Returns​

TxIntentWithMeta

Transaction intent

buildTransferSecretTx()​

buildTransferSecretTx(params): TxIntentWithMeta

Defined in: keyManagement/tx-builders.ts:162

Build a transaction to transfer ownership of a secret

Only the current owner can transfer a secret. If the secret has a delegate, the delegation will be cleared upon transfer.

Parameters​

params​

Transaction parameters

chainId​

number

Chain ID

controllerAddress​

`0x${string}`

SecretsController contract address

secretId​

bigint

Secret ID

newOwner​

`0x${string}`

New owner address

Returns​

TxIntentWithMeta

Transaction intent

Example​

const txIntent = buildTransferSecretTx({
  chainId: 752025,
  controllerAddress: '0x...',
  secretId: 123n,
  newOwner: '0xNewOwner...',
});