@algorandfoundation/algorand-typescript 0.0.1-alpha.16 → 0.0.1-alpha.17

package/arc-28.d.ts

@@ -0,0 +1,34 @@
+import { DeliberateAny } from './typescript-helpers';
+/**
+ * Emit an arc28 event log using either an ARC4Struct type or a named object type.
+ * Object types must have an ARC4 equivalent type.
+ *
+ * Anonymous types cannot be used as the type name is used to determine the event prefix
+ * @param event An ARC4Struct instance, or a plain object with a named type
+ *
+ * @example
+ * class Demo extends Struct<{ a: UintN64 }> {}
+ * emit(new Demo({ a: new UintN64(123) }))
+ *
+ * @example
+ * type Demo = { a: uint64 }
+ * emit<Demo>({a: 123})
+ * // or
+ * const d: Demo = { a: 123 }
+ * emit(d)
+ */
+export declare function emit<TEvent extends Record<string, DeliberateAny>>(event: TEvent): void;
+/**
+ * Emit an arc28 event log using an explicit name and inferred property/field types.
+ * Property types must be ARC4 or have an ARC4 equivalent type.
+ * @param eventName The name of the event (must be a compile time constant)
+ * @param eventProps A set of event properties (order is significant)
+ *
+ * @example
+ * emit("Demo", new UintN64(123))
+ *
+ * @example
+ * const a: uint64 = 123
+ * emit("Demo", a)
+ */
+export declare function emit<TProps extends [...DeliberateAny[]]>(eventName: string, ...eventProps: TProps): void;

package/arc4/encoded-types.d.ts

@@ -1,41 +1,52 @@
-import { biguint, BigUintCompat, bytes, BytesBacked, StringCompat, uint64, Uint64Compat } from '../primitives';
+import { biguint, BigUintCompat, bytes, BytesBacked, BytesCompat, StringCompat, uint64, Uint64Compat } from '../primitives';
 import { Account } from '../reference';
