stxer 0.3.3 → 0.4.0

package/src/clarity-api.ts

@@ -0,0 +1,186 @@
+import {
+  ClarityType,
+  type ClarityValue,
+  type OptionalCV,
+} from '@stacks/transactions';
+import type {
+  ClarityAbiFunction,
+  ClarityAbiMap,
+  ClarityAbiVariable,
+  TContractPrincipal,
+  TPrincipal,
+} from 'clarity-abi';
+import { decodeAbi, encodeAbi } from 'ts-clarity';
+import type {
+  InferReadonlyCallParameterType,
+  InferReadonlyCallResultType,
+  InferMapValueType,
+  InferReadMapParameterType,
+  InferReadVariableParameterType,
+  InferVariableType,
+} from 'ts-clarity';
+import { BatchProcessor } from './BatchProcessor';
+
+// Shared processor instance with default settings
+const defaultProcessor = new BatchProcessor({
+  batchDelayMs: 100,
+});
+
+export type ReadonlyCallRuntimeOptions = {
+  sender?: TPrincipal;
+  contract: TContractPrincipal;
+  stacksEndpoint?: string;
+  indexBlockHash?: string;
+  batchProcessor?: BatchProcessor;
+};
+
+export type ReadMapRuntimeParameters = {
+  contract: TContractPrincipal;
+  stacksEndpoint?: string;
+  proof?: boolean;
+  indexBlockHash?: string;
+  batchProcessor?: BatchProcessor;
+};
+
+export type ReadVariableRuntimeParameterType = {
+  contract: TContractPrincipal;
+  stacksEndpoint?: string;
+  proof?: boolean;
+  indexBlockHash?: string;
+  batchProcessor?: BatchProcessor;
+};
+
+export async function callReadonly<
+  Functions extends readonly ClarityAbiFunction[] | readonly unknown[],
+  FunctionName extends string,
+>(
+  params: InferReadonlyCallParameterType<Functions, FunctionName> &
+    ReadonlyCallRuntimeOptions,
+): Promise<InferReadonlyCallResultType<Functions, FunctionName>> {
+  const processor = params.batchProcessor ?? defaultProcessor;
+  const [deployer, contractName] = params.contract.split('.', 2);
+  const fn = String(params.functionName);
+  
+  const functionDef = (params.abi as readonly ClarityAbiFunction[]).find(
+    (def) => def.name === params.functionName,
+  );
+  if (!functionDef) {
+    throw new Error(`failed to find function definition for ${params.functionName}`);
+  }
+  
+  const argsKV = (params as unknown as { args: Record<string, unknown> }).args;
+  const args: ClarityValue[] = [];
+  for (const argDef of functionDef.args) {
+    args.push(encodeAbi(argDef.type, argsKV[argDef.name]));
+  }
+
+  return new Promise((resolve, reject) => {
+    processor.enqueue({
+      request: {
+        mode: 'readonly',
+        contractAddress: deployer,
+        contractName: contractName,
+        functionName: fn,
+        functionArgs: args,
+      },
+      tip: params.indexBlockHash,
+      resolve: (result: ClarityValue | OptionalCV) => {
+        try {
+          const decoded = decodeAbi(functionDef.outputs.type, result);
+          resolve(decoded as InferReadonlyCallResultType<Functions, FunctionName>);
+        } catch (error) {
+          reject(error);
+        }
+      },
+      reject,
+    });
+  });
+}
+
+export async function readMap<
+  Maps extends readonly ClarityAbiMap[] | readonly unknown[] = readonly ClarityAbiMap[],
+  MapName extends string = string,
+>(
+  params: InferReadMapParameterType<Maps, MapName> & ReadMapRuntimeParameters,
+): Promise<InferMapValueType<Maps, MapName> | null> {
+  const processor = params.batchProcessor ?? defaultProcessor;
+  const [deployer, contractName] = params.contract.split('.', 2);
+  
+  const mapDef = (params.abi as readonly ClarityAbiMap[]).find(
+    (m) => m.name === params.mapName,
+  );
+  if (!mapDef) {
+    throw new Error(`failed to find map definition for ${params.mapName}`);
+  }
+  
+  const key: ClarityValue = encodeAbi(mapDef.key, params.key);
+
+  return new Promise((resolve, reject) => {
+    processor.enqueue({
+      request: {
+        mode: 'mapEntry',
+        contractAddress: deployer,
+        contractName: contractName,
+        mapName: params.mapName,
+        mapKey: key,
+      },
+      tip: params.indexBlockHash,
+      resolve: (result: ClarityValue | OptionalCV) => {
+        try {
+          if (result.type === ClarityType.OptionalNone) {
+            resolve(null);
+            return;
+          }
+          if (result.type !== ClarityType.OptionalSome) {
+            throw new Error(`unexpected map value: ${result}`);
+          }
+          const someCV = result as { type: ClarityType.OptionalSome; value: ClarityValue };
+          const decoded = decodeAbi(mapDef.value, someCV.value);
+          resolve(decoded as InferMapValueType<Maps, MapName>);
+        } catch (error) {
+          reject(error);
+        }
+      },
+      reject,
+    });
+  });
+}
+
+export async function readVariable<
+  Variables extends readonly ClarityAbiVariable[] | readonly unknown[] = readonly ClarityAbiVariable[],
+  VariableName extends string = string,
+>(
+  params: InferReadVariableParameterType<Variables, VariableName> &
+    ReadVariableRuntimeParameterType,
+): Promise<InferVariableType<Variables, VariableName>> {
+  const processor = params.batchProcessor ?? defaultProcessor;
+  const [deployer, contractName] = params.contract.split('.', 2);
+  
+  const varDef = (params.abi as readonly ClarityAbiVariable[]).find(
+    (def) => def.name === params.variableName,
+  );
+  if (!varDef) {
+    throw new Error(`failed to find variable definition for ${params.variableName}`);
+  }
+
+  return new Promise((resolve, reject) => {
+    processor.enqueue({
+      request: {
+        mode: 'variable',
+        contractAddress: deployer,
+        contractName: contractName,
+        variableName: params.variableName,
+      },
+      tip: params.indexBlockHash,
+      resolve: (result: ClarityValue | OptionalCV) => {
+        try {
+          const decoded = decodeAbi(varDef.type, result);
+          resolve(decoded as InferVariableType<Variables, VariableName>);
+        } catch (error) {
+          reject(error);
+        }
+      },
+      reject,
+    });
+  });
+}

