@goplausible/algorand-mcp 3.0.7

package/dist/resources/knowledge/taxonomy/tealscript:guides_math.md

@@ -0,0 +1,54 @@
+---
+title: Math
+---
+
+## Truncation
+
+It is important to note TEALScript only works with unsigned integers. This means that there are no fractional values or negative numbers. The AVM, and thus TEALScript, will always truncate the result of division operations. For example, `99 / 100 === 0` will be true.
+
+## Opcode Cost
+
+Performing math operations with a integer width more than 64 bits can be up to **20x more expensive** (see table below). As such, if you find yourself running out of opcode budget, it is best to manually cast to `uint64` and then cast back when possible.
+
+### Opcode Costs
+
+| Bit Width | Operations | Cost |
+| --------- | ---------- | ---- |
+| `<= 64`    | `+` or `-` | 1    |
+| `<= 64`     | `*` or `/` | 1    |
+| `> 64`      | `+` or `-` | 10   |
+| `> 64`      | `*` or `/` | 20   |
+
+## Overflows
+
+### Runtime
+
+During runtime, TEALscript will not perform overflow checks. This means you will only encouter an overflow panic when performing math operations and the following max values are exceeded
+
+| Bit Width | Max Value |
+| --------- | --------- |
+| `<= 64`     | `2^64 - 1`  |
+| `> 64`      | `2^512 - 1` |
+
+### Encoding
+
+Prior to encoding a number, TEALScript will ensure that the value does not exceed the respective max value. For example, it will check a `uint8` is not more than `2^8 - 1` prior to encoding it.
+
+### Underflows
+
+Any operation that results in a value less than 0 will cause a panic in the AVM.
+
+## Wide Ratio
+
+A common operation in contracts is to perform division to get the ratio between two numbers (ie. in a liquidty pool). If the numerator and/or divisor includes multiplication of `uint64` values, they might be larger than `uint64` (thus cause an overflow panic) even if the final result of the division would fit in a `uint64`. To handle such cases, TEALScript implements a global function called `wideRatio`. 
+
+### Example
+
+```ts
+  private tokensToSwap(inAmount: uint64, inSupply: uint64, outSupply: uint64): uint64 {
+    const factor = SCALE - FEE;
+    return wideRatio([inAmount, factor, outSupply], [inSupply * SCALE + inAmount * factor]);
+  }
+```
+
+A full AMM example can be found [here](https://github.com/algorandfoundation/TEALScript/blob/dev/examples/amm/amm.algo.ts).

package/dist/resources/knowledge/taxonomy/tealscript:guides_methods.md

@@ -0,0 +1,85 @@
+---
+title: Defining Methods
+---
+
+## Typing
+All method arguments MUST have a type and all methods MUST have an explicit return type. 
+
+### Examples
+
+#### Valid
+```ts
+add(a: uint64, b: uint64): uint64 {
+  return a + b
+}
+```
+
+#### Invalid
+
+```ts
+add(a: uint64, b: uint64) { // missing return type
+  return a + b
+}
+```
+
+```ts
+add(a, b: uint64): uint64 { // missing argument type
+  return a + b
+}
+```
+
+## ABI Methods
+All methods defined in your contract will be routed as ABI methods, unless they have the `private` keyword. This means they will be exposed in the ABI and Application Spec generated by TEALScript.
+
+## Private Subroutines
+A method defined with the `private` keyword will only be accessible within the contract itself via a subroutine. This means other contracts or end-users cannot call this method directly and it will not be exposed in the ABI or Application Spec.
+
+### Example
+In this example, there is a single public ABI method `doMath` which will then call the `add` or `subtract` subroutines depending on the method given. `doMath` is the only method that is externally callable.
+
+```ts
+class Calculator extends Contract {
+  /**
+   * Calculates the sum of two numbers
+   *
+   * @param a
+   * @param b
+   * @returns The sum of a and b
+   */
+  private getSum(a: uint64, b: uint64): uint64 {
+    return a + b;
+  }
+
+  /**
+   * Calculates the difference between two numbers
+   *
+   * @param a
+   * @param b
+   * @returns The difference between a and b.
+   */
+  private getDifference(a: uint64, b: uint64): uint64 {
+    return a >= b ? a - b : b - a;
+  }
+
+  /**
+   * A method that takes two numbers and does either addition or subtraction
+   *
+   * @param a The first number
+   * @param b The second number
+   * @param operation The operation to perform. Can be either 'sum' or 'difference'
+   *
+   * @returns The result of the operation
+   */
+  doMath(a: uint64, b: uint64, operation: string): uint64 {
+    let result: uint64;
+
+    if (operation === 'sum') {
+      result = this.getSum(a, b);
+    } else if (operation === 'difference') {
+      result = this.getDifference(a, b);
+    } else throw Error('Invalid operation');
+
+    return result;
+  }
+}
+```

package/dist/resources/knowledge/taxonomy/tealscript:guides_multiple_contracts.md

@@ -0,0 +1,92 @@
+---
+title: Multiple Contracts
+---
+
+## Inheritance
+
+You can inherit another Contract or LogicSig in order to inherit all of the class properties (state, events, scratch, etc.) and methods.
+
+```ts
+export class BaseContract extends Contract {
+    favoriteNumber = GlobalStateKey<uint64>()
+    
+    private setNumber(n: uint64): void {
+        this.favoriteNumber.value = n
+    }
+}
+
+export class AnotherContract extends BaseContract {
+    checkNumber(): void {
+        this.setNumber(42)
+        assert(this.favoriteNumber.value === 42)
+    }
+}
+```
+
+## Importing and Inheritance
+
+TEALScript supports importing any `Contract`, `LogicSig`, const, or type from another TEALScript file. 
+
+```ts
+// base_contract.algo.ts
+export class BaseContract extends Contract {
+    favoriteNumber = GlobalStateKey<uint64>()
+    
+    private setNumber(n: uint64): void {
+        this.favoriteNumber.value = n
+    }
+}
+```
+
+```ts
+// another_contract.algo.ts
+import { BaseContract } from './base_contract.algo.ts'
+
+export class AnotherContract extends BaseContract {
+    checkNumber(): void {
+        this.setNumber(42)
+        assert(this.favoriteNumber.value === 42)
+    }
+}
+```
+
+## App Programs and Schema
+
+To access the program or schema of another TEALScript app you can use the `.approvalProgram()`. `.clearProgram()`, or `.schema` static methods.
+
+```ts
+class TheApp extends Contract {
+  favoriteNumber = GlobalStateKey<uint64>();
+
+  createApplication(): void {
+    this.favoriteNumber.value = 42;
+  }
+}
+
+class TheFactory extends Contract {
+  createTheApp(): void {
+    sendMethodCall<[], void>({
+      name: 'createApplication',
+      approvalProgram: TheApp.approvalProgram(),
+      clearStateProgram: TheApp.clearProgram(),
+      globalNumUint: TheApp.schema.global.numUint,
+    });
+  }
+}
+```
+
+## Logic Signature Address and Program
+
+```ts
+class TheLsig extends LogicSig {
+  logic(): void {
+    assert(this.txn.fee === 0);
+  }
+}
+class TheApp extends Contract {
+  createApplication(): void {
+    assert(TheLsig.address().balance >= 10_000_000);
+    log(TheLsig.program());
+  }
+}
+```

package/dist/resources/knowledge/taxonomy/tealscript:guides_pyteal.md

@@ -0,0 +1,35 @@
+---
+title: PyTeal Migration
+---
+
+## Classes and Functions
+| PyTeal       | TEALScript                                  |
+| ------------ | ------------------------------------------- |
+| `Txn`        | `this.txn`                                  |
+| `Global`     | `globals`                                   |
+| `Itxn`       | `this.itxn`                                 |
+| `Assert`     | `assert`                                    |
+| `NamedTuple` | See Objects section [here](types/tuples.md) |
+| `Gtxn`       | `this.txnGroup`                             |
+| `precompile` | See [multiple contracts](./multiple_contracts.md) |
+
+## Maybe Values
+
+In TEALScript, there is no concept of `MaybeValue`. For every opcode that would return a `MaybeValue` in PyTeal, TEALScript exposes two methods. One to get the value and one to get whether the value exists. Simply getting the value will always assert that the value exists. For boxes, the means needing to call `exist` prior to `get`. Otherwise there will be two methods, with one prefixed with `has` to indicate it is getting whether the value exists or not.
+
+### Example
+
+```ts
+class BalanceApp extends Contract {
+    counters = BoxMap<Address, uint64>();
+
+    getBalance(addr: Address): void {
+        // Set balance to 0 if addr balance doesn't exist
+        const balance = addr.hasBalance ? addr.balance : 0
+
+        // set counter to 1 if it doesn't already exist
+        const newCounter = this.counters(addr).exists ? this.counters(addr).value + 1 : 1
+        this.counters(addr).value = newCounter
+    }
+}
+```

package/dist/resources/knowledge/taxonomy/tealscript:guides_storage.md

@@ -0,0 +1,110 @@
+---
+title: On-Chain Storage
+---
+
+There are three storage types available for Algorand smart contracts: global, local, and box. To read more about these storage types, you can go to [this page](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/state/) on the developer portal.
+
+In general, you want to use global storage for small values (< 128 byte) when you have a known amount of key/value pairs and otherwise use box storage. There are exceptions of course when local storage makes sense, but most developers should start with global and box storage.
+
+For each storage type, there are two classess in TEALScript for interacting with contract state `Key` and `Map`. Classes ending with `Key` point to a single key in storage and `Map` is a mapping of an undefined amount of keys to their respective values.
+
+## Key Declaration
+
+All `Key` functions `GlobalStateKey`, `BoxKey`, `LocalStateKey`) are generic functions with one type argument that corresponds to the type of the value held in the respective value. 
+
+These functions all take an optional argument `key`. By default, the property name will be used for the on-chain key name. The `key` property, however, can be used to override what value is used as the on-chain key. This is paticularly useful when you want small keys on-chain but longer more-descriptive keys in TEALScript. If you want the key to be a non-string value, use `Map`s
+
+### Examples
+
+#### Key Declaration
+
+```ts
+class MyApp extends Contract {
+    someKey = GlobalStateKey<string>()
+
+    setSomeKey(value: string): void {
+        this.someKey.value = value // On chain: "someKey" now contains value
+    }
+}
+```
+
+#### Modified On-Chain Key
+
+```ts
+class MyApp extends Contract {
+    someKey = GlobalStateKey<string>({ key: 'sk' })
+
+    setSomeKey(value: string): void {
+        this.someKey.value = value // On chain: "sk" now contains value
+    }
+}
+```
+
+## Map Declaration
+
+All `Map` functions (`GlobalStateMap`, `BoxMap`,  `LocalStateMap`) are generic functions with two type arguments that corresponds to the type of the key and the type of the value, respectively. 
+
+These functions all take an optional argument `prefix`. The value given to `prefix` is a string that will prefix each key accessed via this `Map`. This is useful when you have two different maps that might have the same key type. The compiler will throw an error if two `Map`s of the same storage type have the same key type and no prefix.
+
+#### Map Declaration
+
+```ts
+class MyApp extends Contract {
+    favoriteColor = BoxMap<Address, string>()
+
+    setColor(color: string): void {
+        this.favoriteColor(this.txn.sender).value = color // on chain: sender's address now points to their favorite color
+    }
+}
+```
+
+#### Map Prefix Declaration
+
+```ts
+class MyApp extends Contract {
+    favoriteColor = BoxMap<Address, string>({ prefix: 'c' })
+    favoriteNumber = BoxMap<Address, string>({ prefix: 'n' })
+
+    setColor(color: string): void {
+        this.favoriteColor(this.txn.sender).value = color // on chain: ("c" + sender's address) now points to their favorite color
+    }
+
+    setNumber(number: uint64): void {
+        this.favoriteNumber(this.txn.sender).value = number // on chain: ("n" + sender's address) now points to their favorite number
+    }
+}
+```
+
+#### Incorrect: Overlapping Key Types
+
+```ts
+class MyApp extends Contract {
+    favoriteColor = BoxMap<Address, string>() // ERROR: same key type as favoriteNumber and no prefix
+    favoriteNumber = BoxMap<Address, string>() // ERROR: same key type as favoriteColor and no prefix
+}
+```
+
+## Box defaultSize Parameter
+
+`BoxKey` and `BoxMap` have an additional option that is not applicable to global or local storage.
+
+`dynamicSize` is an optional parameter that indicates whether TEALScript should call `box_del` before each `box_put`. By default, this value will be false when the value type is static and true when the value type is dynamic. This means in most cases, you shouldn't need to manually set this parameter unless you want to manually manage box resizing via `.delete()`
+
+## StateMap maxKeys Parameter
+
+`GlobalStateMap` and `LocalStateMap` have an additional parameter `maxKeys`.
+
+`maxKeys` is a required parameter that indicates how many keys should be reserved for this map.
+
+```ts
+// Reserve 3 keys for this map
+class MyApp extends Contract {
+  data = GlobalStateMap<bytes, bytes>({ maxKeys: 3 })
+  
+  createApplication(){
+    this.data('name').value = 'MyApp'
+    this.data('version').value = '1.0.0'
+    this.data('author').value = 'Me'
+  }
+}
+```

