> For the complete documentation index, see [llms.txt](https://docs.bloxchain.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bloxchain.app/protocol/api-reference.md).

# API reference

Complete reference for Bloxchain TypeScript SDK classes and methods. Contract source of truth: Solidity in `contracts/core/`. See [TECHNICAL\_OVERVIEW.md](https://github.com/PracticalParticle/Bloxchain-Protocol/blob/99beac2d6e6d7567c23b25cecaf6f4053f31c987/TECHNICAL_OVERVIEW.md) and [contracts/core/AUDIT.md](https://github.com/PracticalParticle/Bloxchain-Protocol/blob/99beac2d6e6d7567c23b25cecaf6f4053f31c987/contracts/core/AUDIT.md).

## 📚 **Core Classes**

### **SecureOwnable**

The `SecureOwnable` class provides type-safe access to SecureOwnable contracts.

#### **Constructor**

```typescript
constructor(
  client: PublicClient,
  walletClient?: WalletClient,
  contractAddress: Address,
  chain: Chain
)
```

**Parameters:**

* `client`: Viem public client for read operations
* `walletClient`: Optional wallet client for write operations
* `contractAddress`: Address of the deployed contract
* `chain`: Chain configuration

#### **Read Methods**

**`owner(): Promise<Address>`**

Returns the current owner of the contract.

```typescript
const owner = await secureOwnable.owner()
```

**`getTimeLockPeriodSec(): Promise<bigint>`**

Returns the time lock period in seconds.

```typescript
const period = await secureOwnable.getTimeLockPeriodSec()
```

**`getBroadcasters(): Promise<Address[]>`**

Returns all broadcaster addresses for the broadcaster role.

```typescript
const broadcasters = await secureOwnable.getBroadcasters()
```

**`getRecovery(): Promise<Address>`**

Returns the recovery address.

```typescript
const recovery = await secureOwnable.getRecovery()
```

**`initialized(): Promise<boolean>`**

Returns whether the contract is initialized.

```typescript
const isInit = await secureOwnable.initialized()
```

#### **Write Methods**

**`transferOwnershipRequest(options?: TransactionOptions): Promise<TransactionResult>`**

Requests a time-delayed transfer of the **owner** role to the **recovery address at request time** (snapshotted in the pending tx). Rotating recovery later does not change that stored beneficiary. See the **Ownership transfer vs recovery** section in the [SecureOwnable guide](/protocol/secure-ownable.md).

```typescript
const result = await secureOwnable.transferOwnershipRequest({ from: account.address })
```

**`transferOwnershipDelayedApproval(txId: bigint, options?: TransactionOptions): Promise<TransactionResult>`**

Approves a pending ownership transfer after the time lock. Callable by **current** owner or **current** recovery; execution still assigns owner to the address snapshotted at request time (may differ from `getRecovery()` at approval time).

**`updateBroadcasterRequest(newBroadcaster: Address, currentBroadcaster: Address, options?: TransactionOptions): Promise<TransactionResult>`**

Requests a broadcaster update by address pair: replace (`currentBroadcaster` → `newBroadcaster`), add (`currentBroadcaster` = zero), or revoke (`newBroadcaster` = zero).

```typescript
const [current] = await secureOwnable.getBroadcasters()
const result = await secureOwnable.updateBroadcasterRequest(
  '0x...', // new broadcaster (or zero to revoke)
  current, // existing broadcaster (or zero to add)
  { from: account.address }
)
```

**`updateRecoveryRequestAndApprove(metaTx: MetaTransaction, options?: TransactionOptions): Promise<TransactionResult>`**

Requests and approves a recovery update using a signed meta-transaction (owner signs, broadcaster submits).

**`updateTimeLockRequestAndApprove(metaTx: MetaTransaction, options?: TransactionOptions): Promise<TransactionResult>`**

Requests and approves a time lock period update using a signed meta-transaction.

### **RuntimeRBAC**

The `RuntimeRBAC` class provides type-safe access to RuntimeRBAC contracts. It extends `BaseStateMachine` and provides batch-based role configuration.

#### **Constructor**

```typescript
constructor(
  client: PublicClient,
  walletClient?: WalletClient,
  contractAddress: Address,
  chain: Chain
)
```

#### **Read Methods**

**`getRole(roleHash: Hex): Promise<Role>`**

Gets role information by hash. Return shape includes `roleName`, `roleHash` (or `roleHashReturn`), `maxWallets`, `walletCount`, `isProtected`.

**`hasRole(roleHash: Hex, wallet: Address): Promise<boolean>`**

Checks if a wallet has a specific role.

```typescript
const hasRole = await runtimeRBAC.hasRole('0x...', '0x...')
```

**`getAuthorizedWallets(roleHash: Hex): Promise<Address[]>`**

Gets all authorized wallets for a role.

```typescript
const wallets = await runtimeRBAC.getAuthorizedWallets('0x...')
```

**`getWalletRoles(wallet: Address): Promise<Hex[]>`**

Gets all roles assigned to a wallet.

```typescript
const roles = await runtimeRBAC.getWalletRoles('0x...')
```

**`getSupportedRoles(): Promise<Hex[]>`**

Returns the list of supported roles.

```typescript
const roles = await runtimeRBAC.getSupportedRoles()
```

**`getFunctionSchema(functionSelector: Hex): Promise<FunctionSchema>`**

Gets function schema information.

```typescript
const schema = await runtimeRBAC.getFunctionSchema('0xa9059cbb')
```

#### **Write Methods**

**`roleConfigBatchRequestAndApprove(metaTx: MetaTransaction, options?: TransactionOptions): Promise<TransactionResult>`**

Requests and approves a RBAC configuration batch using a meta-transaction.

```typescript
const txHash = await runtimeRBAC.roleConfigBatchRequestAndApprove(
  metaTx,
  { from: account.address }
)
```

**`roleConfigBatchExecutionParams(definitionAddress: Address, actions: RoleConfigAction[]): Promise<Hex>`**

Calls the deployed RuntimeRBACDefinitions contract to build execution params (single source of truth with Solidity).

```typescript
const definitionAddress = deployedAddresses.sepolia.RuntimeRBACDefinitions.address; // from deployed-addresses.json for your chain
const executionParams = await runtimeRBAC.roleConfigBatchExecutionParams(definitionAddress, actions);
// Or use definition helper: import { roleConfigBatchExecutionParams } from '@bloxchain/sdk'; const executionParams = await roleConfigBatchExecutionParams(client, definitionAddress, actions);
```

## 📝 **Types & Interfaces**

### **Core Types**

```typescript
type Address = `0x${string}`
type Hash = `0x${string}`


type OperationType = 
  | 'OWNERSHIP_TRANSFER'
  | 'BROADCASTER_UPDATE'
  | 'RECOVERY_UPDATE'
  | 'TIMELOCK_UPDATE'
  | 'ROLE_EDITING_TOGGLE'
  | 'CUSTOM'

type TxAction = 
  | 'EXECUTE_TIME_DELAY_REQUEST'
  | 'EXECUTE_TIME_DELAY_APPROVE'
  | 'EXECUTE_TIME_DELAY_CANCEL'
  | 'SIGN_META_REQUEST_AND_APPROVE'
  | 'SIGN_META_APPROVE'
  | 'SIGN_META_CANCEL'
  | 'EXECUTE_META_REQUEST_AND_APPROVE'
  | 'EXECUTE_META_APPROVE'
  | 'EXECUTE_META_CANCEL'

type TxStatus = 
  | 'UNDEFINED'
  | 'PENDING'
  | 'COMPLETED'
  | 'CANCELLED'
```

## 🔧 **Transaction Options**

```typescript
interface TransactionOptions {
  from?: Address
  value?: bigint
  gas?: bigint
  gasPrice?: bigint
  maxFeePerGas?: bigint
  maxPriorityFeePerGas?: bigint
  nonce?: number
}
```

## 📊 **Error Types**

```typescript
class BloxchainError extends Error {
  code: string
  details?: any
}

class ContractError extends BloxchainError {
  contractAddress: Address
  method: string
}

class ValidationError extends BloxchainError {
  field: string
  value: any
}

class ComplianceError extends BloxchainError {
  violation: ComplianceViolation
}
```

## 🎯 **Usage Examples**

### **Basic Contract Interaction**

```typescript
import { SecureOwnable } from '@bloxchain/sdk'
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http()
})

const secureOwnable = new SecureOwnable(
  client,
  undefined,
  '0x...',
  mainnet
)

// Read operations
const owner = await secureOwnable.owner()
const timeLock = await secureOwnable.getTimeLockPeriodSec()

console.log('Owner:', owner)
console.log('Time lock period:', timeLock)
```

***

**Need more details?** Check out the specific guides:

* [SecureOwnable Guide](/protocol/secure-ownable.md)
* [RuntimeRBAC Guide](/protocol/runtime-rbac.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bloxchain.app/protocol/api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.