-export type BitSize = 8 | 16 | 32 | 64 | 128 | 256 | 512;
-type NativeForArc4Int<N extends BitSize> = N extends 8 | 16 | 32 | 64 ? uint64 : biguint;
-type CompatForArc4Int<N extends BitSize> = N extends 8 | 16 | 32 | 64 ? Uint64Compat : BigUintCompat;
-declare abstract class ARC4Encoded implements BytesBacked {
-    abstract __type?: string;
+type UintBitSize = 8 | 16 | 24 | 32 | 40 | 48 | 56 | 64;
+type BigUintBitSize = 72 | 80 | 88 | 96 | 104 | 112 | 120 | 128 | 136 | 144 | 152 | 160 | 168 | 176 | 184 | 192 | 200 | 208 | 216 | 224 | 232 | 240 | 248 | 256 | 264 | 272 | 280 | 288 | 296 | 304 | 312 | 320 | 328 | 336 | 344 | 352 | 360 | 368 | 376 | 384 | 392 | 400 | 408 | 416 | 424 | 432 | 440 | 448 | 456 | 464 | 472 | 480 | 488 | 496 | 504 | 512;
+export type BitSize = UintBitSize | BigUintBitSize;
+type NativeForArc4Int<N extends BitSize> = N extends UintBitSize ? uint64 : biguint;
+type CompatForArc4Int<N extends BitSize> = N extends UintBitSize ? Uint64Compat : BigUintCompat;
+declare const TypeProperty: unique symbol;
+export declare abstract class ARC4Encoded implements BytesBacked {
+    abstract [TypeProperty]?: string;
     get bytes(): bytes;
-    equals(other: this): boolean;
 }
 export declare class Str extends ARC4Encoded {
     #private;
-    __type?: 'arc4.Str';
+    [TypeProperty]?: 'arc4.Str';
     constructor(s?: StringCompat);
     get native(): string;
 }
 export declare class UintN<N extends BitSize> extends ARC4Encoded {
-    __type?: `arc4.UintN<${N}>`;
+    [TypeProperty]?: `arc4.UintN<${N}>`;
     constructor(v?: CompatForArc4Int<N>);
     get native(): NativeForArc4Int<N>;
 }
+export declare class Byte extends UintN<8> {
+}
+export declare class UintN8 extends UintN<8> {
+}
+export declare class UintN16 extends UintN<16> {
+}
+export declare class UintN32 extends UintN<32> {
+}
+export declare class UintN64 extends UintN<64> {
+}
+export declare class UintN128 extends UintN<128> {
+}
+export declare class UintN256 extends UintN<256> {
+}
 export declare class UFixedNxM<N extends BitSize, M extends number> extends ARC4Encoded {
-    __type?: `arc4.UFixedNxM<${N}x${M}>`;
-    constructor(v: `${number}.${number}`, n?: N, m?: M);
+    [TypeProperty]?: `arc4.UFixedNxM<${N}x${M}>`;
+    constructor(v: `${number}.${number}`);
     get native(): NativeForArc4Int<N>;
 }
-export declare class Byte extends UintN<8> {
-    constructor(v?: Uint64Compat);
-}
-export declare class Bool {
-    #private;
-    __type?: `arc4.Bool`;
+export declare class Bool extends ARC4Encoded {
+    [TypeProperty]?: `arc4.Bool`;
     constructor(v?: boolean);
     get native(): boolean;
 }
 declare abstract class Arc4ReadonlyArray<TItem extends ARC4Encoded> extends ARC4Encoded {
-    protected items: TItem[];
-    protected constructor(items: TItem[]);
+    protected constructor();
     /**
      * Returns the current length of this array
      */
@@ -65,7 +76,7 @@ declare abstract class Arc4ReadonlyArray<TItem extends ARC4Encoded> extends ARC4
     [index: uint64]: TItem;
 }
 export declare class StaticArray<TItem extends ARC4Encoded, TLength extends number> extends Arc4ReadonlyArray<TItem> {
-    __type?: `arc4.StaticArray<${TItem['__type']}, ${TLength}>`;
+    [TypeProperty]?: `arc4.StaticArray<${TItem[typeof TypeProperty]}, ${TLength}>`;
     constructor();
     constructor(...items: TItem[] & {
         length: TLength;
@@ -74,7 +85,7 @@ export declare class StaticArray<TItem extends ARC4Encoded, TLength extends numb
     copy(): StaticArray<TItem, TLength>;
 }
 export declare class DynamicArray<TItem extends ARC4Encoded> extends Arc4ReadonlyArray<TItem> {
-    __type?: `arc4.DynamicArray<${TItem['__type']}>`;
+    [TypeProperty]?: `arc4.DynamicArray<${TItem[typeof TypeProperty]}>`;
     constructor(...items: TItem[]);
     /**
      * Push a number of items into this array
@@ -87,24 +98,50 @@ export declare class DynamicArray<TItem extends ARC4Encoded> extends Arc4Readonl
     pop(): TItem;
     copy(): DynamicArray<TItem>;
 }
-type ExpandTupleType<T extends ARC4Encoded[]> = T extends [infer T1 extends ARC4Encoded, ...infer TRest extends ARC4Encoded[]] ? TRest extends [] ? `${T1['__type']}` : `${T1['__type']},${ExpandTupleType<TRest>}` : '';
+type ExpandTupleType<T extends ARC4Encoded[]> = T extends [infer T1 extends ARC4Encoded, ...infer TRest extends ARC4Encoded[]] ? TRest extends [] ? `${T1[typeof TypeProperty]}` : `${T1[typeof TypeProperty]},${ExpandTupleType<TRest>}` : '';
 export declare class Tuple<TTuple extends [ARC4Encoded, ...ARC4Encoded[]]> extends ARC4Encoded {
-    #private;
-    __type?: `arc4.Tuple<${ExpandTupleType<TTuple>}>`;
+    [TypeProperty]?: `arc4.Tuple<${ExpandTupleType<TTuple>}>`;
     constructor(...items: TTuple);
     at<TIndex extends keyof TTuple>(index: TIndex): TTuple[TIndex];
     get length(): TTuple['length'] & uint64;
     get native(): TTuple;
 }
 export declare class Address extends Arc4ReadonlyArray<Byte> {
-    __type?: `arc4.Address`;
+    [TypeProperty]?: `arc4.Address`;
     constructor(value?: Account | string | bytes);
     get native(): Account;
 }
 type StructConstraint = Record<string, ARC4Encoded>;
 declare class StructBase extends ARC4Encoded {
-    __type: string;
+    [TypeProperty]: string;
 }
 type StructConstructor = new <T extends StructConstraint>(initial: T) => StructBase & T;
 export declare const Struct: StructConstructor;
+export declare class DynamicBytes extends Arc4ReadonlyArray<Byte> {
+    [TypeProperty]?: `arc4.DynamicBytes`;
+    constructor(value?: bytes | string);
+    get native(): bytes;
+}
+export declare class StaticBytes<TLength extends number = 0> extends Arc4ReadonlyArray<Byte> {
+    [TypeProperty]?: `arc4.StaticBytes<${TLength}>`;
+    constructor(value?: bytes | string);
+    get native(): bytes;
+}
+/**
+ * Interpret the provided bytes as an ARC4 encoded type with no validation
+ * @param bytes An arc4 encoded bytes value
+ * @param prefix The prefix (if any), present in the bytes value. This prefix will be validated and removed
+ */
+export declare function interpretAsArc4<T extends ARC4Encoded>(bytes: BytesCompat, prefix?: 'none' | 'log'): T;
+/**
+ * Decode the provided bytes to a native Algorand TypeScript value
+ * @param bytes An arc4 encoded bytes value
+ * @param prefix The prefix (if any), present in the bytes value. This prefix will be validated and removed
+ */
+export declare function decodeArc4<T>(bytes: BytesCompat, prefix?: 'none' | 'log'): T;
+/**
+ * Encode the provided Algorand TypeScript value as ARC4 bytes
+ * @param value Any native Algorand TypeScript value with a supported ARC4 encoding
+ */
+export declare function encodeArc4<T>(value: T): bytes;
 export {};

package/arc4/index.d.ts

@@ -1,4 +1,5 @@
 import { BaseContract } from '../base-contract';
+import { bytes } from '../primitives';
 import { DeliberateAny } from '../typescript-helpers';
 export * from './encoded-types';
 export declare class Contract extends BaseContract {
@@ -55,3 +56,10 @@ export type BareMethodConfig = {
     onCreate?: CreateOptions;
 };
 export declare function baremethod<TContract extends Contract>(config?: BareMethodConfig): <TArgs extends DeliberateAny[], TReturn>(target: (this: TContract, ...args: TArgs) => TReturn, ctx: ClassMethodDecoratorContext<TContract>) => (this: TContract, ...args: TArgs) => TReturn;
+/**
+ * Returns the ARC4 method selector for a given ARC4 method signature. The method selector is the first
+ * 4 bytes of the SHA512/256 hash of the method signature.
+ * @param methodSignature An ARC4 method signature. Eg. `hello(string)string`. Must be a compile time constant.
+ * @returns The ARC4 method selector. Eg. `02BECE11`
+ */
+export declare function methodSelector(methodSignature: string): bytes;

package/arc4/index.mjs

@@ -1,4 +1,4 @@
-export { x as Address, v as Bool, t as Byte, C as Contract, D as DynamicArray, o as OnCompleteAction, w as StaticArray, S as Str, y as Struct, T as Tuple, s as UFixedNxM, r as UintN, g as abimethod, q as baremethod } from '../index-DaaqFl7S.js';
+export { h as ARC4Encoded, x as Address, v as Bool, k as Byte, C as Contract, D as DynamicArray, z as DynamicBytes, O as OnCompleteAction, w as StaticArray, E as StaticBytes, S as Str, y as Struct, T as Tuple, u as UFixedNxM, j as UintN, r as UintN128, n as UintN16, s as UintN256, o as UintN32, q as UintN64, l as UintN8, c as abimethod, g as baremethod, G as decodeArc4, H as encodeArc4, F as interpretAsArc4, m as methodSelector } from '../index-BD1amocx.js';
 import '../execution-context-BznYSiE4.js';
 import 'node:buffer';
 import 'node:util';

package/compiled.d.ts

@@ -0,0 +1,108 @@
+import { BaseContract } from './base-contract';
+import { LogicSig } from './logic-sig';
+import { bytes, uint64 } from './primitives';
+import { Account } from './reference';
+import { ConstructorFor, DeliberateAny } from './typescript-helpers';
+/**
+ * Provides compiled programs and state allocation values for a Contract. Created by calling `compile(ExampleContractType)`
+ */
+export type CompiledContract = {
+    /**
+     * Approval program pages for a contract, after template variables have been replaced and compiled to AVM bytecode
+     */
+    approvalProgram: [bytes, bytes];
+    /**
+     * Clear state program pages for a contract, after template variables have been replaced and compiled to AVM bytecode
+     */
+    clearStateProgram: [bytes, bytes];
+    /**
+     * By default, provides extra program pages required based on approval and clear state program size, can be overridden when calling `compile(ExampleContractType, { extraProgramPages: ... })`
+     */
+    extraProgramPages: uint64;
+    /**
+     * By default, provides global num uints based on contract state totals, can be overridden when calling `compile(ExampleContractType, { globalUints: ... })`
+     */
+    globalUints: uint64;
+    /**
+     * By default, provides global num bytes based on contract state totals, can be overridden when calling `compile(ExampleContractType, { globalBytes: ... })`
+     */
+    globalBytes: uint64;
+    /**
+     * By default, provides local num uints based on contract state totals, can be overridden when calling `compile(ExampleContractType, { localUints: ... })`
+     */
+    localUints: uint64;
+    /**
+     * By default, provides local num bytes based on contract state totals, can be overridden  when calling `compile(ExampleContractType, { localBytes: ... })`
+     */
+    localBytes: uint64;
+};
+/**
+ * Provides account for a Logic Signature. Created by calling `compile(LogicSigType)`
+ */
+export type CompiledLogicSig = {
+    /**
+     * Address of a logic sig program, after template variables have been replaced and compiled to AVM bytecode
+     */
+    account: Account;
+};
+/**
+ * Options for compiling a contract
+ */
+type CompileContractOptions = {
+    /**
+     * Number of extra program pages, defaults to minimum required for contract
+     */
+    extraProgramPages?: uint64;
+    /**
+     * Number of global uint64s, defaults to value defined for contract
+     */
+    globalUints?: uint64;
+    /**
+     * Number of global bytes, defaults to value defined for contract
+     */
+    globalBytes?: uint64;
+    /**
+     * Number of local uint64s, defaults to value defined for contract
+     */
+    localUints?: uint64;
+    /**
+     * Number of local bytes, defaults to value defined for contract
+     */
+    localBytes?: uint64;
+    /**
+     * Template variables to substitute into the contract, key should be without the prefix, must evaluate to a compile time constant
+     * and match the type of the template var declaration
+     */
+    templateVars?: Record<string, DeliberateAny>;
+    /**
+     * Prefix to add to provided template vars, defaults to the prefix supplied on command line (which defaults to TMPL_)
+     */
+    templateVarsPrefix?: string;
+};
+/**
+ * Options for compiling a logic signature
+ */
+type CompileLogicSigOptions = {
+    /**
+     * Template variables to substitute into the contract, key should be without the prefix, must evaluate to a compile time constant
+     * and match the type of the template var declaration
+     */
+    templateVars?: Record<string, DeliberateAny>;
+    /**
+     * Prefix to add to provided template vars, defaults to the prefix supplied on command line (which defaults to TMPL_)
+     */
+    templateVarsPrefix?: string;
+};
+/**
+ * Compile a contract and return the resulting byte code for approval and clear state programs.
+ * @param contract The contract class to compile
+ * @param options Options for compiling the contract
+ */
+export declare function compile(contract: ConstructorFor<BaseContract>, options?: CompileContractOptions): CompiledContract;
+/**
+ * Compile a logic signature and return an account ready for signing transactions.
+ * @param logicSig The logic sig class to compile
+ * @param options Options for compiling the logic sig
+ */
+export declare function compile(logicSig: ConstructorFor<LogicSig>, options?: CompileLogicSigOptions): CompiledLogicSig;
+export {};

package/execution-context-BznYSiE4.js.map

@@ -1 +1 @@
-{"version":3,"file":"execution-context-BznYSiE4.js","sources":["../src/execution-context.ts"],"sourcesContent":["import { Box, BoxMap, BoxRef, Contract, GlobalState, gtxn, itxn, LocalState } from '.'\nimport { AbiMethodConfig, BareMethodConfig } from './arc4'\nimport { OpsNamespace } from './op-types'\nimport { bytes, uint64 } from './primitives'\nimport { Account, Application, Asset } from './reference'\n\nexport type ExecutionContext = {\n  log(value: bytes): void\n  application(id?: uint64): Application\n  asset(id?: uint64): Asset\n  account(address?: bytes): Account\n  op: Partial<OpsNamespace>\n  abiMetadata: {\n    captureMethodConfig<T extends Contract>(contract: T, methodName: string, config?: AbiMethodConfig<T> | BareMethodConfig): void\n  }\n  gtxn: {\n    Transaction: typeof gtxn.Transaction\n    PaymentTxn: typeof gtxn.PaymentTxn\n    KeyRegistrationTxn: typeof gtxn.KeyRegistrationTxn\n    AssetConfigTxn: typeof gtxn.AssetConfigTxn\n    AssetTransferTxn: typeof gtxn.AssetTransferTxn\n    AssetFreezeTxn: typeof gtxn.AssetFreezeTxn\n    ApplicationTxn: typeof gtxn.ApplicationTxn\n  }\n  itxn: {\n    submitGroup: typeof itxn.submitGroup\n    payment: typeof itxn.payment\n    keyRegistration: typeof itxn.keyRegistration\n    assetConfig: typeof itxn.assetConfig\n    assetTransfer: typeof itxn.assetTransfer\n    assetFreeze: typeof itxn.assetFreeze\n    applicationCall: typeof itxn.applicationCall\n  }\n  state: {\n    GlobalState: typeof GlobalState\n    LocalState: typeof LocalState\n    Box: typeof Box\n    BoxMap: typeof BoxMap\n    BoxRef: typeof BoxRef\n  }\n}\n\ndeclare global {\n  // eslint-disable-next-line no-var\n  var puyaTsExecutionContext: ExecutionContext | undefined\n}\n\nexport const ctxMgr = {\n  set instance(ctx: ExecutionContext) {\n    const instance = global.puyaTsExecutionContext\n    if (instance != undefined) throw new Error('Execution context has already been set')\n    global.puyaTsExecutionContext = ctx\n  },\n  get instance() {\n    const instance = global.puyaTsExecutionContext\n    if (instance == undefined) throw new Error('No execution context has been set')\n    return instance\n  },\n  reset() {\n    global.puyaTsExecutionContext = undefined\n  },\n}\n"],"names":[],"mappings":"AA+Ca,MAAA,MAAM,GAAG;IACpB,IAAI,QAAQ,CAAC,GAAqB,EAAA;AAChC,QAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,sBAAsB,CAAA;QAC9C,IAAI,QAAQ,IAAI,SAAS;AAAE,YAAA,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;AACpF,QAAA,MAAM,CAAC,sBAAsB,GAAG,GAAG,CAAA;KACpC;AACD,IAAA,IAAI,QAAQ,GAAA;AACV,QAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,sBAAsB,CAAA;QAC9C,IAAI,QAAQ,IAAI,SAAS;AAAE,YAAA,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAA;AAC/E,QAAA,OAAO,QAAQ,CAAA;KAChB;IACD,KAAK,GAAA;AACH,QAAA,MAAM,CAAC,sBAAsB,GAAG,SAAS,CAAA;KAC1C;;;;;"}
+{"version":3,"file":"execution-context-BznYSiE4.js","sources":["../src/execution-context.ts"],"sourcesContent":["import { Box, BoxMap, BoxRef, Contract, GlobalState, gtxn, itxn, LocalState } from '.'\nimport { AbiMethodConfig, BareMethodConfig } from './arc4'\nimport { OpsNamespace } from './op-types'\nimport { bytes, uint64 } from './primitives'\nimport { Account, Application, Asset } from './reference'\n\nexport type ExecutionContext = {\n  log(value: bytes): void\n  application(id?: uint64): Application\n  asset(id?: uint64): Asset\n  account(address?: bytes): Account\n  op: Partial<OpsNamespace>\n  abiMetadata: {\n    captureMethodConfig<T extends Contract>(contract: T, methodName: string, config?: AbiMethodConfig<T> | BareMethodConfig): void\n  }\n  gtxn: {\n    Transaction: typeof gtxn.Transaction\n    PaymentTxn: typeof gtxn.PaymentTxn\n    KeyRegistrationTxn: typeof gtxn.KeyRegistrationTxn\n    AssetConfigTxn: typeof gtxn.AssetConfigTxn\n    AssetTransferTxn: typeof gtxn.AssetTransferTxn\n    AssetFreezeTxn: typeof gtxn.AssetFreezeTxn\n    ApplicationTxn: typeof gtxn.ApplicationTxn\n  }\n  itxn: {\n    submitGroup: typeof itxn.submitGroup\n    payment: typeof itxn.payment\n    keyRegistration: typeof itxn.keyRegistration\n    assetConfig: typeof itxn.assetConfig\n    assetTransfer: typeof itxn.assetTransfer\n    assetFreeze: typeof itxn.assetFreeze\n    applicationCall: typeof itxn.applicationCall\n  }\n  state: {\n    GlobalState: typeof GlobalState\n    LocalState: typeof LocalState\n    Box: typeof Box\n    BoxMap: typeof BoxMap\n    BoxRef: typeof BoxRef\n  }\n}\n\ndeclare global {\n  // eslint-disable-next-line no-var\n  var puyaTsExecutionContext: ExecutionContext | undefined\n}\n\nexport const ctxMgr = {\n  set instance(ctx: ExecutionContext) {\n    const instance = global.puyaTsExecutionContext\n    if (instance != undefined) throw new Error('Execution context has already been set')\n    global.puyaTsExecutionContext = ctx\n  },\n  get instance() {\n    const instance = global.puyaTsExecutionContext\n    if (instance == undefined) throw new Error('No execution context has been set')\n    return instance\n  },\n  reset() {\n    global.puyaTsExecutionContext = undefined\n  },\n}\n"],"names":[],"mappings":"AA+Ca,MAAA,MAAM,GAAG;IACpB,IAAI,QAAQ,CAAC,GAAqB,EAAA;AAChC,QAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,sBAAsB;QAC9C,IAAI,QAAQ,IAAI,SAAS;AAAE,YAAA,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC;AACpF,QAAA,MAAM,CAAC,sBAAsB,GAAG,GAAG;KACpC;AACD,IAAA,IAAI,QAAQ,GAAA;AACV,QAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,sBAAsB;QAC9C,IAAI,QAAQ,IAAI,SAAS;AAAE,YAAA,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC;AAC/E,QAAA,OAAO,QAAQ;KAChB;IACD,KAAK,GAAA;AACH,QAAA,MAAM,CAAC,sBAAsB,GAAG,SAAS;KAC1C;;;;;"}

package/impl/errors.d.ts

@@ -27,3 +27,10 @@ export declare class CodeError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
 export declare function codeError(message: string): never;
+/**
+ * This error can be used in stub implementations that are expected to be overridden
+ * by the testing framework
+ */
+export declare class NoImplementation extends Error {
+    constructor();
+}

package/impl/primitives.d.ts

@@ -52,7 +52,7 @@ export declare class BytesCls extends AlgoTsPrimitiveCls {
     get length(): Uint64Cls;
     toBytes(): BytesCls;
     at(i: StubUint64Compat): BytesCls;
-    slice(start: undefined | StubUint64Compat, end: undefined | StubUint64Compat): BytesCls;
+    slice(start?: StubUint64Compat, end?: StubUint64Compat): BytesCls;
     concat(other: StubBytesCompat): BytesCls;
     bitwiseAnd(other: StubBytesCompat): BytesCls;
     bitwiseOr(other: StubBytesCompat): BytesCls;