Record Scanner

Overview

A record provider implementation that uses a record scanning service to find records for usage in program execution and deployment, wallet functionality, and other use cases. This is an alternative to NetworkRecordProvider for users who prefer to use a dedicated scanning service.

Kind: global class

RecordScanner
- constructor
  - new RecordScanner(options)
- instance
  - .setApiKey(apiKey)
  - .setUuid(uuidOrViewKey)
  - .register(viewKey, startBlock) ⇒ Promise.<RegistrationResponse>
  - .encryptedRecords(recordsFilter) ⇒ Promise.<EncryptedRecord[]>
  - .checkSerialNumbers(serialNumbers) ⇒ Promise.<Record<string, boolean>>
  - .checkTags(tags) ⇒ Promise.<Record<string, boolean>>
  - .checkStatus() ⇒ Promise.<StatusResponse>
  - .findRecord(searchParameters) ⇒ Promise.<OwnedRecord>
  - .findRecords(filter) ⇒ Promise.<OwnedRecord[]>
  - .findCreditsRecord(microcredits, searchParameters) ⇒ Promise.<OwnedRecord>
  - .findCreditsRecords(microcreditAmounts, searchParameters) ⇒ Promise.<OwnedRecord[]>
  - .computeUUID(vk) ⇒ Field

Constructor

RecordScanner

Create a new RecordScanner instance that uses a record scanning service to find records.

new RecordScanner(options)

Param	Type	Description
options	`RecordScannerOptions`	Configuration options for the record scanner

RecordScannerOptions

Property	Type	Description
url	`string`	The URL of the record scanning service
apiKey	`string \| { header: string, value: string }`	Optional API key for authentication

Example

import { RecordScanner, Account } from "@provablehq/sdk/mainnet.js";

// Create a new RecordScanner with a simple API key
const recordScanner = new RecordScanner({ 
    url: "https://record-scanner.aleo.org",
    apiKey: "your-api-key"
});

// Or with a custom header
const recordScannerCustomHeader = new RecordScanner({ 
    url: "https://record-scanner.aleo.org",
    apiKey: { header: "X-Custom-Header", value: "your-api-key" }
});

// Register an account and start scanning
const account = new Account({ privateKey: 'APrivateKey1...' });
const response = await recordScanner.register(account.viewKey(), 0);

// Find records
const filter = {
    uuid: response.uuid,
    filter: {
        program: "credits.aleo",
        records: ["credits"],
    },
    unspent: true,
};
const records = await recordScanner.findRecords(filter);

RecordScanner Methods

setApiKey

Set the API key to use for the record scanner.

setApiKey(apiKey) ⇒ Promise.<void>

Parameters	Type	Description
apiKey	`string \| { header: string, value: string }`	The API key to use for the record scanner
*return*	`Promise.<void>`	Resolves when the API key is set

Example

// Set API key as a string (uses default header X-Provable-API-Key)
await recordScanner.setApiKey("your-api-key");

// Set API key with a custom header
await recordScanner.setApiKey({ header: "X-Custom-Header", value: "your-api-key" });

setUuid

Set the UUID to use for the record scanner. The UUID identifies the registered account with the scanning service.

setUuid(uuidOrViewKey) ⇒ Promise.<void>

Parameters	Type	Description
uuidOrViewKey	`Field \| ViewKey`	The UUID or ViewKey to use for the record scanner
*return*	`Promise.<void>`	Resolves when the UUID is set

Example

// Set UUID directly
await recordScanner.setUuid(uuidField);

// Or compute UUID from ViewKey
await recordScanner.setUuid(account.viewKey());

register

register(viewKey, startBlock) ⇒ Promise.<RegistrationResponse>

Parameters	Type	Description
viewKey	`ViewKey`	The view key of the account to register
startBlock	`number`	The block height to start scanning from
*return*	`Promise.<RegistrationResponse>`	The response from the record scanner service containing the UUID

