feat: introduce pluggable wallet policy engine (AOP-style)

[nimdeveloper]

Wallet Policies

This PR introduces Wallet Policies, a non-breaking feature that allows registering policy objects to gate mutating wallet, account, and protocol methods. Policies are evaluated before method execution. If a policy fails, a PolicyViolationError is thrown and execution is halted.

This feature is implemented using an Aspect-Oriented Programming (AOP) approach to cleanly separate cross-cutting concerns from wallet business logic.

Motivation and Context

WDK currently lacks a unified mechanism to enforce runtime constraints such as:

• Transaction limits
• Protocol-level restrictions
• Blockchain-specific rules
• Compliance or environment guardrails

These concerns are cross-cutting: they affect many unrelated methods across accounts and protocols. Without AOP, we would either duplicate checks inside every mutating method or make each class aware of external enforcement logic — both reduce maintainability and violate separation of concerns.

This PR introduces a lightweight AOP-style policy engine that allows defining enforcement logic once and declaratively applying it to selected wallet methods.

Aspect-Oriented Programming (AOP) Model

Join Point

A join point is a place where behavior can be intercepted. In WDK, every mutating method call is a join point:

await account.sendTransaction(tx)
await protocol.swap(options)

Pointcut

A pointcut defines which join points to target, expressed declaratively:

{ target: { blockchain: 'ethereum' }, method: 'sendTransaction' }

Pointcuts can scope by blockchain, protocol, method name, or all methods.

Advice

Advice is the code that runs at the join point via evaluate(). Advice is async-safe, enabling real-world enforcement tasks beyond simple in-memory checks — for example:

• Querying an indexer to check cumulative spend over the past 24 hours
• Calling a KYT (Know Your Transaction) service to screen a recipient address

// Simple synchronous check
evaluate({ params }) {
  return params.amount <= 1_000_000n
}

// Async: check rolling spend via indexer
async evaluate({ params, target }) {
  const spent = await indexer.getSpentLast24h(target.address)
  return spent + params.amount <= DAILY_LIMIT
}

// Async: screen address via KYT service
async evaluate({ params }) {
  const result = await kyt.screen(params.to)
  return result.risk !== 'high'
}

Advice runs before the original method. Policies execute sequentially and fail-fast — the first failing policy halts execution.

Aspect

An aspect combines a pointcut with advice. In this implementation, a policy object is an aspect:

const maxAmountPolicy = {
  name: 'max-amount',
  target: { blockchain: 'ethereum' },
  method: 'sendTransaction',
  evaluate({ params }) {
    return params.amount <= 1_000_000n
  }
}

Weaving

Weaving attaches aspects to join points at runtime inside _withPolicyGate():

const originalFn = instance[methodName].bind(instance)
instance[methodName] = async (...args) => {
  await runPolicies(methodPolicyMap.get(methodName), methodName, args[0], target)
  return originalFn(...args)
}

The original method is wrapped once, ensuring no modification to original class implementations and clean separation of concerns.

Design Decisions

Why not use Proxy?

Proxy intercepts all property access, complicates debugging, and makes execution flow less explicit. Instead, explicit method wrapping is used, which targets only specific methods, preserves performance, and keeps weaving controlled and predictable.

Why use Symbol?

Two internal Symbols store policy metadata per instance to prevent property name collisions, keep metadata non-enumerable, avoid polluting the public API, and ensure clean instance-level isolation.

Implementation Summary

• registerPolicies() — validates and registers aspects (policies)
• _runPolicies() — executes advice sequentially (async-safe, fail-fast)
• _withPolicyGate() — performs runtime weaving
• Policies support method, blockchain, and protocol scoping
• Policies are isolated per account/protocol instance
• Each method is wrapped only once

This change is fully backward compatible and introduces no breaking behavior.

Type of Change

• New feature (non-breaking change which adds functionality)