@usearete/sdk 0.10.0 → 0.12.0

package/README.md

@@ -348,6 +348,7 @@ Available reads include:
 - `minimumBalanceForRentExemption(space)`
 - `clock()`
 - `account(address)`
+- `accounts(addresses)` - batched `account(address)`, up to 100 per call, results aligned with the input order
 - `mint(address)`
 - `tokenAccount(address)`
 - `balance({ owner, mint, tokenProgram? })`

package/dist/index.cjs

@@ -3123,6 +3123,30 @@ function createTypedViews(stack, storage, subscriptionRegistry) {
     return views;
 }
 
+/**
+ * Non-enumerable brand attached by the operation and read factories so
+ * tooling (e.g. the knowledge-layer extractor's runtime walk) can classify
+ * values by brand instead of duck-typing. Non-enumerable keeps JSON
+ * serialization and object spreads of surrounding containers unchanged.
+ */
+const OPERATION_KIND = '__areteOperationKind';
+function brandOperationKind(value, kind) {
+    Object.defineProperty(value, OPERATION_KIND, {
+        value: kind,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return value;
+}
+function getOperationKind(value) {
+    if (value === null || (typeof value !== 'object' && typeof value !== 'function')) {
+        return undefined;
+    }
+    const kind = value[OPERATION_KIND];
+    return typeof kind === 'string' ? kind : undefined;
+}
+
 class ReadRequestError extends Error {
     constructor(input) {
         super(`Read request to '${input.path}' failed (${input.status}): ${input.body}`);
@@ -3159,26 +3183,26 @@ async function parseReadResponse(response, path) {
     return response.json();
 }
 function programAccountRead(input) {
-    return {
+    return brandOperationKind({
         account: input.account,
         schema: input.schema,
-    };
+    }, 'account-fetch');
 }
 function programQuery(input) {
-    return {
+    return brandOperationKind({
         name: input.name,
         path: input.path,
         method: input.method,
         schema: input.schema,
-    };
+    }, 'query');
 }
 function stackQuery(input) {
-    return {
+    return brandOperationKind({
         name: input.name,
         path: input.path,
         method: input.method,
         schema: input.schema,
-    };
+    }, 'query');
 }
 
 function joinUrl(baseUrl, path) {
@@ -3199,6 +3223,19 @@ function decodeBase64(encoded) {
     }
     throw new Error('No base64 decoder available in this environment');
 }
+const MAX_BATCH_ADDRESSES = 100;
+function toRawAccount(body) {
+    if (!body) {
+        return null;
+    }
+    return {
+        address: body.address,
+        ownerProgram: body.ownerProgram,
+        lamports: decimalU64(body.lamports, 'lamports'),
+        executable: body.executable,
+        data: decodeBase64(body.data),
+    };
+}
 function decimalU64(value, field) {
     if (!/^\d+$/.test(value)) {
         throw new TypeError(`${field} must be a decimal u64 string`);
@@ -3286,17 +3323,33 @@ function createChainClient(httpBaseUrl, fetchImpl) {
         async account(address) {
             const path = `/chain/accounts/${encodeURIComponent(address)}`;
             const response = await fetchImpl(joinUrl(httpBaseUrl, path));
+            return toRawAccount(await parseReadResponse(response, path));
+        },
+        async accounts(addresses) {
+            // Copied before anything else: `readonly string[]` accepts a mutable array, so a caller can
+            // splice it while the request is in flight and the cardinality check below would then compare
+            // the response against a list that is no longer what was asked for. The Python client copies
+            // for the same reason.
+            const requested = [...addresses];
+            if (requested.length > MAX_BATCH_ADDRESSES) {
+                throw new RangeError(`addresses exceeds the ${MAX_BATCH_ADDRESSES}-address limit for one batch`);
+            }
+            if (requested.length === 0) {
+                return [];
+            }
+            const path = '/chain/accounts';
+            const response = await fetchImpl(joinUrl(httpBaseUrl, path), {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ addresses: requested }),
+            });
             const body = await parseReadResponse(response, path);
-            if (!body) {
-                return null;
+            // A different count would shift every later account onto the wrong address.
+            if (body.items.length !== requested.length) {
+                throw new TypeError(`Invalid chain response for '${path}': expected ${requested.length} items, got ${body.items.length}`);
             }
-            return {
-                address: body.address,
-                ownerProgram: body.ownerProgram,
-                lamports: body.lamports,
-                executable: body.executable,
-                data: decodeBase64(body.data),
-            };
+            // Positionally aligned with `requested`; absent accounts arrive as null.
+            return body.items.map(toRawAccount);
         },
         async mint(address) {
             const path = `/chain/mints/${encodeURIComponent(address)}`;
@@ -4805,12 +4858,18 @@ function serializeValue(value, type) {
     if ('vec' in type) {
         return serializeVec(value, type.vec);
     }
+    if ('vecU64Len' in type) {
+        return serializeVec(value, type.vecU64Len, 8);
+    }
     if ('option' in type) {
         return serializeOption(value, type.option);
     }
     if ('array' in type) {
         return serializeArray(value, type.array[0], type.array[1]);
     }
+    if ('tuple' in type) {
+        return serializeTuple(value, type.tuple);
+    }
     if ('hashMap' in type) {
         return serializeHashMap(value, type.hashMap[0], type.hashMap[1]);
     }
@@ -4838,6 +4897,15 @@ function serializeStruct(value, fields) {
     }
     return buffer.Buffer.concat(buffers);
 }
+function serializeTuple(value, elementTypes) {
+    if (!Array.isArray(value)) {
+        throw new Error(`Tuple value must be an array, got ${typeof value}`);
+    }
+    if (value.length !== elementTypes.length) {
+        throw new Error(`Tuple length mismatch: expected ${elementTypes.length}, got ${value.length}`);
+    }
+    return buffer.Buffer.concat(elementTypes.map((elementType, index) => serializeValue(value[index], elementType)));
+}
 function serializeHashMap(value, keyType, valueType) {
     if (keyType !== 'string') {
         throw new Error(`Instruction hashMap keys must use the 'string' schema, got ${JSON.stringify(keyType)}`);
@@ -5011,9 +5079,15 @@ function serializePrimitive(value, type) {
             throw new Error(`Unknown primitive type: ${type}`);
     }
 }
-function serializeVec(values, elementType) {
-    const len = buffer.Buffer.alloc(4);
-    len.writeUInt32LE(values.length, 0);
+// `lengthBytes`: 4 for Borsh, 8 for bincode-style sequences.
+function serializeVec(values, elementType, lengthBytes = 4) {
+    const len = buffer.Buffer.alloc(lengthBytes);
+    if (lengthBytes === 8) {
+        len.writeBigUInt64LE(BigInt(values.length), 0);
+    }
+    else {
+        len.writeUInt32LE(values.length, 0);
+    }
     const elementBuffers = values.map(v => serializeValue(v, elementType));
     return buffer.Buffer.concat([len, ...elementBuffers]);
 }
@@ -7245,22 +7319,22 @@ async function createSession(definition, ...args) {
 }
 
 function instructionOperation(prepare) {
-    return {
+    return brandOperationKind({
         kind: 'instruction',
         prepare: async (input) => prepare(input),
-    };
+    }, 'instruction');
 }
 function transactionOperation(prepare) {
-    return {
+    return brandOperationKind({
         kind: 'transaction',
         prepare: async (input) => prepare(input),
-    };
+    }, 'transaction');
 }
 function flowOperation(prepare) {
-    return {
+    return brandOperationKind({
         kind: 'flow',
         prepare: async (input) => prepare(input),
-    };
+    }, 'flow');
 }
 
 function chainAccountLoader(chain) {
@@ -7431,6 +7505,7 @@ exports.DEFAULT_MAX_ENTRIES_PER_VIEW = DEFAULT_MAX_ENTRIES_PER_VIEW;
 exports.FrameProcessor = FrameProcessor;
 exports.InstructionError = InstructionError;
 exports.MemoryAdapter = MemoryAdapter;
+exports.OPERATION_KIND = OPERATION_KIND;
 exports.OperationCallbackError = OperationCallbackError;
 exports.OperationExecutionError = OperationExecutionError;
 exports.PROGRAM_OPERATION_EXTENSIONS = PROGRAM_OPERATION_EXTENSIONS;
@@ -7494,6 +7569,7 @@ exports.formatPreparedOperation = formatPreparedOperation;
 exports.formatProgramError = formatProgramError;
 exports.formatRawToUi = formatRawToUi;
 exports.getMintDecimals = getMintDecimals;
+exports.getOperationKind = getOperationKind;
 exports.getProgramRuntimeExtensions = getProgramRuntimeExtensions;
 exports.getStackRuntimeExtensions = getStackRuntimeExtensions;
 exports.getTransactionFailureOutcome = getTransactionFailureOutcome;