@ar.io/sdk 3.10.0 → 3.11.0-alpha.1

package/lib/esm/common/wayfinder/routers/random.test.js

@@ -0,0 +1,102 @@
+import { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+import { RandomGatewayRouter } from './random.js';
+describe('RandomRouter', () => {
+    const mockGateways = [
+        {
+            settings: {
+                fqdn: 'gateway1.net',
+                port: 443,
+                protocol: 'https',
+                allowDelegatedStaking: false,
+                delegateRewardShareRatio: 0.5,
+                allowedDelegates: [],
+                minDelegatedStake: 0,
+                autoStake: false,
+                properties: '',
+                label: '',
+                note: '',
+            },
+            gatewayAddress: 'addr1',
+            observerAddress: 'addr1',
+            totalDelegatedStake: 1000,
+            startTimestamp: 0,
+            endTimestamp: 0,
+            operatorStake: 100,
+            status: 'joined',
+            weights: {
+                normalizedCompositeWeight: 0.5,
+                stakeWeight: 0.5,
+                tenureWeight: 0.5,
+                gatewayPerformanceRatio: 0.5,
+                observerPerformanceRatio: 0.5,
+                compositeWeight: 0.5,
+                gatewayRewardRatioWeight: 0.5,
+                observerRewardRatioWeight: 0.5,
+            },
+            stats: {
+                passedConsecutiveEpochs: 10,
+                failedConsecutiveEpochs: 5,
+                totalEpochCount: 15,
+                passedEpochCount: 10,
+                failedEpochCount: 5,
+                observedEpochCount: 15,
+                prescribedEpochCount: 20,
+            },
+        },
+        {
+            settings: {
+                fqdn: 'gateway2.net',
+                port: 443,
+                protocol: 'https',
+                allowDelegatedStaking: false,
+                delegateRewardShareRatio: 0.5,
+                allowedDelegates: [],
+                minDelegatedStake: 0,
+                autoStake: false,
+                properties: '',
+                label: '',
+                note: '',
+            },
+            gatewayAddress: 'addr2',
+            observerAddress: 'addr2',
+            totalDelegatedStake: 0,
+            startTimestamp: 0,
+            endTimestamp: 0,
+            operatorStake: 0,
+            status: 'leaving',
+            weights: {
+                normalizedCompositeWeight: 0.5,
+                stakeWeight: 0.5,
+                tenureWeight: 0.5,
+                gatewayPerformanceRatio: 0.5,
+                observerPerformanceRatio: 0.5,
+                compositeWeight: 0.5,
+                gatewayRewardRatioWeight: 0.5,
+                observerRewardRatioWeight: 0.5,
+            },
+            stats: {
+                passedConsecutiveEpochs: 10,
+                failedConsecutiveEpochs: 5,
+                totalEpochCount: 15,
+                passedEpochCount: 10,
+                failedEpochCount: 5,
+                observedEpochCount: 15,
+                prescribedEpochCount: 20,
+            },
+        },
+    ];
+    const mockGatewaysProvider = {
+        getGateways: async () => mockGateways,
+    };
+    it('should only return joined gateways', async () => {
+        const router = new RandomGatewayRouter({
+            gatewaysProvider: mockGatewaysProvider,
+        });
+        // Run multiple times to ensure we only get joined gateways
+        for (let i = 0; i < 10; i++) {
+            const result = await router.getTargetGateway();
+            assert.deepStrictEqual(result, new URL('https://gateway1.net'));
+        }
+    });
+});

package/lib/esm/common/wayfinder/routers/simple-cache.js

@@ -0,0 +1,21 @@
+export class SimpleCacheRouter {
+    name;
+    lastUpdatedTimestamp;
+    ttlSeconds;
+    targetGateway;
+    router;
+    constructor({ router, ttlSeconds = 5 * 60, // 5 minutes
+     }) {
+        this.router = router;
+        this.ttlSeconds = ttlSeconds;
+    }
+    async getTargetGateway() {
+        if (this.targetGateway === undefined ||
+            this.lastUpdatedTimestamp + this.ttlSeconds * 1000 < Date.now()) {
+            this.targetGateway = await this.router.getTargetGateway();
+            this.lastUpdatedTimestamp = Date.now();
+        }
+        return this.targetGateway;
+    }
+}
+// TODO: a router that accepts ario and a router, and adds read through promise cache to ario.getGateways to avoid calling the ARIO contract on every request

package/lib/esm/common/wayfinder/routers/simple-cache.test.js

@@ -0,0 +1,39 @@
+import { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+import { SimpleCacheRouter } from './simple-cache.js';
+describe('SimpleCacheRouter', () => {
+    it('should cache gateway for TTL period even if underlying gateway changes', async () => {
+        const gateway1 = new URL('https://gateway1.net');
+        const gateway2 = new URL('https://gateway2.net');
+        let currentGateway = gateway1;
+        const mockRouter = {
+            name: 'mock',
+            getTargetGateway: async () => currentGateway,
+        };
+        const router = new SimpleCacheRouter({
+            router: mockRouter,
+            ttlSeconds: 300, // 5 minutes
+        });
+        // Get initial gateway which should be cached
+        const initial = await router.getTargetGateway();
+        assert.deepStrictEqual(initial, gateway1);
+        // Change the underlying gateway
+        currentGateway = gateway2;
+        // Should still return cached gateway1 for multiple calls
+        for (let i = 0; i < 5; i++) {
+            const result = await router.getTargetGateway();
+            assert.deepStrictEqual(result, gateway1);
+        }
+        // Advance time past TTL
+        const originalNow = Date.now;
+        try {
+            Date.now = () => originalNow() + 300 * 1000 + 1;
+            // Should now return the new gateway2
+            const result = await router.getTargetGateway();
+            assert.deepStrictEqual(result, gateway2);
+        }
+        finally {
+            Date.now = originalNow;
+        }
+    });
+});

package/lib/esm/common/wayfinder/wayfinder.js

@@ -0,0 +1,161 @@
+import { ARIO } from '../io.js';
+import { ARIOGatewaysProvider } from './gateways.js';
+import { RandomGatewayRouter } from './routers/random.js';
+// known regexes for wayfinder urls
+export const arnsRegex = /^[a-z0-9_-]{1,51}$/;
+export const txIdRegex = /^[a-z0-9]{43}$/;
+/**
+ * Core function to resolve a wayfinder url against a target gateway
+ * @param originalUrl - the wayfinder url to resolve
+ * @param targetGateway - the target gateway to resolve the url against
+ * @returns the resolved url that can be used to make a request
+ */
+export const resolveWayfinderUrl = ({ originalUrl, targetGateway, }) => {
+    if (originalUrl.toString().startsWith('ar://')) {
+        const [, path] = originalUrl.toString().split('ar://');
+        // e.g. ar:///info should route to the info endpoint of the target gateway
+        if (path.startsWith('/')) {
+            return new URL(path.slice(1), targetGateway);
+        }
+        // TODO: this breaks 43 character named arns names - we should check a a local name cache list before resolving raw transaction ids
+        if (txIdRegex.test(path)) {
+            const [txId, ...rest] = path.split('/');
+            return new URL(`${txId}${rest.join('/')}`, targetGateway);
+        }
+        if (arnsRegex.test(path)) {
+            // TODO: tests to ensure arns names support query params and paths
+            const [name, ...rest] = path.split('/');
+            const targetGatewayUrl = new URL(targetGateway);
+            const arnsUrl = `${targetGatewayUrl.protocol}//${name}.${targetGatewayUrl.hostname}${targetGatewayUrl.port ? `:${targetGatewayUrl.port}` : ''}`;
+            return new URL(rest.join('/'), arnsUrl);
+        }
+        // TODO: support .eth addresses
+        // TODO: "gasless" routing via DNS TXT records (e.g. ar://gatewaypie.com -> TXT record lookup for TX ID and redirect to that gateway)
+    }
+    // return the original url if it's not a wayfinder url (allows you to use the wayfinder client with non-wayfinder urls)
+    return new URL(originalUrl);
+};
+/**
+ * Creates a wrapped http client that supports ar:// protocol
+ *
+ * This function leverages a Proxy to intercept calls to the http client
+ * and redirects them to the target gateway using the resolveUrl function url.
+ * It also supports the http client methods like get(), post(), put(), delete(), etc.
+ *
+ * Any URLs provided that are not wayfinder urls will be returned as is.
+ *
+ * @param httpClient - the http client to wrap (e.g. axios, fetch, got, etc.)
+ * @param resolveUrl - the function to construct the redirect url for ar:// requests
+ * @returns a wrapped http client that supports ar:// protocol
+ */
+export const createWayfinderClient = ({ httpClient, resolveUrl, }) => {
+    const wayfinderRedirect = async (fn, rawArgs) => {
+        // TODO: handle if first arg is not a string (i.e. just return the result of the function call)
+        const [originalUrl, ...rest] = rawArgs;
+        // route the request to the target gateway
+        const redirectUrl = await resolveUrl({
+            originalUrl,
+        });
+        // make the request to the target gateway using the redirect url and http client
+        const response = await fn(redirectUrl.toString(), ...rest);
+        // TODO: if verifyDataHash is provided, verify the data hash before returning
+        return response;
+    };
+    return new Proxy(httpClient, {
+        // support direct calls: fetch('ar://…', options)
+        // axios() or got()
+        apply: (_target, _thisArg, argArray) => wayfinderRedirect(httpClient, argArray),
+        // support http clients that use methods like `got.get`, `got.post`, `axios.get`, etc. while still using the wayfinder redirect function
+        get: (target, prop, receiver) => {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value === 'function') {
+                return (...inner) => wayfinderRedirect(value.bind(target), inner);
+            }
+            return value; // numbers, objects, symbols pass through untouched
+        },
+    });
+};
+/**
+ * The main class for the wayfinder
+ * @param router - the router to use for requests
+ * @param httpClient - the http client to use for requests
+ * @param blocklist - the blocklist of gateways to avoid
+ */
+export class Wayfinder {
+    /**
+     * The router to use for requests
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     * });
+     */
+    router;
+    /**
+     * The http client to use for requests
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     *   httpClient: axios,
+     * });
+     */
+    httpClient;
+    /**
+     * The function that resolves the redirect url for ar:// requests to a target gateway
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     *   httpClient: axios,
+     * });
+     *
+     * const redirectUrl = await wayfinder.resolveUrl({ originalUrl: 'ar://example' });
+     */
+    resolveUrl;
+    /**
+     * A wrapped http client that supports ar:// protocol
+     *
+     * @example
+     * const { request: wayfind } = new Wayfinder({
+     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     *   httpClient: axios,
+     * });;
+     *
+     * TODO: consider a top level function that supports wayfinder routing under the hood
+     * const response = await wayfind('ar://', {
+     *   method: 'POST',
+     *   data: {
+     *     name: 'John Doe',
+     *   },
+     * })
+     */
+    request;
+    // TODO: stats provider
+    // TODO: metricsProvider for otel/prom support
+    // TODO: private verificationSettings: {
+    //   trustedGateways: URL[];
+    //   method: 'local' | 'remote';
+    // };
+    constructor({ 
+    // TODO: consider changing router to routingStrategy or strategy
+    router = new RandomGatewayRouter({
+        // optionally use a cache gateways provider to reduce the number of requests to the contract
+        gatewaysProvider: new ARIOGatewaysProvider({ ario: ARIO.mainnet() }),
+    }), httpClient,
+    // TODO: add verifier interface that provides a verifyDataHash function
+    // TODO: stats provider
+     }) {
+        this.router = router;
+        this.httpClient = httpClient;
+        this.resolveUrl = async ({ originalUrl }) => resolveWayfinderUrl({
+            originalUrl,
+            targetGateway: await this.router.getTargetGateway(),
+        });
+        this.request = createWayfinderClient({
+            httpClient,
+            resolveUrl: this.resolveUrl,
+            // TODO: provide the verifyDataHash function from the verifier to the wayfinder client along with verificationSettings
+        });
+    }
+}

package/lib/esm/common/wayfinder/wayfinder.test.js

@@ -0,0 +1,248 @@
+import axios from 'axios';
+import got from 'got';
+import assert from 'node:assert';
+import { buffer } from 'node:stream/consumers';
+import { before, describe, it } from 'node:test';
+import { RandomGatewayRouter } from './routers/random.js';
+import { Wayfinder } from './wayfinder.js';
+const stubbedGateway = {
+    status: 'joined',
+    gatewayAddress: 'arweave',
+    operatorStake: 1000,
+    totalDelegatedStake: 1000,
+    startTimestamp: 1000,
+    settings: {
+        protocol: 'https',
+        fqdn: 'arweave.net',
+        port: 443,
+    },
+};
+const stubbedGatewaysProvider = {
+    getGateways: async () => [stubbedGateway],
+};
+describe('Wayfinder', () => {
+    describe('http wrapper', () => {
+        describe('fetch', () => {
+            let wayfinder;
+            before(() => {
+                wayfinder = new Wayfinder({
+                    httpClient: fetch,
+                    router: new RandomGatewayRouter({
+                        gatewaysProvider: stubbedGatewaysProvider,
+                    }),
+                });
+            });
+            it('should fetch the data using the selected gateway', async () => {
+                const nativeFetch = await fetch('https://ao.arweave.net');
+                const response = await wayfinder.request('ar://ao');
+                assert.strictEqual(response.status, 200);
+                assert.strictEqual(response.status, nativeFetch.status);
+                // assert the arns headers are the same
+                const arnsHeaders = Array.from(response.headers.entries()).filter(([key]) => key.startsWith('x-arns-'));
+                const nativeFetchHeaders = Array.from(nativeFetch.headers.entries()).filter(([key]) => key.startsWith('x-arns-'));
+                assert.deepStrictEqual(arnsHeaders, nativeFetchHeaders);
+                assert.deepStrictEqual(await response.text(), await nativeFetch.text());
+            });
+            it('should route a non-ar:// url as a normal fetch', async () => {
+                const [nativeFetch, response] = await Promise.all([
+                    fetch('https://arweave.net/', {
+                        method: 'HEAD',
+                    }),
+                    wayfinder.request('https://arweave.net/', {
+                        method: 'HEAD',
+                    }),
+                ]);
+                assert.strictEqual(response.status, 200);
+                assert.strictEqual(response.status, nativeFetch.status);
+                // TODO: ensure the headers are the same excluding unique headers
+                assert.deepStrictEqual(await response.text(), await nativeFetch.text());
+            });
+            for (const api of ['/info', '/metrics', '/block/current']) {
+                it(`supports native arweave node apis ${api}`, async () => {
+                    const [nativeFetch, response] = await Promise.all([
+                        fetch(`https://arweave.net${api}`),
+                        wayfinder.request(`ar:///${api}`),
+                    ]);
+                    assert.strictEqual(response.status, 200);
+                    assert.strictEqual(response.status, nativeFetch.status);
+                    // TODO: ensure the headers are the same excluding unique headers
+                    assert.deepStrictEqual(await response.text(), await nativeFetch.text());
+                });
+            }
+            for (const api of ['/ar-io/info', '/ar-io/__gateway_metrics']) {
+                it(`supports native ario node gateway apis ${api}`, async () => {
+                    const [nativeFetch, response] = await Promise.all([
+                        fetch(`https://arweave.net${api}`),
+                        wayfinder.request(`ar:///${api}`),
+                    ]);
+                    assert.strictEqual(response.status, 200);
+                    assert.strictEqual(response.status, nativeFetch.status);
+                    // TODO: ensure the headers are the same excluding unique headers
+                    assert.deepStrictEqual(await response.text(), await nativeFetch.text());
+                });
+            }
+            it('supports a post request to graphql', async () => {
+                const response = await wayfinder.request('ar:///graphql', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        query: `
+                query {
+                  transactions(
+                    ids: ["xf958qhCNGfDme1FtoiD6DtMfDENDbtxZpjOM_1tsMM"]
+                  ) {
+                    edges {
+                      cursor
+                      node {
+                        id
+                        tags {
+                          name
+                          value
+                        }
+                        block {
+                          height
+                          timestamp
+                        }
+                      }
+                    }
+                    pageInfo {
+                      hasNextPage
+                    }
+                  }
+                }
+            `,
+                    }),
+                });
+                assert.strictEqual(response.status, 200);
+            });
+            it('returns the error from the target gateway if the route is not found', async () => {
+                const [nativeFetch, response] = await Promise.all([
+                    fetch('https://arweave.net/not-found'),
+                    wayfinder.request('https://arweave.net/not-found'),
+                ]);
+                assert.strictEqual(response.status, nativeFetch.status);
+                assert.strictEqual(response.statusText, nativeFetch.statusText);
+                assert.deepStrictEqual(await response.text(), await nativeFetch.text());
+            });
+        });
+        describe('axios', () => {
+            let wayfinder;
+            before(() => {
+                wayfinder = new Wayfinder({
+                    httpClient: axios,
+                    router: new RandomGatewayRouter({
+                        gatewaysProvider: stubbedGatewaysProvider,
+                    }),
+                });
+            });
+            it('should fetch the data using axios default function against the target gateway', async () => {
+                const [nativeAxios, response] = await Promise.all([
+                    axios('https://ao.arweave.net'),
+                    wayfinder.request('ar://ao'),
+                ]);
+                assert.strictEqual(response.status, 200);
+                assert.strictEqual(response.status, nativeAxios.status);
+                // assert the arns headers are the same
+                const arnsHeaders = Object.entries(response.headers)
+                    .sort()
+                    .filter(([key]) => key.startsWith('x-arns-'));
+                const nativeAxiosHeaders = Object.entries(nativeAxios.headers).filter(([key]) => key.startsWith('x-arns-'));
+                assert.deepStrictEqual(arnsHeaders.sort(), nativeAxiosHeaders.sort());
+                assert.deepStrictEqual(response.data, nativeAxios.data);
+            });
+            it('should fetch the data using the axios.get method against the target gateway', async () => {
+                const [nativeAxios, response] = await Promise.all([
+                    axios.get('https://ao.arweave.net'),
+                    wayfinder.request.get('ar://ao'),
+                ]);
+                assert.strictEqual(response.status, 200);
+                assert.strictEqual(response.status, nativeAxios.status);
+                // assert the arns headers are the same
+                const arnsHeaders = Object.entries(response.headers)
+                    .sort()
+                    .filter(([key]) => key.startsWith('x-arns-'));
+                const nativeAxiosHeaders = Object.entries(nativeAxios.headers).filter(([key]) => key.startsWith('x-arns-'));
+                assert.deepStrictEqual(arnsHeaders.sort(), nativeAxiosHeaders.sort());
+                assert.deepStrictEqual(response.data, nativeAxios.data);
+            });
+            it('should route a non-ar:// url as a normal axios request', async () => {
+                const [nativeAxios, response] = await Promise.all([
+                    axios('https://arweave.net/'),
+                    wayfinder.request('https://arweave.net/'),
+                ]);
+                assert.strictEqual(response.status, 200);
+                assert.strictEqual(response.status, nativeAxios.status);
+                assert.deepStrictEqual(response.data, nativeAxios.data);
+                // TODO: ensure the headers are the same excluding unique headers
+            });
+            for (const api of ['/info', '/metrics', '/block/current']) {
+                it(`supports native arweave node apis ${api}`, async () => {
+                    const [nativeAxios, response] = await Promise.all([
+                        axios(`https://arweave.net${api}`),
+                        wayfinder.request(`ar:///${api}`),
+                    ]);
+                    assert.strictEqual(response.status, 200);
+                    assert.strictEqual(response.status, nativeAxios.status);
+                    // TODO: ensure the headers are the same excluding unique headers
+                    assert.deepStrictEqual(response.data, nativeAxios.data);
+                });
+            }
+            for (const api of ['/ar-io/info', '/ar-io/__gateway_metrics']) {
+                it(`supports native ario node gateway apis ${api}`, async () => {
+                    const [nativeAxios, response] = await Promise.all([
+                        axios(`https://arweave.net${api}`),
+                        wayfinder.request(`ar:///${api}`),
+                    ]);
+                    assert.strictEqual(response.status, 200);
+                    assert.strictEqual(response.status, nativeAxios.status);
+                    // TODO: ensure the headers are the same excluding unique headers
+                    assert.deepStrictEqual(response.data, nativeAxios.data);
+                });
+            }
+            it('should return the error from the target gateway if the route is not found', async () => {
+                const axiosInstance = axios.create({
+                    validateStatus: () => true, // don't throw so we can compare axios result with wrapped axios result
+                });
+                const wayfinder = new Wayfinder({
+                    httpClient: axiosInstance,
+                    router: new RandomGatewayRouter({
+                        gatewaysProvider: stubbedGatewaysProvider,
+                    }),
+                });
+                const [nativeAxios, response] = await Promise.all([
+                    axiosInstance('https://arweave.net/not-found'),
+                    wayfinder.request('https://arweave.net/not-found'),
+                ]);
+                assert.strictEqual(response.status, nativeAxios.status);
+                assert.strictEqual(response.data, nativeAxios.data);
+            });
+        });
+        describe('got', () => {
+            let wayfinder;
+            before(() => {
+                wayfinder = new Wayfinder({
+                    httpClient: got,
+                    router: new RandomGatewayRouter({
+                        gatewaysProvider: stubbedGatewaysProvider,
+                    }),
+                });
+            });
+            it('should fetch the data using the got default function against the target gateway', async () => {
+                const [nativeGot, response] = await Promise.all([
+                    got('https://ao.arweave.net'),
+                    wayfinder.request('ar://ao'),
+                ]);
+                assert.strictEqual(response.statusCode, 200);
+                assert.strictEqual(response.statusCode, nativeGot.statusCode);
+                assert.deepStrictEqual(response.body, nativeGot.body);
+            });
+            it('should stream the data using got.stream against the selected target gateway', async () => {
+                const nativeBuffer = await buffer(await got.stream('https://ao.arweave.net', { decompress: false }));
+                const wayfinderBuffer = await buffer(await wayfinder.request.stream('ar://ao', { decompress: false }));
+                assert.deepStrictEqual(wayfinderBuffer, nativeBuffer);
+            });
+        });
+    });
+});