package/dist/resources/knowledge/taxonomy/tealscript:tests_test_package_README.md

@@ -0,0 +1 @@
+This is a simple package that is used to test importing things from npm packages.

package/dist/resources/knowledge/taxonomy/tealscript:tutorials_Hello World_0001-intro.md

@@ -0,0 +1,9 @@
+---
+title: 1. Intro and Prerequisites
+---
+
+This tutorial will go over the basics of how to use Algokit to initialize a TEALScript project and modify it to create and test a hello world contract.
+
+## Prerequisites 
+
+Before beginning, make sure you have Algokit installed. Go [here](https://developer.algorand.org/docs/get-started/algokit/) for a quick start guide. 

package/dist/resources/knowledge/taxonomy/tealscript:tutorials_Hello World_0002-init.md

@@ -0,0 +1,50 @@
+---
+title: "2. Initializing The Template"
+---
+
+## Algokit Init
+
+To get started, run the following Algokit command to initialize a template:
+
+```bash
+$ algokit init --template tealscript --name hello_world
+```
+
+For this tutorial, I have chosen the name `hello_world` for my project, which will be reflected throughout the rest of this content. If you choose a different name, some parts might be different for you.
+
+## Template Layout
+
+After the init command finishes, you should have the following directory structure:
+
+```
+.
+├── README.md
+├── __test__
+│   └── hello_world.test.ts
+├── contracts
+│   ├── artifacts
+│   │   └── components
+│   ├── clients
+│   └── hello_world.algo.ts
+├── jest.config.js
+├── package-lock.json
+├── package.json
+└── tsconfig.json
+```
+
+If you have experience with web development, most of this should look familiar. Below are the key directory and files
+
+### __test__/
+#### hello_world.test.ts
+
+`hello_world.test.ts` is a test for our contract written with Jest. This tutorial won't go too in-depth into testing, but it is a good example on how client-side contract interaction works
+
+### contracts/
+
+#### hello_world.algo.ts
+
+`hello_world.algo.ts` is the most important file in the template. This is where our contract logic is defined. You might notice that this file has a `.ts` extension, but also an `.algo.ts`. The `.algo.` is there solely to help tools like ESLint and TypeScript differentiate between regular TypeScript files and TEALScript files. The TEALScript compiler does not require the `.algo.ts` extension but it is highly recommended to use. Any files without `.algo.ts` extension in this template may be mistaken for TypeScript files that should be compiled into JavaScript (instead of TEAL), which may cause errors.
+
+#### artifacts/
+
+`artifacts/` is the directory where all the files generated by the TEALScript compiler and algokit will go. We will go further in-depth on these artifacts in the next step of this tutorial.

package/dist/resources/knowledge/taxonomy/tealscript:tutorials_Hello World_0003-contract.md

@@ -0,0 +1,98 @@
+---
+title: "3. The Template Contract"
+---
+
+By default, the TEALScript template includes a very basic contract that performs some math operations. This page will breakdown the contract and explain what each of the components do and how TEALScript works. 
+
+
+## Import Contract
+
+```ts
+import { Contract } from '@algorandfoundation/tealscript';
+```
+
+Here we are simply importing `Contract` from the tealscript npm package. `Contract` is the most important class in TEALScript as every contract written in TEALScript must extend the `Contract` class. Code outside of the `Contract` superclass will not get compiled.
+
+## Class Definition
+
+```ts
+// eslint-disable-next-line no-unused-vars
+class HelloWorld extends Contract {
+```
+
+As mentioned above, every contract must extend `Contract`. You will also notice that there is the ESLint rule, `no-unused-vars` is disabled for this line. ESLint expects every class we define to be used in our codebase. Since we are developing a contract, however, we don't directly use this class in other TypeScript files, thus we expect it to be unused.
+
+## Private Methods
+
+```ts
+  /**
+   * Calculates the sum of two numbers
+   *
+   * @param a
+   * @param b
+   * @returns The sum of a and b
+   */
+  private getSum(a: uint64, b: uint64): uint64 {
+    return a + b;
+  }
+
+  /**
+   * Calculates the difference between two numbers
+   *
+   * @param a
+   * @param b
+   * @returns The difference between a and b.
+   */
+  private getDifference(a: uint64, b: uint64): uint64 {
+    return a >= b ? a - b : b - a;
+  }
+```
+
+In TypeScript, a private function is a function that can only be called internally by an instance of this class. The `private` keyword in TEALScript has a very similar meaning. If a method is `private`, then nobody can directly call the method. The only way to reach the logic defined in these methods is through a public method that explicitly calls them.
+
+The logic of these methods are rather simple. 
+
+### getSum
+
+Simply adds the two given numbers together/
+
+### getDifference
+
+Will get the difference of the two given numbers by subtracting the smaller one from the bigger one.
+
+## Public Method
+
+```ts
+  /**
+  * A method that takes two numbers and does either addition or subtraction
+  *
+  * @param a The first number
+  * @param b The second number
+  * @param operation The operation to perform. Can be either 'sum' or 'difference'
+  *
+  * @returns The result of the operation
+  */
+  doMath(a: uint64, b: uint64, operation: string): uint64 {
+    let result: uint64;
+
+    if (operation === 'sum') {
+      result = this.getSum(a, b);
+    } else if (operation === 'difference') {
+      result = this.getDifference(a, b);
+    } else throw Error('Invalid operation');
+
+    return result;
+  }
+```
+
+### doMath
+
+Because this function is public (there is no `private` keyword, thus it is implicitly public), any client on or off chain can call `doMath`. 
+
+As indicating by the TypeDoc comment, this function takes in two numbers and a string as an operation. The `operation` argument is used to determine whether `getSum` or `getDifferent` should be called.
+
+### Errors
+
+If the `operation` string is not an expected operation, the contract will throw an error.
+
+It should be noted that there is no concept of `try` in TEALScript. Errors are unrecoverable and will results in a failed transaction. On Algorand, failed transaction do not get charged a fee.

package/dist/resources/knowledge/taxonomy/tealscript:tutorials_Hello World_0004-artifacts.md

@@ -0,0 +1,59 @@
+---
+title: "4. Compilation Artifacts"
+---
+
+## Compiling
+
+To compile the `hello_world.algo.ts`, simply run `npm run build`. This will generate some artifacts under the `contracts/artifacts` directory
+
+
+## TEALScript Artifacts
+
+The `contracts/` directory will now look like the following. While you won't need to directly interact with most of these files, it's get to get a general understanding of what they do. Below are all the files generated by TEALScript.
+
+```
+contracts
+├── artifacts
+│   ├── HelloWorld.abi.json
+│   ├── HelloWorld.approval.teal
+│   ├── HelloWorld.clear.teal
+│   ├── HelloWorld.json
+│   ├── HelloWorld.src_map.json
+│   └── components
+├── clients
+│   └── HelloWorldClient.ts
+└── hello_world.algo.ts
+```
+
+### artifacts/HelloWorld.abi.json
+
+This is the ABI JSON description. In short, this file helps clients know what methods are availible and how to call them. You might also see that there are descriptions for our method and arguments. These descriptions were generated auotomatically via the TypeDoc comment. This means writing documentation for your contract methods not only helps you in your IDE, but it also helps potential callers of your contract understand how they should call it.
+
+### artifacts/HelloWorld.approval.teal
+
+This file is the low-level source code of our contract that is ultimately given to a node when deploying the contract. This file contains TEAL, which is a low-level language native to the Algorand blockchain. Luckily, you will not need to work with TEAL directly too often, but it's worthwhile to take a look at it to get a basic idea of how it works. Sometimes when debugging, you will need to look at the TEAL to truly understand what is happening.
+
+This file represents what we call the `approval program`, which is the code that executes when the contract is normally called.
+
+### artifacts/HelloWorld.clear.teal
+
+On Algorand, contracts actually have two pieces of source code. The `approval program` and the `clear program`. The `clear program` is only called when a user wants to clear their state from the contract. If that sounds distressing, don't worry, this tutorial will go more in depth about how this works and ways to control what can and can't be deleted.
+
+### artifacts/HelloWorld.json
+
+This is the applicaiton spec for our contract. Think of this file like an enhanced ABI file. It includes all of the information in the ABI JSON description while also providing even more information for clients, such as source code, state encoding, etc.
+
+## Algokit Generated Client
+
+### clients/HelloWorldClien.ts
+
+This is a client that was automatically generated by Algokit. If you look at what happens when `npm run build` runs, there are two commands:
+
+1. `tealscript contracts/hello_world.algo.ts contracts/artifacts`
+2. `algokitgen generate -a contracts/artifacts/HelloWorld.json -o contracts/clients/HelloWorldClient.ts`
+
+The first one is passing the contract to the TEALScript compiler and generated the aforementioned artifacts. 
+
+The second one is passing our appspec, `HelloWorld.json`, to algokit which then outputs an auto-generated client. This generated client is a TypeScript file that exports a class that can be used to interact with our contract. This client includes not only all of the public methods, but also things like contract state. 
+
+This client means we don't need to manually write boilerplate code for connecting our contract to our client which will be shown in the next step of this tutorial.

package/dist/resources/knowledge/taxonomy/tealscript:tutorials_Hello World_0005-hello.md

@@ -0,0 +1,35 @@
+---
+title: "5. Hello World Method"
+---
+
+For this tutorial, we are going to write a method and returns `"Hello, NAME"` with `NAME` being an argument to the method.
+
+## Modifying the Contract
+
+```ts
+import { Contract } from "@algorandfoundation/tealscript";
+
+// eslint-disable-next-line no-unused-vars
+class HelloWorld extends Contract {
+  /**
+   * @param name The name of the caller
+   *
+   * @returns A greeting string
+   */
+  hello(name: string): string {
+    return "Hello, " + name;
+  }
+}
+```
+
+## Compile New Contract
+
+To compile the contract, run `npm run build`. This should update all of the files in `contracts/artifacts` and `contracts/clients`
+
+## Template Literals
+
+It should be noted that TEALScript does not currently support string literals. For example, the following syntax is not yet supported: 
+
+```ts
+return `Hello, ${name}`
+```

package/dist/resources/knowledge/taxonomy/tealscript:tutorials_Hello World_0006-test.md

@@ -0,0 +1,30 @@
+---
+title: "6. Writing a Test"
+---
+
+Now we need to go `__test__/hello_world.test.ts` and modify our test to properly call our contract.
+
+We can do so by removing `test("sum")` and `test("difference")` and write our own test:
+
+```ts
+  test("helloWorld", async () => {
+    const message = await appClient.hello({ name: "AlgoDev" });
+    expect(message.return?.valueOf()).toBe("Hello, AlgoDev");
+  });
+```
+
+The important thing here is that `await appClient.doMath` was changed to `await appClient.hello` and the argument was changed to `{ name: "AlgoDev" }`. Finally, we changed the test to expect `"Hello, AlgoDev"` since the argument we passed in was `"AlgoDev"`.
+
+
+## Running The Test
+
+To run the test, run the script `npm run test`, which should show all tests passing:
+
+```bash
+ PASS  __test__/hello_world.test.ts
+  HelloWorld
+    ✓ helloWorld (766 ms)
+
+Test Suites: 1 passed, 1 total
+Tests:       1 passed, 1 total
+```