package/src/index.ts

@@ -1,2 +1,3 @@
-export * from './batch-api';
+export * from './BatchAPI';
 export * from './simulation';
+export * from './clarity-api';

package/src/sample/read.ts

@@ -1,127 +1,184 @@
 import {
-    contractPrincipalCV,
-    principalCV,
-    stringAsciiCV,
-    tupleCV,
-    uintCV,
-  } from '@stacks/transactions';
-  import { batchRead, batchReadonly } from '../batch-api';
-  
-  async function batchReadsExample() {
-    const rs = await batchRead({
-      // index_block_hash:
-      //   'ce04817b9c6d90814ff9c06228d3a07d64335b1d9b01a233456fc304e34f7c0e', // block 373499
-      variables: [
-        {
-          contract: contractPrincipalCV(
-            'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
-            'liquidity-token-v5kbe3oqvac'
-          ),
-          variableName: 'balance-x',
-        },
-        {
-          contract: contractPrincipalCV(
-            'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
-            'liquidity-token-v5kbe3oqvac'
-          ),
-          variableName: 'balance-y',
-        },
-        {
-          contract: contractPrincipalCV(
-            'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
-            'liquidity-token-v5kbe3oqvac'
-          ),
-          variableName: 'something-not-exists',
-        },
-      ],
-      maps: [
-        {
-          contract: contractPrincipalCV(
-            'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM',
-            'amm-registry-v2-01'
-          ),
-          mapName: 'pools-data-map',
-          mapKey: tupleCV({
-            'token-x': principalCV(
-              'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2'
-            ),
-            'token-y': principalCV(
-              'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex'
-            ),
-            factor: uintCV(1e8),
-          }),
-        },
-        {
-          contract: contractPrincipalCV(
-            'SP1Y5YSTAHZ88XYK1VPDH24GY0HPX5J4JECTMY4A1',
-            'univ2-core'
+  contractPrincipalCV,
+  principalCV,
+  tupleCV,
+  uintCV,
+} from '@stacks/transactions';
+import { SIP010TraitABI } from 'clarity-abi/abis'
+import { batchRead } from '../BatchAPI';
+import { BatchProcessor } from '../BatchProcessor';
+import { callReadonly, readMap, readVariable } from '../clarity-api';
+import { unwrapResponse } from 'ts-clarity';
+
+async function batchReadsExample() {
+  const rs = await batchRead({
+    // index_block_hash:
+    //   'ce04817b9c6d90814ff9c06228d3a07d64335b1d9b01a233456fc304e34f7c0e', // block 373499
+    variables: [
+      {
+        contract: contractPrincipalCV(
+          'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
+          'liquidity-token-v5kbe3oqvac'
+        ),
+        variableName: 'balance-x',
+      },
+      {
+        contract: contractPrincipalCV(
+          'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
+          'liquidity-token-v5kbe3oqvac'
+        ),
+        variableName: 'balance-y',
+      },
+      {
+        contract: contractPrincipalCV(
+          'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
+          'liquidity-token-v5kbe3oqvac'
+        ),
+        variableName: 'something-not-exists',
+      },
+    ],
+    maps: [
+      {
+        contract: contractPrincipalCV(
+          'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM',
+          'amm-registry-v2-01'
+        ),
+        mapName: 'pools-data-map',
+        mapKey: tupleCV({
+          'token-x': principalCV(
+            'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2'
           ),
-          mapName: 'pools',
-          mapKey: uintCV(1),
-        },
-        {
-          contract: contractPrincipalCV(
-            'SP1Y5YSTAHZ88XYK1VPDH24GY0HPX5J4JECTMY4A1',
-            'contract-not-exists'
+          'token-y': principalCV(
+            'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex'
           ),
-          mapName: 'pools',
-          mapKey: uintCV(1),
-        },
-      ],
+          factor: uintCV(1e8),
+        }),
+      },
+      {
+        contract: contractPrincipalCV(
+          'SP1Y5YSTAHZ88XYK1VPDH24GY0HPX5J4JECTMY4A1',
+          'univ2-core'
+        ),
+        mapName: 'pools',
+        mapKey: uintCV(1),
+      },
+      {
+        contract: contractPrincipalCV(
+          'SP1Y5YSTAHZ88XYK1VPDH24GY0HPX5J4JECTMY4A1',
+          'contract-not-exists'
+        ),
+        mapName: 'pools',
+        mapKey: uintCV(1),
+      },
+    ],
+  });
+  console.log(rs);
+}
+
+async function batchQueueProcessorExample() {
+  const processor = new BatchProcessor({
+    stxerAPIEndpoint: 'https://api.stxer.xyz',
+    batchDelayMs: 1000,
+  });
+
+
+  const promiseA = new Promise((resolve, reject) => {
+    processor.enqueue({
+      request: {
+        mode: 'variable',
+        contractAddress: 'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
+        contractName: 'liquidity-token-v5kbe3oqvac',
+        variableName: 'balance-x',
+      },
+      resolve: resolve,
+      reject: reject,
     });
-    console.log(rs);
-  }
-  
-  async function batchReadonlyExample() {
-    const rs = await batchReadonly({
-      index_block_hash:
-        'ce04817b9c6d90814ff9c06228d3a07d64335b1d9b01a233456fc304e34f7c0e',
-      readonly: [
-        {
-          contract: contractPrincipalCV(
-            'SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4',
-            'sbtc-token'
-          ),
-          functionName: 'get-total-supply',
-          functionArgs: [],
-        },
-        {
-          contract: contractPrincipalCV(
-            'SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4',
-            'sbtc-token'
-          ),
-          functionName: 'get-balance',
-          functionArgs: [
-            principalCV('SP1CT7J2RWBZD62QAX36A2PQ3HKH5NFDGVHB8J34V'),
-          ],
-        },
+  });
+
+  const promiseB = new Promise((resolve, reject) => {
+    processor.enqueue({
+      request: {
+        mode: 'variable',
+        contractAddress: 'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
+        contractName: 'liquidity-token-v5kbe3oqvac',
+        variableName: 'balance-y',
+      },
+      resolve: resolve,
+      reject: reject,
+    });
+  });
+
+  const result = await Promise.all([promiseA, promiseB]);
+  console.log(result);
+}
+
+// https://explorer.hiro.so/txid/SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.trait-sip-010
+const sip010 = {
+  functions: [
+    {
+      name: 'get-balance',
+      access: 'read_only',
+      args: [
         {
-          contract: contractPrincipalCV(
-            'SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4',
-            'sbtc-token'
-          ),
-          functionName: 'function-not-exists',
-          functionArgs: [],
-        },
-        {
-          contract: contractPrincipalCV(
-            'SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4',
-            'sbtc-token'
-          ),
-          functionName: 'get-balance',
-          functionArgs: [stringAsciiCV('invalid-args')],
+          name: 'who',
+          type: 'principal',
         },
       ],
-    });
-    console.log(rs);
-  }
-  
-  async function main() {
-    await batchReadsExample();
-    // await batchReadonlyExample();
-  }
-  
-  if (require.main === module) {
-    main().catch(console.error);
-  }
-  
+      outputs: {
+        type: {
+          response: {
+            ok: 'uint128',
+            error: 'none',
+          },
+        },
+      },
+    },
+  ],
+  variables: [],
+  maps: [],
+  fungible_tokens: [],
+  non_fungible_tokens: [],
+  epoch: 'Epoch2_05',
+  clarity_version: 'Clarity1',
+} as const;
+
+async function batchSip010Example() {
+  const supply = callReadonly({
+    abi: SIP010TraitABI.functions,
+    functionName: 'get-total-supply',
+    contract: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex',
+  }).then(unwrapResponse)
+  const balance = callReadonly({
+    abi: SIP010TraitABI.functions,
+    functionName: 'get-balance',
+    contract: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex',
+    args: {
+      who: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-vault-v2-01',
+    },
+  }).then(unwrapResponse)
+  const paused = readVariable({
+    abi: [{ name: 'paused', type: 'bool', access: 'variable' },],
+    variableName: 'paused',
+    contract: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-vault-v2-01',
+  });
+  const approved = readMap({
+    abi: [
+      { key: 'principal', name: 'approved-tokens', value: 'bool' }, 
+    ],
+    mapName: 'approved-tokens',
+    key: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex',
+    contract: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-vault-v2-01',
+  })
+  const result = await Promise.all([supply, balance, paused, approved]);
+  console.log(result);
+}
+
+async function main() {
+  await batchReadsExample();
+  await batchQueueProcessorExample();
+  await batchSip010Example();
+}
+
+if (require.main === module) {
+  main().catch(console.error);
+}