Update to RecordProvider Interface (#1074)

* wip: started upgrade to record provider interface and started record scanner implementation of said interface

* moved record provider types to models dir. moved nonces out of record provider method signatures into RecordSearchParams interface. added jsdoc comments to record scanner

* added jsdoc comments to record provider/scanner types

* fixed failing record provider tests

* fixed casing of fields on OwnedRecord and EncryptedRecord types

* corrected fields in RecordsFilter interface

* updated encryptedRecords function to mirror changes made to the endpoint in RSS

* changed program to programs in RecordsFilter

* fixed outdated test case for invalid transaction id API response

* added optional apiKey field to RecordScanner

* changed api key field on RecordScanner to be able to accept either a plain key as a string or an object containing the key and the header name

* removed concrete record scanner impl

* Add missing fields to documentation and objects

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

* corrected boolean type name in ownedFilter.ts

---------

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

Author: alexpitsikoulis

sdk/src/browser.ts

@@ -6,6 +6,7 @@ import { BlockJSON, Header, Metadata } from "./models/blockJSON.js";
 import { ConfirmedTransactionJSON } from "./models/confirmed_transaction.js";
 import { DeploymentJSON, VerifyingKeys } from "./models/deployment/deploymentJSON.js";
 import { DeploymentObject } from "./models/deployment/deploymentObject.js";
+import { EncryptedRecord } from "./models/record-provider/encryptedRecord.js";
 import { ExecutionJSON, FeeExecutionJSON } from "./models/execution/executionJSON.js";
 import { ExecutionObject, FeeExecutionObject } from "./models/execution/executionObject.js";
 import { FinalizeJSON } from "./models/finalizeJSON.js";
@@ -15,6 +16,8 @@ import { InputJSON } from "./models/input/inputJSON.js";
 import { InputObject } from "./models/input/inputObject.js";
 import { OutputJSON } from "./models/output/outputJSON.js";
 import { OutputObject } from "./models/output/outputObject.js";
+import { OwnedFilter } from "./models/record-scanner/ownedFilter.js";
+import { OwnedRecord } from "./models/record-provider/ownedRecord.js";
 import { OwnerJSON } from "./models/owner/ownerJSON.js";
 import { PlaintextArray} from "./models/plaintext/array.js";
 import { PlaintextLiteral} from "./models/plaintext/literal.js";
@@ -23,6 +26,9 @@ import { PlaintextStruct} from "./models/plaintext/struct.js";
 import { ProvingRequestJSON } from "./models/provingRequest.js";
 import { ProvingResponse } from "./models/provingResponse.js";
 import { RatificationJSON } from "./models/ratification.js";
+import { RecordsFilter } from "./models/record-scanner/recordsFilter.js";
+import { RecordsResponseFilter } from "./models/record-scanner/recordsResponseFilter.js";
+import { RecordSearchParams } from "./models/record-provider/recordSearchParams.js";
 import { SolutionsJSON, SolutionJSON, PartialSolutionJSON } from "./models/solution.js";
 import { TransactionJSON } from "./models/transaction/transactionJSON.js";
 import { TransactionObject } from "./models/transaction/transactionObject.js";
@@ -45,7 +51,6 @@ import {
     BlockHeightSearch,
     NetworkRecordProvider,
     RecordProvider,
-    RecordSearchParams,
 } from "./record-provider.js";
 
 // @TODO: This function is no longer needed, remove it.
@@ -136,6 +141,7 @@ export {
     ConfirmedTransactionJSON,
     DeploymentJSON,
     DeploymentObject,
+    EncryptedRecord,
     ExecutionJSON,
     ExecutionObject,
     FeeExecutionJSON,
@@ -156,6 +162,8 @@ export {
     OfflineSearchParams,
     OutputJSON,
     OutputObject,
+    OwnedFilter,
+    OwnedRecord,
     OwnerJSON,
     PartialSolutionJSON,
     PlaintextArray,
@@ -166,6 +174,8 @@ export {
     ProvingRequestJSON,
     ProvingResponse,
     RatificationJSON,
+    RecordsFilter,
+    RecordsResponseFilter,
     RecordProvider,
     RecordSearchParams,
     SolutionJSON,

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

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ * 
+ * @property {string} commitment - The commitment of the record.
+ * @property {string | undefined} checksum - The checksum of the record.
+ * @property {number | undefined} block_height - The block height of the record.
+ * @property {number | undefined} block_timestamp - The block timestamp of the record.
+ * @property {string | undefined} program_name - The name of the program that produced the record.
+ * @property {string | undefined} function_name - The name of the function that produced the record.
+ * @property {number | undefined} output_index - The output index of the record.
+ * @property {string | undefined} owner - The owner of the record.
+ * @property {string | undefined} record_ciphertext - The ciphertext of the record.
+ * @property {string | undefined} record_name - The name of the record.
+ * @property {string | undefined} record_nonce - The nonce of the record.
+ * @property {string | undefined} sender_ciphertext - The ciphertext of the sender.
+ * @property {string | undefined} transaction_id - The ID of the transaction that produced the record.
+ * @property {string | undefined} transition_id - The ID of the transition that produced the record.
+ * @property {number | undefined} transaction_index - The index of the transaction that produced the record.
+ * @property {number | undefined} transition_index - The index of the transition that produced the record.
+ * 
+ * @example
+ * const encryptedRecord: EncryptedRecord = {
+ *     commitment: "1754131901135854615627743152473414463769543922079966020586765988138574911385field",
+ *     checksum: "731623304764338277682996290553427512270277231686866672455141481050283829616field",
+ *     block_height: 123456,
+ *     block_timestamp: 1725845998,
+ *     program_name: "credits.aleo",
+ *     function_name: "transfer_private",
+ *     output_index: 0,
+ *     owner: "ciphertext1qgqdetlfzk98jkm4e7sgqml66e3x2gpg5d6udkpw0g67z0tplkpmzrm6q5dyfd7xhgmhedvptxzwfhrtxaqn7n0hs0esge3lwg9s2zukqgzxd0cr",
+ *     record_ciphertext: "record1qyqsqt43u9kp97svljyyup3v4jmppd0vgght9edvvmtxx6mxycsej8cwqsrxzmt0w4h8ggcqqgqspf8zqut2ycnap7f0uzz5ktu0cxscca96urtkg2aweuzn70787dsrpp6x76m9de0kjezrqqpqyqp3mn3xeh53lukvcy406amjf5g0ksl3saauzjk0j4ljtjqq6kqlqhdz05sw92zye96qym7kp83ra0eesgtwhaw37c85r499456se8ts28m90p6x2unwv9k97ct4w35x7unf0fshg6t0de0hyet3w45hyetyyvqqyqgq4t2wr9tmcrfha5tfz5j585ptvvslqe0f6sf29vytshhdh7ym05rpqct4w35x7unf0fjkghm4de6xjmprqqpqzqru6p7fef29vuz6smyqwcn3z7jhxtdgjdw5xv23ppxhpgnvu72fp8hz6fjt6gsdn8yxhzq7gpsah0rscwqrzxwl5e8aemkj5gt09y7q5506yrf",
+ *     record_name: "credits",
+ *     record_nonce: "3077450429259593211617823051143573281856129402760267155982965992208217472983group",
+ *     sender_ciphertext: "1754131901135854615627743152473414463769543922079966020586765988138574911385field",
+ *     transaction_id: "at1f8ueqxu3x49sckpc6jlg676tmxumddzer3fwe2l0dxwj4dqxygyqua4u2q",
+ *     transition_id: "au17mm5v7sfwus6y40xsyc99d5rtsr4vsajdec6twdjzv0m458q85zspqdnka",
+ *     transaction_index: 0,
+ *     transition_index: 0,
+ * }
+ */
+export type EncryptedRecord = {
+    commitment: string;
+    checksum?: string;
+    block_height?: number;
+    block_timestamp?: number;
+    program_name?: string;
+    function_name?: string;
+    output_index?: number;
+    owner?: string;
+    record_ciphertext?: string;
+    record_name?: string;
+    record_nonce?: string;
+    sender_ciphertext?: string;
+    transaction_id?: string;
+    transition_id?: string;
+    transaction_index?: number;
+    transition_index?: number;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ *
+ * @property {number | undefined} block_height - Block height where the record was created.
+ * @property {number | undefined} block_timestamp - The timestamp of the block that the record was created in.
+ * @property {string | undefined} commitment - Commitment of the record.
+ * @property {string | undefined} function_name - Name of the function that created the record.
+ * @property {number | undefined} output_index - Index of the output in the function call that created the record.
+ * @property {string | undefined} owner - Address of the record owner.
+ * @property {string | undefined} program_name - Name of the program that created the record.
+ * @property {string | undefined} record_ciphertext - Encrypted ciphertext of the record.
+ * @property {string | undefined} record_name - Name of the record.
+ * @property {string | undefined} sender - Address of the sender.
+ * @property {boolean | undefined} spent - Whether the record has been spent.
+ * @property {string | undefined} tag - Tag associated with the record.
+ * @property {string | undefined} transaction_id - ID of the transaction that created the record.
+ * @property {string | undefined} transition_id - ID of the transition that created the record.
+ * @property {string | undefined} transaction_index - Index of the transaction in the block.
+ * @property {string | undefined} transition_index - Index of the transition in the transaction.
+ *
+ * @example
+ * const ownedRecord: OwnedRecord = {
+ *     block_height: 123456,
+ *     block_timestamp: 1725845998,
+ *     commitment: "1754131901135854615627743152473414463769543922079966020586765988138574911385field",
+ *     function_name: "transfer_public_to_private",
+ *     output_index: 0,
+ *     owner: "ciphertext1qgqdetlfzk98jkm4e7sgqml66e3x2gpg5d6udkpw0g67z0tplkpmzrm6q5dyfd7xhgmhedvptxzwfhrtxaqn7n0hs0esge3lwg9s2zukqgzxd0cr",
+ *     program_name: "credits.aleo",
+ *     record_ciphertext: "record1qyqsqt43u9kp97svljyyup3v4jmppd0vgght9edvvmtxx6mxycsej8cwqsrxzmt0w4h8ggcqqgqspf8zqut2ycnap7f0uzz5ktu0cxscca96urtkg2aweuzn70787dsrpp6x76m9de0kjezrqqpqyqp3mn3xeh53lukvcy406amjf5g0ksl3saauzjk0j4ljtjqq6kqlqhdz05sw92zye96qym7kp83ra0eesgtwhaw37c85r499456se8ts28m90p6x2unwv9k97ct4w35x7unf0fshg6t0de0hyet3w45hyetyyvqqyqgq4t2wr9tmcrfha5tfz5j585ptvvslqe0f6sf29vytshhdh7ym05rpqct4w35x7unf0fjkghm4de6xjmprqqpqzqru6p7fef29vuz6smyqwcn3z7jhxtdgjdw5xv23ppxhpgnvu72fp8hz6fjt6gsdn8yxhzq7gpsah0rscwqrzxwl5e8aemkj5gt09y7q5506yrf",
+ *     record_plaintext: "{ owner: aleo1j7qxyunfldj2lp8hsvy7mw5k8zaqgjfyr72x2gh3x4ewgae8v5gscf5jh3.private, microcredits: 1500000000000000u64.private, _nonce: 3077450429259593211617823051143573281856129402760267155982965992208217472983group.public , _version: 1u8 }",
+ *     record_name: "credits",
+ *     spent: true,
+ *     sender: "aleo1sf5kk4f8mcmgjasw9fannmm0h8z2nwqxu5e200cjneu28jxvtvpqulfxsa",
+ *     tag: "6511661650536816422260305447175136877451468301541296257226129781611237851030field",
+ *     transaction_id: "at1f8ueqxu3x49sckpc6jlg676tmxumddzer3fwe2l0dxwj4dqxygyqua4u2q",
+ *     transition_id: "au17mm5v7sfwus6y40xsyc99d5rtsr4vsajdec6twdjzv0m458q85zspqdnka",
+ *     transaction_index: 0,
+ *     transition_index: 0,
+ * }
+ */
+export type OwnedRecord = {
+    block_height?: number;
+    block_timestamp?: number;
+    commitment?: string;
+    function_name?: string;
+    output_index?: number;
+    owner?: string;
+    program_name?: string;
+    record_ciphertext?: string;
+    record_plaintext?: string;
+    record_name?: string;
+    sender?: string;
+    spent?: boolean;
+    tag?: string;
+    transaction_id?: string;
+    transition_id?: string;
+    transaction_index?: number;
+    transition_index?: number;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Interface for record search parameters. This allows for arbitrary search parameters to be passed to record provider
+ * implementations.
+ * 
+ * @example
+ * const recordSearchParams: RecordSearchParams = {
+ *     // Declared fields
+ *     unspent: true,
+ *     nonces: ["3077450429259593211617823051143573281856129402760267155982965992208217472983group"],
+ *     // Arbitrary fields
+ *     startHeight: 123456,
+ *     programName: "credits.aleo"
+ * }
+ */
+export interface RecordSearchParams {
+    unspent?: boolean;
+    nonces?: string[];
+    [key: string]: any; // This allows for arbitrary keys with any type values
+}

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

@@ -0,0 +1,25 @@
+import { RecordSearchParams } from "../record-provider/recordSearchParams";
+import { RecordsFilter } from "./recordsFilter";
+import { OwnedRecordsResponseFilter } from "./ownedRecordsResponseFilter";
+
+/**
+ * OwnedFilter is an extension of RecordSearchParams that represents a filter for scanning owned records.
+ * 
+ * @example
+ * const ownedFilter: OwnedFilter = {
+ *     unspent: true,
+ *     nonces: ["3077450429259593211617823051143573281856129402760267155982965992208217472983group"],
+ *     decrypt: true,
+ *     filter: {
+ *         program: "credits.aleo",
+ *         record: "credits",
+ *     },
+ * }
+ */ 
+export interface OwnedFilter extends RecordSearchParams {
+    decrypt?: boolean;
+    filter?: RecordsFilter;
+    responseFilter?: OwnedRecordsResponseFilter;
+    unspent?: boolean;
+    uuid?: string;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * OwnedRecordsResponseFilter is a type that represents a filter for the response from a record provider.
+ * A `true` value for a field in the filter will include that field in the response.
+ * 
+ * @example
+ * const ownedRecordsResponseFilter: OwnedRecordsResponseFilter = {
+ *     commitment: true,
+ *     owner: true,
+ *     tag: true,
+ *     sender: true,
+ *     spent: true,
+ *     record_ciphertext: true,
+ *     block_height: true,
+ *     block_timestamp: true,
+ *     output_index: true,
+ *     record_name: true,
+ *     function_name: true,
+ *     program_name: true,
+ *     transition_id: true,
+ *     transaction_id: true,
+ *     transaction_index: true,
+ *     transition_index: true,
+ * }
+ */
+export interface OwnedRecordsResponseFilter {
+    commitment?: boolean;
+    owner?: boolean;
+    tag?: boolean;
+    sender?: boolean;
+    spent?: boolean;
+    record_ciphertext?: boolean;
+    block_height?: boolean;
+    block_timestamp?: boolean;
+    output_index?: boolean;
+    record_name?: boolean;
+    function_name?: boolean;
+    program_name?: boolean;
+    transition_id?: boolean;
+    transaction_id?: boolean;
+    transaction_index?: boolean;
+    transition_index?: boolean;
+}

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

@@ -0,0 +1,36 @@
+import { RecordSearchParams } from "../record-provider/recordSearchParams";
+import { RecordsResponseFilter } from "./recordsResponseFilter";
+
+/**
+ * RecordsFilter is an extension of RecordSearchParams that represents a filter for scanning encrypted or owned records.
+ * 
+ * @example
+ * const recordsFilter: RecordsFilter = {
+ *     start: 0,
+ *     end: 100,
+ *     programs: ["credits.aleo"],
+ *     records: ["credits"],
+ *     functions: ["transfer_public_to_private"],
+ *     response: {
+ *         program: true,
+ *         record: true,
+ *         function: true,
+ *         transition: true,
+ *         block_height: true,
+ *         transaction_id: true,
+ *     }
+ *     results_per_page: 100,
+ *     page: 0,
+ * }
+ */
+export interface RecordsFilter extends RecordSearchParams {
+    commitments?: string[];
+    response?: RecordsResponseFilter;
+    start?: number;
+    end?: number;
+    programs?: string[];
+    records?: string[];
+    functions?: string[];
+    results_per_page?: number;
+    page?: number;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * RecordsResponseFilter is a type that represents a filter for the response from a record provider.
+ * A `true` value for a field in the filter will include that field in the response.
+ * 
+ * @example
+ * const recordsResponseFilter: RecordsResponseFilter = {
+ *     block_height: true,
+ *     checksum: true,
+ *     commitment: true,
+ *     record_ciphertext: true,
+ *     function_name: true,
+ *     nonce: true,
+ *     output_index: true,
+ *     owner: true,
+ *     program_name: true,
+ *     record_name: true,
+ *     transaction_id: true,
+ *     transition_id: true,
+ *     transaction_index: true,
+ *     transition_index: true,
+ * }
+ */
+export type RecordsResponseFilter = {
+    blockHeight?: boolean;
+    checksum?: boolean;
+    commitment?: boolean;
+    record_ciphertext?: boolean;
+    function_name?: boolean;
+    nonce?: boolean;
+    output_index?: boolean;
+    owner?: boolean;
+    program_name?: boolean;
+    record_name?: boolean;
+    transaction_id?: boolean;
+    transition_id?: boolean;
+    transaction_index?: boolean;
+    transition_index?: boolean;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * RegistrationRequest is a type that represents a request to register an account's view key with a record scanning service.
+ * 
+ * @example
+ * const registrationRequest: RegistrationRequest = {
+ *     view_key: "AViewKey1ccEt8A2Ryva5rxnKcAbn7wgTaTsb79tzkKHFpeKsm9NX",
+ *     start: 123456,
+ * }
+ */
+export type RegistrationRequest = {
+    view_key: string;
+    start: number;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * RegistrationResponse is a type that represents a response from a record scanning service.
+ * 
+ * @example
+ * const registrationResponse: RegistrationResponse = {
+ *     uuid: "5291249998620209321712738612705518874926462927543783711572375085855029172391field",
+ *     job_id: "3019177021147406178755252788128212930359855601860174268911518336835545087409field",
+ *     status: "pending",
+ * }
+ */
+interface RegistrationResponse {
+    uuid: string,
+    job_id?: string,
+    status?: string 
+ }