navs-aml/README.md

Anti-Money Laundering (AML) services powered by NAVS - Node-Assisted Verification Service

# NAVS AML - Anti-Money Laundering Services

A specialized NAVS package providing Anti-Money Laundering (AML) compliance functions powered by decentralized cryptoeconomic security.

## Overview

This package provides AML compliance functions that are executed by a decentralized network of operators with economic stake backing the results. All functions are decorated with `@navs` annotations and leverage the NAVS (Node-Assisted Verification Service) infrastructure.

## Features

- **Address Sanctions Checking**: Check if Ethereum addresses appear on the OFAC Sanctions List
- **Bulk Processing**: Efficiently process multiple addresses in a single call  
- **Data Freshness**: Get timestamps of the last OFAC list updates
- **Cryptoeconomic Security**: Results backed by operator stakes and slashing penalties
- **Caching**: Intelligent caching of sanctions data to minimize API calls

## Functions

### `isAddressSanctioned(address: string): Promise<boolean>`

Check if an Ethereum address appears on the OFAC Sanctions List.

```typescript
import { AMLServices } from 'navs-aml';

const isSanctioned = await AMLServices.isAddressSanctioned('0x1234567890123456789012345678901234567890');
console.log(`Address is sanctioned: ${isSanctioned}`);
```

### `bulkAddressCheck(addresses: string[]): Promise<{address: string, sanctioned: boolean}[]>`

Efficiently check multiple addresses for sanctions.

```typescript
const addresses = [
  '0x1234567890123456789012345678901234567890',
  '0x0987654321098765432109876543210987654321'
];

const results = await AMLServices.bulkAddressCheck(addresses);
results.forEach(result => {
  console.log(`${result.address}: ${result.sanctioned ? 'SANCTIONED' : 'CLEAR'}`);
});
```

### `getLastUpdateTime(): Promise<string>`

Get the timestamp of the last OFAC list update.

```typescript
const lastUpdate = await AMLServices.getLastUpdateTime();
console.log(`OFAC list last updated: ${lastUpdate}`);
```

## Installation & Setup

1. Install dependencies:
```bash
npm install
```

2. Set up environment variables:
```bash
cp .env.example .env
# Edit .env with your configuration
```

3. Generate Solidity contracts:
```bash
npm run gen
```

4. Build the project:
```bash
npm run build
```

## Using in Smart Contracts

After running `npm run gen`, you can use the generated Solidity contracts:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "./contracts/NavsReceiver.sol";

contract MyContract is NavsReceiver {
    
    function checkAddress(address addr) external returns (bytes32 taskId) {
        bytes memory addressBytes = abi.encodePacked(addr);
        return NavsAml.isAddressSanctioned(addressBytes, 0.1 ether);
    }
    
    function _onIsAddressSanctioned(
        bytes32 taskId,
        bytes memory address_param,
        bool result,
        string memory error
    ) internal virtual override {
        if (bytes(error).length > 0) {
            // Handle error
            return;
        }
        
        // Handle result
        if (result) {
            // Address is sanctioned - take appropriate action
        }
    }
}
```

## Data Source

This package uses the official OFAC (Office of Foreign Assets Control) SDN Enhanced XML file:
- **Source**: U.S. Treasury Department
- **URL**: https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN_ENHANCED.XML
- **Update Frequency**: Regular updates by OFAC

## Security & Compliance

- **Cryptoeconomic Security**: Results are backed by operator stakes
- **Slashing Protection**: Operators are penalized for providing incorrect results
- **Data Integrity**: Multiple operators independently verify results
- **Real-time Data**: Always uses the latest OFAC sanctions list

## License

MIT License - see LICENSE file for details.