Example

import { RecordScanner, Account } from "@provablehq/sdk/mainnet.js";

const account = new Account({ privateKey: 'APrivateKey1...' });
const recordScanner = new RecordScanner({ url: "https://record-scanner.aleo.org" });

// Register the account starting from block 0
const response = await recordScanner.register(account.viewKey(), 0);
console.log("Registration UUID:", response.uuid);

encryptedRecords

Get encrypted records from the record scanner service.

encryptedRecords(recordsFilter) ⇒ Promise.<EncryptedRecord[]>

Parameters	Type	Description
recordsFilter	`RecordsFilter`	The filter to use to find the records and filter the response
*return*	`Promise.<EncryptedRecord[]>`	Array of encrypted records matching the filter

Example

const filter = {
    uuid: "your-uuid",
    filter: {
        program: "credits.aleo",
        records: ["credits"],
    },
};
const encryptedRecords = await recordScanner.encryptedRecords(filter);

checkSerialNumbers

Check if a list of serial numbers exist in the record scanner service. This is used to determine if records have been spent.

checkSerialNumbers(serialNumbers) ⇒ Promise.<Record<string, boolean>>

Parameters	Type	Description
serialNumbers	`string[]`	The serial numbers to check
*return*	`Promise.<Record<string, boolean>>`	Map of Aleo Record serial numbers and whether they appeared in any inputs on chain. If boolean corresponding to the Serial Number has a true value, that Record is considered spent by the Aleo Network.

Example

const serialNumbers = ["sn1...", "sn2..."];
const result = await recordScanner.checkSerialNumbers(serialNumbers);
console.log(result); // { "sn1...": true, "sn2...": false }

checkTags

Check if a list of tags exist in the record scanner service. This is used to determine if records have been spent.

checkTags(tags) ⇒ Promise.<Record<string, boolean>>

Parameters	Type	Description
tags	`string[]`	The tags to check
*return*	`Promise.<Record<string, boolean>>`	Map of Aleo Record tags and whether they appeared in any inputs on chain. If boolean corresponding to the tag has a true value, that Record is considered spent by the Aleo Network.

Example

const tags = ["tag1...", "tag2..."];
const result = await recordScanner.checkTags(tags);
console.log(result); // { "tag1...": false, "tag2...": true }

checkStatus

Check the status of a record scanner indexing job.

checkStatus() ⇒ Promise.<StatusResponse>

Parameters	Type	Description
*return*	`Promise.<StatusResponse>`	The status of the indexing job for the registered account

Example

const status = await recordScanner.checkStatus();
console.log("Current block:", status.current_block);
console.log("Indexed up to:", status.indexed_to);

findRecord

Find a single record in the record scanner service.

findRecord(searchParameters) ⇒ Promise.<OwnedRecord>

Parameters	Type	Description
searchParameters	`OwnedFilter`	The filter to use to find the record
*return*	`Promise.<OwnedRecord>`	The first record matching the filter

Example

const filter = {
    decrypt: true,
    unspent: true,
    filter: {
        program: "credits.aleo",
        record: "credits",
    },
};
const record = await recordScanner.findRecord(filter);

findRecords

Find multiple records in the record scanner service.

findRecords(filter) ⇒ Promise.<OwnedRecord[]>

Parameters	Type	Description
filter	`OwnedFilter`	The filter to use to find the records
*return*	`Promise.<OwnedRecord[]>`	Array of records matching the filter

Example

const filter = {
    decrypt: true,
    unspent: true,
    filter: {
        program: "credits.aleo",
        record: "credits",
    },
    responseFilter: {
        commitment: true,
        owner: true,
        tag: true,
        spent: true,
        record_ciphertext: true,
        block_height: true,
        block_timestamp: true,
    },
};
const records = await recordScanner.findRecords(filter);
console.log(`Found ${records.length} records`);

findCreditsRecord

Find a credits record with at least the specified number of microcredits.

