{"_id":"@avenbreaks/resonance-sdk","name":"@avenbreaks/resonance-sdk","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.1":{"name":"@avenbreaks/resonance-sdk","version":"0.1.1","description":"Resonance Network SDK for TypeScript/JavaScript - Official SDK for interacting with Resonance FPoS blockchain","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup src/index.ts --format cjs,esm --dts","dev":"tsup src/index.ts --format cjs,esm --dts --watch","lint":"eslint src","type-check":"tsc --noEmit","prepublishOnly":"npm run build && npm run type-check"},"dependencies":{"ethers":"^6.9.0"},"devDependencies":{"@types/node":"^20.10.0","tsup":"^8.0.1","typescript":"^5.3.0"},"keywords":["resonance","blockchain","ethereum","staking","sdk","poa","proof-of-authority","web3","validator","delegator","typescript"],"author":{"name":"avenbreaks"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/avenbreaks/resonance-sdk.git"},"bugs":{"url":"https://github.com/avenbreaks/resonance-sdk/issues"},"homepage":"https://github.com/avenbreaks/resonance-sdk#readme","publishConfig":{"access":"public"},"engines":{"node":">=16.0.0"},"_id":"@avenbreaks/resonance-sdk@0.1.1","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-Wpoto5Hj3qID/1onKdODkDilkpKXWMywAEjqILS8RYCaO9iGSwjyGMlW9mmTbytHlBrHpYm6mRFuteg1qjurZw==","shasum":"5ec48ec73bb041131fc25a15d78e875912e10f0c","tarball":"https://registry.npmjs.org/@avenbreaks/resonance-sdk/-/resonance-sdk-0.1.1.tgz","fileCount":8,"unpackedSize":88954,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCWMD6xPDGWvW6/wP2JExfZ4J2T4M+wLwpeFx5hbxqeOwIhAKsmjAXhuuL8pMWqo8sPCBmoIxCrk9VmOX0UPrRYmJiU"}]},"_npmUser":{"name":"avenbreaks","email":"joywibowo10@gmail.com"},"directories":{},"maintainers":[{"name":"avenbreaks","email":"joywibowo10@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/resonance-sdk_0.1.1_1765072046189_0.8393421264229073"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-07T01:47:26.115Z","0.1.1":"2025-12-07T01:47:26.342Z","modified":"2025-12-07T01:47:26.634Z"},"maintainers":[{"name":"avenbreaks","email":"joywibowo10@gmail.com"}],"description":"Resonance Network SDK for TypeScript/JavaScript - Official SDK for interacting with Resonance FPoS blockchain","homepage":"https://github.com/avenbreaks/resonance-sdk#readme","keywords":["resonance","blockchain","ethereum","staking","sdk","poa","proof-of-authority","web3","validator","delegator","typescript"],"repository":{"type":"git","url":"git+https://github.com/avenbreaks/resonance-sdk.git"},"author":{"name":"avenbreaks"},"bugs":{"url":"https://github.com/avenbreaks/resonance-sdk/issues"},"license":"MIT","readme":"# Resonance Network SDK\n\nOfficial TypeScript/JavaScript SDK for interacting with the Resonance Network API.\n\n## Installation\n\n```bash\nnpm install @avenbreaks/resonance-sdk\n# or\nyarn add @avenbreaks/resonance-sdk\n# or\npnpm add @avenbreaks/resonance-sdk\n```\n\n## Quick Start\n\n```typescript\nimport { ResonanceSDK } from '@avenbreaks/resonance-sdk';\n\n// Initialize the SDK\nconst sdk = new ResonanceSDK({\n apiUrl: 'https://api.resonance.network',\n timeout: 30000, // Optional, default 30s\n});\n\n// Get global network statistics\nconst stats = await sdk.global.getStats();\nconsole.log('Total Network Stake:', stats.total_network_stake);\n\n// Get validator details\nconst validator = await sdk.validators.get('0x1234...');\nconsole.log('Validator Status:', validator.status);\n```\n\n## Authentication\n\nThe SDK supports wallet-based authentication using Web3 providers:\n\n```typescript\nimport { ethers } from 'ethers';\nimport { ResonanceSDK } from '@avenbreaks/resonance-sdk';\n\nconst sdk = new ResonanceSDK({\n apiUrl: 'https://api.resonance.network',\n});\n\n// Connect wallet (browser environment)\nconst provider = new ethers.BrowserProvider(window.ethereum);\nconst authResponse = await sdk.auth.connectWallet(provider, 'delegator');\n\n// Set the JWT token for authenticated requests\nsdk.setAuthToken(authResponse.token);\n\n// Check authentication status\nif (sdk.isAuthenticated()) {\n console.log('User is authenticated');\n}\n\n// Logout\nsdk.logout();\n```\n\n## API Reference\n\n### Global Network Stats\n\n```typescript\n// Get global network statistics\nconst stats = await sdk.global.getStats();\n\n// Get network APR\nconst apr = await sdk.global.getNetworkAPR();\n\n// Get network APR breakdown\nconst breakdown = await sdk.global.getNetworkAPRBreakdown();\n\n// Get delegator leaderboard\nconst delegatorLeaderboard = await sdk.global.getLeaderboardDelegators(10, 0);\n\n// Get validator leaderboard\nconst validatorLeaderboard = await sdk.global.getLeaderboardValidators(10, 0);\n```\n\n### Validators\n\n```typescript\n// Get all validators\nconst allValidators = await sdk.validators.getAll();\n\n// Get specific validator details\nconst validator = await sdk.validators.get('0x1234...');\n\n// Get validator delegators\nconst delegators = await sdk.validators.getDelegators('0x1234...');\n\n// Get validator stake breakdown\nconst stakeBreakdown = await sdk.validators.getStakeBreakdown('0x1234...');\n\n// Get validator epoch details\nconst epochData = await sdk.validators.getEpoch('0x1234...', 100);\n\n// Get validator history\nconst history = await sdk.validators.getHistory('0x1234...', 1, 100);\n\n// Get validator withdrawals\nconst withdrawals = await sdk.validators.getWithdrawals('0x1234...', 50, 0);\n\n// Get validator metrics\nconst metrics = await sdk.validators.getMetrics('0x1234...');\n\n// Get validator slashing events\nconst slashing = await sdk.validators.getSlashing('0x1234...');\n\n// Get validator APR\nconst validatorAPR = await sdk.validators.getAPR('0x1234...');\n```\n\n### Delegators\n\n```typescript\n// Get all delegators\nconst allDelegators = await sdk.delegators.getAll();\n\n// Get specific delegator details\nconst delegator = await sdk.delegators.get('0xabcd...');\n\n// Get delegator stakes breakdown\nconst stakes = await sdk.delegators.getStakes('0xabcd...');\n\n// Get delegator rewards history\nconst rewards = await sdk.delegators.getRewards('0xabcd...', 50, 0);\n\n// Get delegator withdrawals\nconst withdrawals = await sdk.delegators.getWithdrawals('0xabcd...', 50, 0);\n\n// Get delegator unbonding status\nconst unbonding = await sdk.delegators.getUnbonding('0xabcd...');\n\n// Get delegator active validators\nconst validators = await sdk.delegators.getValidators('0xabcd...');\n```\n\n### Referrals\n\n```typescript\n// Validate a referral code\nconst validation = await sdk.referrals.validate('REF123');\n\n// Create a new referral code (requires authentication)\nconst referralCode = await sdk.referrals.create({\n validator_address: '0x1234...',\n max_quota: 100,\n expires_in_days: 30,\n});\n\n// Apply a referral code\nawait sdk.referrals.apply({\n referral_code: 'REF123',\n delegator_address: '0xabcd...',\n});\n\n// Delete a referral code (requires authentication)\nawait sdk.referrals.delete('REF123');\n\n// Unlink a delegator from referral (requires authentication)\nawait sdk.referrals.unlink('0xabcd...');\n\n// Get delegator referral information\nconst delegatorRef = await sdk.referrals.getDelegatorReferral('0xabcd...');\n\n// Get validator referral information\nconst validatorRef = await sdk.referrals.getValidatorReferral('0x1234...');\n```\n\n### Slashing\n\n```typescript\n// Get all slashing events\nconst allEvents = await sdk.slashing.getEvents();\n\n// Get slashing events for a specific validator\nconst validatorEvents = await sdk.slashing.getEvents('0x1234...', 50, 0);\n```\n\n## Advanced Usage\n\n### Custom Headers\n\n```typescript\nconst sdk = new ResonanceSDK({\n apiUrl: 'https://api.resonance.network',\n headers: {\n 'X-Custom-Header': 'value',\n },\n});\n\n// Or set headers after initialization\nsdk.setHeader('X-API-Key', 'your-api-key');\n```\n\n### Error Handling\n\n```typescript\ntry {\n const validator = await sdk.validators.get('0x1234...');\n} catch (error) {\n if (error instanceof Error) {\n console.error('API Error:', error.message);\n }\n}\n```\n\n### Timeout Configuration\n\n```typescript\nconst sdk = new ResonanceSDK({\n apiUrl: 'https://api.resonance.network',\n timeout: 60000, // 60 seconds\n});\n```\n\n## TypeScript Support\n\nThe SDK is written in TypeScript and provides full type definitions:\n\n```typescript\nimport type {\n ValidatorDetailResponse,\n DelegatorDetailResponse,\n GlobalNetworkResponse,\n} from '@avenbreaks/resonance-sdk';\n\nconst processValidator = (validator: ValidatorDetailResponse) => {\n console.log(validator.validator_address);\n console.log(validator.total_stake);\n};\n```\n\n## React Example\n\n```typescript\nimport { useEffect, useState } from 'react';\nimport { ResonanceSDK } from '@avenbreaks/resonance-sdk';\n\nconst sdk = new ResonanceSDK({\n apiUrl: 'https://api.resonance.network',\n});\n\nfunction ValidatorList() {\n const [validators, setValidators] = useState([]);\n const [loading, setLoading] = useState(true);\n\n useEffect(() => {\n const fetchValidators = async () => {\n try {\n const data = await sdk.validators.getAll();\n setValidators(data);\n } catch (error) {\n console.error('Failed to fetch validators:', error);\n } finally {\n setLoading(false);\n }\n };\n\n fetchValidators();\n }, []);\n\n if (loading) return
Loading...
;\n\n return (\n
\n {validators.map((validator) => (\n
{validator.address}
\n ))}\n
\n );\n}\n```\n\n## Next.js Example\n\n```typescript\n// app/page.tsx\nimport { ResonanceSDK } from '@avenbreaks/resonance-sdk';\n\nconst sdk = new ResonanceSDK({\n apiUrl: process.env.NEXT_PUBLIC_API_URL || 'https://api.resonance.network',\n});\n\nexport default async function HomePage() {\n const stats = await sdk.global.getStats();\n\n return (\n
\n

Network Stats

\n

Total Validators: {stats.total_validators}

\n

Total Delegators: {stats.total_delegators}

\n

Total Stake: {stats.total_network_stake}

\n
\n );\n}\n```\n\n## Node.js Example\n\n```typescript\nimport { ResonanceSDK } from '@avenbreaks/resonance-sdk';\n\nconst sdk = new ResonanceSDK({\n apiUrl: 'https://api.resonance.network',\n});\n\nasync function main() {\n // Get network statistics\n const stats = await sdk.global.getStats();\n console.log('Network Stats:', stats);\n\n // Get validator leaderboard\n const leaderboard = await sdk.global.getLeaderboardValidators(10);\n console.log('Top 10 Validators:', leaderboard);\n}\n\nmain().catch(console.error);\n```\n\n## API Endpoints\n\nAll API endpoints are available under the `/eth/v1` prefix. The SDK handles this automatically.\n\n| Module | Endpoint Pattern | Description |\n|--------|-----------------|-------------|\n| Global | `/eth/v1/global` | Network statistics and leaderboards |\n| Validators | `/eth/v1/validators/:address` | Validator information and history |\n| Delegators | `/eth/v1/delegators/:address` | Delegator information and history |\n| Referrals | `/eth/v1/referrals` | Referral code management |\n| Slashing | `/eth/v1/slashing/events` | Slashing events |\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build the SDK\npnpm build\n\n# Run type checking\npnpm type-check\n\n# Watch mode (for development)\npnpm dev\n```\n\n## License\n\nMIT\n\n## Support\n\nFor issues and questions, please visit:\n- GitHub Issues: https://github.com/resonance-network/sdk/issues\n- Documentation: https://docs.resonance.network\n","readmeFilename":"README.md","_rev":"1-3567dd104ebf2d4d50f62628f5c18efe"}