@axkledger/axk-xrpl-core

v1.1.0

Published

2 months ago

Foundation layer for AXK Network on XRP Ledger

0High
0Medium
0Low

axknetwork

signordev

xrpl blockchain did afrikabal axk

AXK XRPL Core

Package: @axkledger/axk-xrpl-core | Version: 1.1.0

Foundation Layer for AXK Network on Xahau

TypeScript SDK for interacting with the Xahau blockchain and AXK on-chain hooks. Translates TypeScript objects into 80-byte binary memos that the C hooks understand, manages XRPL wallets, handles DIDs, and routes all transactions to the single hooks account.

What it does

NestJS Service (Ledger, Omni, DAO, etc.)
    |
    |  hookClient.submitCheckpoint({ checkpoint_id, merkle_root, ... })
    |
    v
axk-xrpl-core
    |  1. Validates data (format, ranges, prefixes)
    |  2. Packs into 80-byte binary (the exact layout the C hook expects)
    |  3. Wraps in XRPL Payment with binary MemoData
    |  4. Signs, submits to Xahau, waits for confirmation
    |  5. Parses hook execution result from metadata
    |
    v
Xahau Network --> Hook executes --> State stored on-chain

Architecture

9 Hooks, 3 Wallets, 1 Account

All 9 hooks are deployed to a single Xahau account with namespace separation. Three segregated wallets submit transactions based on purpose:

| Wallet | Used by | Hooks it talks to | |--------|---------|-------------------| | anchoring | axk-ledger | checkpoint-anchor, proof-verifier | | settlement | axk-omni | escrow-manager, payment-splitter, settlement-validator, token-economics, vesting-manager, bridge-vault | | governance | axk-dao | governance-voter |

Hooks & Validators

| Hook | Validator | Binary Prefix | Purpose | |------|-----------|---------------|---------| | checkpoint-anchor | CheckpointValidator | ckpt | Merkle root anchoring | | proof-verifier | ProofValidator | ckpt | On-chain proof verification | | escrow-manager | EscrowValidator | escr | Time-locked escrows | | governance-voter | GovernanceValidator | prop | Proposal voting | | settlement-validator | SettlementValidator | setl | Multi-sig settlements | | payment-splitter | PaymentSplitterValidator | splt | Payment distribution | | token-economics | TokenEconomicsValidator | axk | Burn tiers & network fees | | vesting-manager | VestingManagerValidator | vest | Token vesting grants/claims | | bridge-vault | BridgeVaultValidator | brdg | Cross-chain lock/release |

Every validator produces an 80-byte binary that maps 1:1 to the C hook's memo layout.

Project Structure

axk-xrpl-core/
├── src/
│   ├── index.ts                # Main exports
│   ├── xrpl-client.ts          # XRPL connection wrapper
│   ├── wallet-manager.ts       # Wallet generation & storage
│   ├── did-manager.ts          # W3C DID system
│   ├── memo-formatter.ts       # Structured JSON memos
│   ├── hook-client.ts          # Hook submission (binary packing)
│   ├── hook-config.ts          # Hook account & namespace config
│   ├── network-config.ts       # XAHAU_ENV-aware config resolver
│   ├── types/index.ts          # TypeScript definitions
│   └── validators/
│       ├── base-validator.ts           # Shared validation & binary utils
│       ├── checkpoint-validator.ts     # checkpoint-anchor
│       ├── proof-validator.ts          # proof-verifier
│       ├── escrow-validator.ts         # escrow-manager
│       ├── governance-validator.ts     # governance-voter
│       ├── settlement-validator.ts     # settlement-validator
│       ├── payment-splitter-validator.ts # payment-splitter
│       ├── token-economics-validator.ts # token-economics
│       ├── vesting-manager-validator.ts # vesting-manager
│       └── bridge-vault-validator.ts   # bridge-vault
├── config/
│   ├── wallets.json            # Wallet storage (gitignored)
│   └── memo-schemas.json       # Memo format definitions (7 layers)
├── scripts/                    # CLI tools (wallets, DIDs, payments, hooks)
├── tests/                      # Jest test suites (133 tests)
└── .env                        # Environment config