findCreditsRecord(microcredits, searchParameters) ⇒ Promise.<OwnedRecord>

Parameters	Type	Description
microcredits	`number`	The minimum amount of microcredits to find
searchParameters	`OwnedFilter`	The filter to use to find the record
*return*	`Promise.<OwnedRecord>`	A credits record with at least the specified microcredits

Example

// Find a credits record with at least 1,000,000 microcredits (1 credit)
const record = await recordScanner.findCreditsRecord(1000000, {
    unspent: true,
    filter: { start: 0 },
});
console.log("Found record:", record.record_plaintext);

findCreditsRecords

Find credits records matching specific microcredit amounts.

findCreditsRecords(microcreditAmounts, searchParameters) ⇒ Promise.<OwnedRecord[]>

Parameters	Type	Description
microcreditAmounts	`number[]`	The amounts of microcredits to find
searchParameters	`OwnedFilter`	The filter to use to find the records
*return*	`Promise.<OwnedRecord[]>`	Array of credits records matching the specified amounts

Example

// Find credits records with specific amounts
const amounts = [1000000, 5000000, 10000000];
const records = await recordScanner.findCreditsRecords(amounts, {
    unspent: true,
    filter: { start: 0 },
});
console.log(`Found ${records.length} matching records`);

computeUUID

Compute the UUID for a given view key. This is used internally to identify accounts with the scanning service.

computeUUID(vk) ⇒ Field

Parameters	Type	Description
vk	`ViewKey`	The view key to compute the UUID for
*return*	`Field`	The computed UUID as a Field element

Example

const uuid = recordScanner.computeUUID(account.viewKey());
console.log("Computed UUID:", uuid.toString());

OwnedFilter Interface

The OwnedFilter interface defines the search parameters for finding owned records.

Property	Type	Description
uuid	`string`	Optional. The UUID identifying the registered account
decrypt	`boolean`	Optional. Whether to decrypt the records
unspent	`boolean`	Optional. Whether to filter for unspent records only
filter	`object`	Optional. Filter criteria for the records
filter.start	`number`	Optional. Starting block height
filter.program	`string`	Optional. Program ID to filter by
filter.record	`string`	Optional. Record name to filter by
responseFilter	`OwnedRecordsResponseFilter`	Optional. Fields to include in the response

OwnedRecordsResponseFilter Interface

The OwnedRecordsResponseFilter interface defines which fields to include in the record response.

Property	Type	Description
commitment	`boolean`	Include the record commitment
owner	`boolean`	Include the record owner
tag	`boolean`	Include the record tag
sender	`boolean`	Include the sender address
spent	`boolean`	Include spent status
record_ciphertext	`boolean`	Include the encrypted record
block_height	`boolean`	Include the block height
block_timestamp	`boolean`	Include the block timestamp
output_index	`boolean`	Include the output index
record_name	`boolean`	Include the record name
function_name	`boolean`	Include the function name
program_name	`boolean`	Include the program name
transition_id	`boolean`	Include the transition ID
transaction_id	`boolean`	Include the transaction ID
transaction_index	`boolean`	Include the transaction index
transition_index	`boolean`	Include the transition index

Overview​

Constructor​

RecordScanner​

RecordScannerOptions​

RecordScanner Methods​

setApiKey​

setUuid​

register​

encryptedRecords​

checkSerialNumbers​

checkTags​

checkStatus​

findRecord​

findRecords​

findCreditsRecord​

findCreditsRecords​

computeUUID​

OwnedFilter Interface​

OwnedRecordsResponseFilter Interface​

Overview

Constructor

RecordScanner

RecordScannerOptions

RecordScanner Methods

setApiKey

setUuid

register

encryptedRecords

checkSerialNumbers

checkTags

checkStatus

findRecord

findRecords

findCreditsRecord

findCreditsRecords

computeUUID

OwnedFilter Interface

OwnedRecordsResponseFilter Interface