getting-started.md

Getting Started with Guardian TypeScript SDK

This guide will help you get up and running with the Guardian TypeScript SDK quickly.

📋 Prerequisites

• Node.js 16+
• TypeScript 4.5+
• npm or yarn
• Basic knowledge of Ethereum and smart contracts

🚀 Installation

# Install the SDK
npm install @guardian/sdk

# Or with yarn
yarn add @guardian/sdk

🔧 Basic Setup

1. Import Required Dependencies

import { SecureOwnable, DynamicRBAC } from '@guardian/sdk/typescript'
import { createPublicClient, createWalletClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts'

2. Initialize Clients

// Public client for read operations
const publicClient = createPublicClient({
  chain: mainnet,
  transport: http('https://eth-mainnet.alchemyapi.io/v2/your-api-key')
})

// Wallet client for write operations (optional)
const account = privateKeyToAccount('0x...') // Your private key
const walletClient = createWalletClient({
  account,
  chain: mainnet,
  transport: http('https://eth-mainnet.alchemyapi.io/v2/your-api-key')
})

3. Create Contract Instances

// SecureOwnable contract
const secureOwnable = new SecureOwnable(
  publicClient,
  walletClient, // optional
  '0x...', // contract address
  mainnet
)

// DynamicRBAC contract
const dynamicRBAC = new DynamicRBAC(
  publicClient,
  walletClient, // optional
  '0x...', // contract address
  mainnet
)

📖 Basic Usage Examples

Reading Contract State

// Get contract owner
const owner = await secureOwnable.owner()
console.log('Owner:', owner)

// Get time lock period
const timeLockPeriod = await secureOwnable.getTimeLockPeriodSec()
console.log('Time lock period:', timeLockPeriod)

// Check if role editing is enabled
const roleEditingEnabled = await dynamicRBAC.roleEditingEnabled()
console.log('Role editing enabled:', roleEditingEnabled)

Writing to Contracts

// Request ownership transfer (requires wallet client)
const txHash = await secureOwnable.transferOwnershipRequest(
  '0x...', // new owner address
  { from: account.address }
)

console.log('Transaction hash:', txHash)

// Wait for transaction confirmation
const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash })
console.log('Transaction confirmed:', receipt.status)

Event Monitoring

// Listen for ownership transfer events
const unwatch = publicClient.watchContractEvent({
  address: '0x...', // contract address
  abi: secureOwnable.abi,
  eventName: 'OwnershipTransferRequested',
  onLogs: (logs) => {
    console.log('Ownership transfer requested:', logs)
  }
})

// Stop watching
unwatch()

🔍 Workflow Analysis

Basic Contract Analysis

🛠️ Development Workflow

1. Local Development

# Clone the repository
git clone https://github.com/PracticalParticle/Guardian.git
cd guardian

# Install dependencies
npm install

# Compile contracts
npm run compile:truffle

# Run tests
npm run test:truffle

2. Testing Your Integration

// Test with local network
const localClient = createPublicClient({
  chain: {
    id: 1337,
    name: 'local',
    nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
    rpcUrls: {
      default: { http: ['http://127.0.0.1:8545'] }
    }
  },
  transport: http('http://127.0.0.1:8545')
})

// Deploy and test locally
const localSecureOwnable = new SecureOwnable(
  localClient,
  undefined,
  '0x...', // deployed contract address
  { id: 1337, name: 'local' }
)

🔒 Security Best Practices

1. Private Key Management

// Never hardcode private keys
// Use environment variables
const privateKey = process.env.PRIVATE_KEY
if (!privateKey) {
  throw new Error('PRIVATE_KEY environment variable is required')
}

const account = privateKeyToAccount(privateKey)

2. Input Validation

// Always validate addresses
function isValidAddress(address: string): boolean {
  return /^0x[a-fA-F0-9]{40}$/.test(address)
}

// Validate before making transactions
if (!isValidAddress(newOwner)) {
  throw new Error('Invalid address provided')
}

3. Error Handling

try {
  const txHash = await secureOwnable.transferOwnershipRequest(newOwner)
  console.log('Transaction successful:', txHash)
} catch (error) {
  console.error('Transaction failed:', error.message)
  // Handle specific error types
  if (error.message.includes('insufficient funds')) {
    console.log('Please add more ETH to your account')
  }
}

📚 Next Steps

1. Read the API Reference: API Reference
2. Explore SecureOwnable: SecureOwnable Guide
3. Learn about DynamicRBAC: DynamicRBAC Guide
4. Check Examples: Basic Examples

❓ Common Issues

Issue: "Contract not found"

Solution: Ensure the contract address is correct and the contract is deployed on the network you're using.

Issue: "Insufficient funds"

Solution: Add more ETH to your account or use a testnet with faucet.

Issue: "Transaction reverted"

Solution: Check the contract's requirements (e.g., only owner can call certain functions).

Issue: "Network mismatch"

Solution: Ensure your client is configured for the correct network.

🆘 Getting Help

• Documentation: Check the API Reference
• Examples: See Basic Examples
• Issues: GitHub Issues
• Discord: Join our Discord

---

Ready to dive deeper? Check out the API Reference for detailed documentation of all SDK methods.