Installation

As npm dependency

pnpm add @axkledger/axk-xrpl-core

For development

git clone https://github.com/AXK-Infra/axk-xrpl-core.git
cd axk-xrpl-core
pnpm install
cp .env.example .env
pnpm build

Environment Configuration

The SDK uses XAHAU_ENV to switch between testnet and mainnet. One variable controls all network settings:

# .env
XAHAU_ENV=testnet              # or "mainnet"

# Testnet settings
TESTNET_WSS=wss://xahau-test.net
TESTNET_EXPLORER_URL=https://xahau-testnet.xrplwin.com
TESTNET_HOOKS_ACCOUNT=rNtzESnjfvEpYtNg3R48C7K5pm2TXwhB2T

# Mainnet settings (fill when ready)
MAINNET_WSS=wss://xahau.network
MAINNET_EXPLORER_URL=https://xahau.xrplwin.com
MAINNET_HOOKS_ACCOUNT=

The resolveNetworkConfig() function picks the right prefixed values based on XAHAU_ENV:

import { resolveNetworkConfig, explorerTxUrl } from '@axkledger/axk-xrpl-core';

const config = resolveNetworkConfig();
// config.wss         -> "wss://xahau-test.net"
// config.hooksAccount -> "rNtzESnjfvEpYtNg3R48C7K5pm2TXwhB2T"
// config.explorerUrl  -> "https://xahau-testnet.xrplwin.com"
// config.networkId    -> 21338

const url = explorerTxUrl("ABC123...");
// "https://xahau-testnet.xrplwin.com/tx/ABC123..."

Mainnet migration = set XAHAU_ENV=mainnet and fill MAINNET_HOOKS_ACCOUNT.

Usage

HookClient (primary interface)

import { createHookClient, ProofType } from '@axkledger/axk-xrpl-core';
import { Wallet } from '@transia/xrpl';

const hookClient = createHookClient();
const wallet = Wallet.fromSeed(process.env.ANCHORING_WALLET_SEED);

// Submit checkpoint (Merkle root anchoring)
const result = await hookClient.submitCheckpoint({
  wallet,
  checkpoint_id: 'ckpt_block_1703123456',
  merkle_root: 'abc123def456...',   // 64 hex chars
  block_height: 195000,
});

// Submit proof (on-chain verification)
await hookClient.submitProof({
  wallet,
  checkpoint_id: 'ckpt_block_1703123456',
  claim_hash: 'def789...',          // SHA-256 of the event
  proof_type: ProofType.MERKLE,
});

// Create escrow
await hookClient.createEscrow({
  wallet,
  escrow_id: 'escr_trade_001',
  amount: '1000000',
  recipient: 'rDestination...',
  expiry: Math.floor(Date.now() / 1000) + 86400,
});

// Cast governance vote
await hookClient.castVote({
  wallet,
  proposal_id: 'prop_upgrade_001',
  vote: VoteChoice.YES,
  weight: 100,
});

// Token burn event
await hookClient.submitTokenBurn({
  wallet,
  event_id: 'axk_verify_001',
  burn_tier: BurnTier.STANDARD,      // 5% burn
  action_code: (1 << 8) | 0x01,
  amount: 1000000n,
  account: 'rAccount...',
});

// Vesting grant
await hookClient.submitVesting({
  wallet,
  data: {
    vest_id: 'vest_team_001',
    operation: VestingOperation.CREATE,
    schedule: VestingSchedule.TEAM,
    total_amount: 750000000n,
    cliff_end: 1000n,
    vest_end: 5000n,
    beneficiary: 'rBeneficiary...',
  },
});

// Bridge lock
await hookClient.submitBridgeVault({
  wallet,
  data: {
    lock_id: 'brdg_lock_001',
    operation: BridgeOperation.LOCK,
    target_chain: TargetChain.ETHEREUM,
    amount: 5000000n,
    target_address: Buffer.alloc(20, 0xab),
    approval_bitmap: 0,
    nonce: 1n,
  },
});

