keyManagement
cifer-sdk API Reference v0.5.6
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
The log entry to parse
Returns
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
The log entry to parse
Returns
Parsed event data
parseDelegateUpdatedLog()
parseDelegateUpdatedLog(
log):ParsedDelegateUpdatedEvent
Defined in: keyManagement/events.ts:133
Parse a DelegateUpdated event from a log
Parameters
log
The log entry to parse
Returns
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
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
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
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
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
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
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:341
Check if a secret is ready (not syncing)
A secret is ready when isSyncing is false and publicKeyCid is non-empty (new secrets use the on-chain placeholder; fetch the real key from blackbox).
Parameters
params
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:357
Check if an address is authorized for a secret (owner or delegate)
Parameters
params
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
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
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
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
Transaction intent
Example
const txIntent = buildTransferSecretTx({
chainId: 752025,
controllerAddress: '0x...',
secretId: 123n,
newOwner: '0xNewOwner...',
});