package/lib/esm/types/ant.js

@@ -77,6 +77,17 @@ export const AntStateSchema = z.object({
         .boolean()
         .describe('Flag indicating whether the ANT has been initialized.'),
 });
+export const SpawnANTStateSchema = z.object({
+    name: z.string().describe('The name of the ANT.'),
+    ticker: z.string().describe('The ticker symbol for the ANT.'),
+    description: z.string().describe('The description for the ANT.'),
+    keywords: AntKeywordsSchema.describe('The keywords for the ANT.'),
+    owner: AOAddressSchema.describe('The Owners address.'),
+    controllers: AntControllersSchema.describe('Controllers of the ANT who have administrative privileges.'),
+    records: AntRecordsSchema.describe('Records associated with the ANT.'),
+    balances: AntBalancesSchema.describe('Balance details for each address holding the ANT.'),
+    logo: ArweaveTxIdSchema.describe('Transaction ID of the ANT logo.'),
+});
 export const AntReadHandlers = [
     'balance',
     'balances',

package/lib/esm/types/index.js

@@ -19,3 +19,4 @@ export * from './common.js';
 export * from './faucet.js';
 export * from './io.js';
 export * from './token.js';
+export * from './wayfinder.js';

package/lib/esm/types/io.js

@@ -22,7 +22,7 @@ export const intentsUsingYears = [
 export const isValidIntent = (intent) => {
     return validIntents.indexOf(intent) !== -1;
 };
-export const fundFromOptions = ['balance', 'stakes', 'any'];
+export const fundFromOptions = ['balance', 'stakes', 'any', 'turbo'];
 export const isValidFundFrom = (fundFrom) => {
     return fundFromOptions.indexOf(fundFrom) !== -1;
 };

package/lib/esm/types/wayfinder.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/utils/ao.js

@@ -19,8 +19,13 @@ import { z } from 'zod';
 import { defaultArweave } from '../common/arweave.js';
 import { AOProcess, Logger } from '../common/index.js';
 import { ANT_LUA_ID, ANT_REGISTRY_ID, AOS_MODULE_ID, AO_AUTHORITY, DEFAULT_SCHEDULER_ID, } from '../constants.js';
+import { SpawnANTStateSchema } from '../types/ant.js';
+import { parseSchemaResult } from './schema.js';
 export async function spawnANT({ signer, module = AOS_MODULE_ID, ao = connect(), scheduler = DEFAULT_SCHEDULER_ID, state, antRegistryId = ANT_REGISTRY_ID, logger = Logger.default, authority = AO_AUTHORITY, }) {
     // TODO: use On-Boot data handler for bootstrapping state instead of initialize-state
+    if (state) {
+        parseSchemaResult(SpawnANTStateSchema, state);
+    }
     const processId = await ao.spawn({
         module,
         scheduler,

package/lib/esm/utils/random.js

@@ -0,0 +1,26 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { webcrypto } from 'crypto';
+/**
+ * Cryptographically secure helper for randomness, does not support seeding
+ * @param min - the minimum value
+ * @param max - the maximum value
+ * @returns a random integer between min and max
+ */
+export const randomInt = (min, max) => {
+    const [rand] = webcrypto.getRandomValues(new Uint32Array(1));
+    return min + (rand % (max - min));
+};