Update to RecordProvider Interface #1074

alexpitsikoulis · 2025-08-15T22:14:13Z

…scanner implementation of said interface

Motivation

(Write your motivation here)

Test Plan

(Write your test plan here)

Related PRs

(Link your related PRs here)

iamalwaysuncomfortable

Good core impl, but several comments on the interface, code organization, and some method naming.

sdk/src/record-provider.ts

iamalwaysuncomfortable

Looking better, the following things should be added

Can we add doc comments to the interface types. People will be confused about this initially and docs will help.
Can you add tests of the default implementation against stubs?
A few more nits?

sdk/src/models/record-scanner/recordsFilter.ts

sdk/src/models/record-provider/encryptedRecord.ts

sdk/src/record-provider.ts

sdk/src/record-scanner.ts

sdk/src/record-provider.ts

sdk/src/models/record-provider/ownedRecord.ts

sdk/src/models/record-scanner/recordsFilter.ts

sdk/src/models/record-scanner/registrationRequest.ts

iamalwaysuncomfortable · 2025-08-19T00:26:08Z

sdk/src/record-scanner.ts

+ * 
+ * const records = await recordScanner.findRecords({ filter, responseFilter });
+ */
+class RecordScanner implements RecordProvider {


Before it's marked ready this should pass tests using stubs for the test data.

iamalwaysuncomfortable

Some (expected) changes to the interface added here.

Secondly, let's please split out the concrete implementation of the RecordScanner from this PR and make it PR into this one. We need to put some pretty significant tests around it to ensure it's production ready. The interface however, matches what we expect.

iamalwaysuncomfortable · 2025-08-20T17:38:33Z

sdk/src/record-scanner.ts

+     * @param {number} startBlock The block height to start scanning from.
+     * @returns {Promise<void>} A promise that resolves when the account is registered.
+     */
+    async register(startBlock: number): Promise<void> {


This should return a RegistrationResponse type

interface RegistrationResponse { uuid: string, job_id?: string, status?: string }

Suggested change

async register(startBlock: number): Promise<void> {

async register(startBlock: number): Promise<void> {

iamalwaysuncomfortable · 2025-08-21T00:06:54Z

sdk/src/models/record-provider/encryptedRecord.ts

@@ -0,0 +1,52 @@
+/**
+ * Encrypted Record found on chain. This type provides the record ciphertext and metadata from the ledger that such as the record's name, the program/function that produced it, etc.


Suggested change

* Encrypted Record found on chain. This type provides the record ciphertext and metadata from the ledger that such as the record's name, the program/function that produced it, etc.

* Encrypted Record found on chain. This type provides the record ciphertext and metadata from the ledger such as the record's name, the program/function that produced it, etc.

iamalwaysuncomfortable · 2025-08-21T00:07:27Z

sdk/src/models/record-provider/ownedRecord.ts

@@ -0,0 +1,54 @@
+/**
+ * Record owned by a registered view key. This type provides the record ciphertext, record plaintext and metadata from the ledger that such as the record's name, the program/function that produced it, etc.


Suggested change

* Record owned by a registered view key. This type provides the record ciphertext, record plaintext and metadata from the ledger that such as the record's name, the program/function that produced it, etc.

* Record owned by a registered view key. This type provides the record ciphertext, record plaintext and metadata from the ledger such as the record's name, the program/function that produced it, etc.

sdk/src/models/record-provider/encryptedRecord.ts

iamalwaysuncomfortable · 2025-09-18T22:02:17Z

sdk/src/models/record-scanner/ownedFilter.ts

@@ -0,0 +1,24 @@
+import { RecordSearchParams } from "../record-provider/recordSearchParams";
+import { RecordsFilter } from "./recordsFilter";
+import { RecordsResponseFilter } from "../record-provider/recordsResponseFilter";


We need another file to handle the OwnedFilter.

iamalwaysuncomfortable · 2025-09-18T22:29:56Z

sdk/src/record-provider.ts

+    encryptedRecords(recordsFilter: RecordSearchParams, responseFilter: RecordsResponseFilter): Promise<EncryptedRecord[]>;
+
+    /**
+     * Check if a list of serial numbers exist in the chosen provider


Suggested change

* Check if a list of serial numbers exist in the chosen provider

* Check if a list of serial numbers exist in the chosen provider.

iamalwaysuncomfortable · 2025-09-18T22:30:06Z

sdk/src/record-provider.ts

+    checkSerialNumbers(serialNumbers: string[]): Promise<Record<string, boolean>>;
+
+    /**
+     * Check if a list of tags exist in the chosen provider


Suggested change

* Check if a list of tags exist in the chosen provider

* Check if a list of tags exist in the chosen provider.

iamalwaysuncomfortable · 2025-09-18T22:30:40Z

sdk/src/record-scanner.ts

+/**
+ * RecordScanner is a RecordProvider implementation that uses the record scanner service to find records.
+ * 
+ * @example
+ * const account = new Account({ privateKey: 'APrivateKey1...' });
+ * 
+ * const recordScanner = new RecordScanner("https://record-scanner.aleo.org");
+ * recordScanner.setAccount(account);
+ * const uuid = await recordScanner.register(0);
+ * 
+ * const filter = {
+ *     uuid,
+ *     filter: {
+ *         program: "credits.aleo",
+ *         records: ["credits"],
+ *     },
+ *     responseFilter: {
+ *         program: true,
+ *         record: true,
+ *         function: true,
+ *         transition: true,
+ *         block_height: true,


Can we split this record provider out into a second PR so we can write proper tests around it?

iamalwaysuncomfortable · 2025-09-18T22:31:44Z

sdk/src/record-scanner.ts

+            return records.filter(record => {
+                const plaintext = RecordPlaintext.fromString(record.record_plaintext ?? '');
+                const amount = plaintext.getMember("microcredits").toString();
+                return microcreditAmounts.includes(parseInt(amount.replace("u64", "")));


This will only match extremely specific micro credits amounts, which will match a very small amount of the time. This should ensure that records are found that are larger than the microcredit amounts in the array.

For instance if you have credits records with amounts:
100,
200,
3000,
4000,
30

And your filter specifies [100, 300, 400]
It should choose amounts above those like [100, 3000, 4000] OR [200, 3000, 4000]

…scanner implementation of said interface

… provider method signatures into RecordSearchParams interface. added jsdoc comments to record scanner

…int in RSS

…plain key as a string or an object containing the key and the header name

Signed-off-by: Mike Turner <[email protected]>

iamalwaysuncomfortable

@alexpitsikoulis this is approved, merge at will.

alexpitsikoulis force-pushed the feat/upgraded-record-provider-interface branch from 564eefa to c927c95 Compare August 15, 2025 22:41

vercel bot deployed to Preview August 15, 2025 22:41 View deployment

iamalwaysuncomfortable requested changes Aug 18, 2025

View reviewed changes

vercel bot deployed to Preview August 18, 2025 22:12 View deployment

iamalwaysuncomfortable reviewed Aug 18, 2025

View reviewed changes

vercel bot deployed to Preview August 18, 2025 23:04 View deployment

alexpitsikoulis force-pushed the feat/upgraded-record-provider-interface branch from e5f7a46 to 6427fa2 Compare August 18, 2025 23:07

vercel bot deployed to Preview August 18, 2025 23:07 View deployment

iamalwaysuncomfortable reviewed Aug 19, 2025

View reviewed changes

vercel bot deployed to Preview August 20, 2025 17:10 View deployment

alexpitsikoulis force-pushed the feat/upgraded-record-provider-interface branch from dba689e to 7f88144 Compare August 20, 2025 17:50

vercel bot deployed to Preview August 20, 2025 17:50 View deployment

alexpitsikoulis force-pushed the feat/upgraded-record-provider-interface branch from 7f88144 to cdd92fa Compare August 20, 2025 18:27

vercel bot deployed to Preview August 20, 2025 18:27 View deployment

vercel bot deployed to Preview August 20, 2025 22:16 View deployment

alexpitsikoulis force-pushed the feat/upgraded-record-provider-interface branch from b78fbbb to 4487169 Compare August 20, 2025 22:32

vercel bot deployed to Preview August 20, 2025 22:32 View deployment

iamalwaysuncomfortable changed the title ~~wip: started upgrade to record provider interface and started record …~~ Update to RecordProvider Interface Aug 25, 2025

iamalwaysuncomfortable added this to the SDK Version 0.10.0 milestone Aug 25, 2025

iamalwaysuncomfortable assigned alexpitsikoulis Aug 25, 2025

alexpitsikoulis force-pushed the feat/upgraded-record-provider-interface branch from 4487169 to de37e1c Compare September 8, 2025 18:07

vercel bot deployed to Preview September 8, 2025 18:08 View deployment

alexpitsikoulis force-pushed the feat/upgraded-record-provider-interface branch from de37e1c to 8afa6ab Compare September 17, 2025 16:20

vercel bot deployed to Preview September 17, 2025 16:20 View deployment

vercel bot deployed to Preview September 17, 2025 17:14 View deployment

vercel bot deployed to Preview September 17, 2025 17:48 View deployment

vercel bot deployed to Preview September 17, 2025 18:19 View deployment

alexpitsikoulis marked this pull request as ready for review September 17, 2025 21:28

vercel bot deployed to Preview September 17, 2025 22:36 View deployment

iamalwaysuncomfortable requested changes Sep 18, 2025

View reviewed changes

vercel bot deployed to Preview September 19, 2025 17:29 View deployment

alexpitsikoulis added 12 commits September 19, 2025 15:37

wip: started upgrade to record provider interface and started record …

4f083e5

…scanner implementation of said interface

moved record provider types to models dir. moved nonces out of record…

83fbe54

… provider method signatures into RecordSearchParams interface. added jsdoc comments to record scanner

added jsdoc comments to record provider/scanner types

9170df5

fixed failing record provider tests

8a4df53

fixed casing of fields on OwnedRecord and EncryptedRecord types

49577dd

corrected fields in RecordsFilter interface

8e14c99

updated encryptedRecords function to mirror changes made to the endpo…

2572192

…int in RSS

changed program to programs in RecordsFilter

691f71b

fixed outdated test case for invalid transaction id API response

f541996

added optional apiKey field to RecordScanner

39675bf

changed api key field on RecordScanner to be able to accept either a …

2549a9d

…plain key as a string or an object containing the key and the header name

removed concrete record scanner impl

3b345ba

alexpitsikoulis force-pushed the feat/upgraded-record-provider-interface branch from d8f3421 to 3b345ba Compare September 19, 2025 22:37

vercel bot deployed to Preview September 19, 2025 22:37 View deployment

Add missing fields to documentation and objects

71654fb

Signed-off-by: Mike Turner <[email protected]>

vercel bot deployed to Preview September 19, 2025 23:22 View deployment

iamalwaysuncomfortable approved these changes Sep 19, 2025

View reviewed changes

corrected boolean type name in ownedFilter.ts

957f8c8

vercel bot deployed to Preview September 19, 2025 23:35 View deployment

alexpitsikoulis merged commit bce4d9f into mainnet Sep 22, 2025
13 checks passed

alexpitsikoulis deleted the feat/upgraded-record-provider-interface branch September 22, 2025 15:52

alexpitsikoulis mentioned this pull request Sep 22, 2025

[Feature] RecordScanner client #1100

Open

	async register(startBlock: number): Promise<void> {
	async register(startBlock: number): Promise<void> {

		@@ -0,0 +1,52 @@
		/**
		* Encrypted Record found on chain. This type provides the record ciphertext and metadata from the ledger that such as the record's name, the program/function that produced it, etc.

		@@ -0,0 +1,54 @@
		/**
		* Record owned by a registered view key. This type provides the record ciphertext, record plaintext and metadata from the ledger that such as the record's name, the program/function that produced it, etc.

	* Check if a list of serial numbers exist in the chosen provider
	* Check if a list of serial numbers exist in the chosen provider.

	* Check if a list of tags exist in the chosen provider
	* Check if a list of tags exist in the chosen provider.

Update to RecordProvider Interface #1074

Update to RecordProvider Interface #1074

Uh oh!

Conversation

alexpitsikoulis commented Aug 15, 2025

Motivation

Test Plan

Related PRs

Uh oh!

iamalwaysuncomfortable left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iamalwaysuncomfortable left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iamalwaysuncomfortable left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iamalwaysuncomfortable left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

iamalwaysuncomfortable left a comment •

edited

Loading