Bloom Filter for Deposit Addresses

Overview

If you are using a machine with 4GB or less RAM, the Bloom Filter endpoint should not be called until your Veriscope Server has fully synchronized. For more information, please refer to our note on nethermind-sync in our Troubleshooting Guide.

Setting-up the Bloom Filter beforehand could result in your server CPU being maxed-out and your machine getting stuck. If you encounter this issue, delete the Bloom Filter and wait for the server to fully synchronize.

The Veriscope Bloom Filter (based on Redis Bloom) allows VASPs to upload their deposit addresses and limit NEW_ATTESTATION events to attestations on those addresses.

  • Without a Bloom Filter, VASPs receive NEW_ATTESTATION events for all attestations and must ascertain which are "relevant attestations" that may need to be responded to

  • With a Bloom Filter, VASPs receive NEW_ATTESTATION events for attestations on addresses in the filter

For more on the NEW_ATTESTATION event, see our Webhook documentation and examples.

General workflow

  1. Create a Bloom Filter by bulk uploading deposit addresses. In our tests, 100m addresses corresponded to just 20MB of storage space!

  2. (Optional) Rescan historical attestations to identify relevant attestations that may need to be responded to

  3. Append new addresses to the filter as they are created

  4. Receive NEW_ATTESTATION events and decided whether to respond to the Originating VASP

New API Endpoints

Four new API endpoints were introduced to support the Bloom Filter and are summarized in the table below.

Endpoint Purpose

POST /api/v1/server/upload_addresses

To create a new Bloom Filter or append addresses to an existing Filter

DELETE /api/v1/server/upload_addresses

To delete an existing Bloom Filter

GET /api/v1/server/upload_addresses?coin_blockchain&coin_token&coin_address

To check specific addresses in an existing Bloom Filter

POST /api/v1/server/rescan_attestations

To scan historical attestations against addresses in the filter. For every positive match, a NEW_ATTESTATION webhook event will be triggered.

Everything the rescan attestations endpoint is hit, a NEW_ATTESTATION event is generated for all relevant attestations. As such, it is recommended that this is used caution and typically only have a new Bloom Filter has been created.

For more the API endpoints, see our API documentation and examples.

CSV Template

The upload_addresses endpoint takes a comma-separate-file (.csv) as input and must include the following column headers:

  • coin_blockchain

  • coin_token

  • coin_address

Bloom Filter .csv template