Validators (standalone)

Each validator can be used independently for validation and binary packing:

import { CheckpointValidator, TokenEconomicsValidator, BurnTier } from '@axkledger/axk-xrpl-core';

// Validate before submission
CheckpointValidator.validate({
  checkpoint_id: 'ckpt_test',
  merkle_root: 'abc123...',
  block_height: 100,
});

// Pack to 80-byte binary hex
const binaryHex = CheckpointValidator.pack(data); // 160 hex chars

// Unpack hook state
const state = CheckpointValidator.unpack(stateHex);

// Compute burn/fee amounts
const { burn, fee } = TokenEconomicsValidator.computeBurnAndFee(10000n, BurnTier.STANDARD);
// burn = 500n (5%), fee = 1000n (10%)

Wallet Management

import { WalletManager } from '@axkledger/axk-xrpl-core';

const wallet = await WalletManager.generateWallet('anchoring');
const loaded = await WalletManager.loadWallet('settlement');
const balance = await WalletManager.getBalance(loaded.address);

DID Operations

import { DIDManager } from '@axkledger/axk-xrpl-core';

const did = DIDManager.createDID('rN7n7otQ...');
// "did:axk:xrpl:rN7n7otQ..."

const doc = await DIDManager.createDIDDocument(walletConfig);
const isValid = DIDManager.validateDIDFormat(did);

CLI Scripts

# Wallets
pnpm wallet:generate --type anchoring
pnpm wallet:fund --type anchoring
pnpm wallet:list

# DIDs
pnpm did:create --type anchoring
pnpm did:resolve --did did:axk:xrpl:rN7n7otQ...
pnpm did:validate --did did:axk:xrpl:rN7n7otQ...

# Payments
pnpm payment:send --from anchoring --to rDest... --amount 1 --layer ledger --operation checkpoint

# Hook integration tests
pnpm hook:test:checkpoint
pnpm hook:test:all

Testing

pnpm test              # Run all 133 tests
pnpm test:watch        # Watch mode
pnpm test:coverage     # Coverage report

Test suites cover all 9 validators (validate, pack, unpack, reject invalid data, binary format consistency), plus wallet manager, DID manager, memo formatter, and XRPL client.

Exports

// Core modules
export { XRPLClient } from './xrpl-client';
export { WalletManager } from './wallet-manager';
export { MemoFormatter } from './memo-formatter';
export { DIDManager } from './did-manager';
export { HookConfig } from './hook-config';
export { HookClient, createHookClient } from './hook-client';

// Network config
export { resolveNetworkConfig, explorerAccountUrl, explorerTxUrl } from './network-config';

// All 9 validators + enums + types
export {
  CheckpointValidator, ProofValidator, ProofType,
  EscrowValidator, EscrowStatus,
  GovernanceValidator, VoteChoice,
  SettlementValidator,
  PaymentSplitterValidator,
  TokenEconomicsValidator, BurnTier,
  VestingManagerValidator, VestingOperation, VestingSchedule, VestingStatus,
  BridgeVaultValidator, BridgeOperation, TargetChain, BridgeStatus,
} from './validators';

// TypeScript types
export type {
  WalletConfig, WalletType, XRPLClientConfig,
  DIDDocument, MemoData, MemoSchema,
  CheckpointData, ProofData, EscrowData, GovernanceData,
  SettlementData, PaymentSplitterData,
  TokenEconomicsData, VestingData, VestingCreateData, VestingClaimData,
  BridgeVaultData,
} from './types';

Security

config/wallets.json is gitignored — never commit wallet seeds
Use environment variables or a secret manager for production seeds
Set file permissions: chmod 600 config/wallets.json .env
Testnet and mainnet configs are separated — no accidental cross-network usage

License

Proprietary - AFRIKABAL 2025-2026