@goplausible/algorand-mcp 3.0.7

package/dist/resources/knowledge/taxonomy/developer:docs:details:dapps:smart-contracts:guidelines.md

@@ -0,0 +1,405 @@
+title: Modern guidelines for smart contracts and smart signatures on Algorand
+
+## Disclaimer
+
+The content provided here is not an exhaustive list of security considerations. Before deploying any application in production, it is strongly advised to get the contract audited by one more third-party security companies.
+
+## Use smart signatures very SPARINGLY
+
+Algorand supports two types of programs on the blockchain: **smart signatures** and **smart contracts**. Smart signatures themselves can be used both as **delegated (logic) signatures** or **contract account**.
+
+Most dApps should **only** use **smart contracts** and should **not** use any **smart signatures**. 
+
+See the [section "More about smart signatures vs smart contracts"](#more-about-smart-signatures-vs-smart-contracts) for additional details.
+
+!!! info
+    As in the section below, smart signatures were necessary in the past. If you see an example (on the [developer portal](https://developer.algorand.org) or anywhere else online) that uses smart signatures, please take some time to see if it can be migrated following the instructions below.
+
+
+## DO proper fee management
+
+### DO NOT hard-code 1,000 microAlgos as minimum fee
+
+The minimum fee per transaction is a consensus parameter. It **CAN** be changed over time. As such, **NEVER** hard-code its value anywhere.
+
+If you hard-code 1,000 microAlgos instead of using one of the method below, your smart contract or code will fail, if the minimum fee is increased.
+
+#### Get minimum fee in smart contract
+
+=== "PyTeal"
+    ```py
+    Global.min_txn_fee()
+    ```
+
+=== "TEAL"
+    ```teal
+    global MinTxnFee
+    ```
+
+#### Get minimum fee off-chain with SDK
+
+There are two options:
+
+* using SDK constants:
+
+=== "Python"
+    <!-- ===PYSDK_CONST_MIN_FEE=== -->
+	```python
+	from algosdk import constants
+	
+	print(constants.MIN_TXN_FEE)
+	```
+	[Snippet Source](https://github.com/algorand/py-algorand-sdk/blob/examples/examples/overview.py#L83-L86)
+    <!-- ===PYSDK_CONST_MIN_FEE=== -->
+
+=== "JavaScript"
+    <!-- ===JSSDK_CONST_MIN_FEE=== -->
+	```javascript
+	const minFee = algosdk.ALGORAND_MIN_TX_FEE;
+	```
+	[Snippet Source](https://github.com/algorand/js-algorand-sdk/blob/examples/examples/atomics.ts#L53-L54)
+    <!-- ===JSSDK_CONST_MIN_FEE=== -->
+
+=== "Java"
+    <!-- ===JAVASDK_CONST_MIN_FEE=== -->
+	```java
+	System.out.printf("Min fee from const: %d\n", Account.MIN_TX_FEE_UALGOS);
+	```
+	[Snippet Source](https://github.com/algorand/java-algorand-sdk/blob/examples/examples/src/main/java/com/algorand/examples/Overview.java#L70-L71)
+    <!-- ===JAVASDK_CONST_MIN_FEE=== -->
+    
+=== "Go"
+    <!-- ===GOSDK_CONST_MIN_FEE=== -->
+	```go
+	log.Printf("Min fee const: %d", transaction.MinTxnFee)
+	```
+	[Snippet Source](https://github.com/algorand/go-algorand-sdk/blob/examples/examples/overview/main.go#L101-L102)
+    <!-- ===GOSDK_CONST_MIN_FEE=== -->
+    
+* using an algod API:
+
+=== "Python"
+    <!-- ===PYSDK_SP_MIN_FEE=== -->
+	```python
+	suggested_params = algod_client.suggested_params()
+	print(suggested_params.min_fee)
+	```
+	[Snippet Source](https://github.com/algorand/py-algorand-sdk/blob/examples/examples/overview.py#L78-L80)
+    <!-- ===PYSDK_SP_MIN_FEE=== -->
+
+=== "JavaScript"
+    <!-- ===JSSDK_SP_MIN_FEE=== -->
+	```javascript
+	// Not supported because getTransactionParams erases the information
+	```
+	[Snippet Source](https://github.com/algorand/js-algorand-sdk/blob/examples/examples/atomics.ts#L63-L64)
+    <!-- ===JSSDK_SP_MIN_FEE=== -->
+
+=== "Java"
+    <!-- ===JAVASDK_SP_MIN_FEE=== -->
+	```java
+	Response<TransactionParametersResponse> tpr = algodClient.TransactionParams().execute();
+	TransactionParametersResponse sp = tpr.body();
+	System.out.printf("Min fee from suggested params: %d\n", sp.minFee);
+	```
+	[Snippet Source](https://github.com/algorand/java-algorand-sdk/blob/examples/examples/src/main/java/com/algorand/examples/Overview.java#L50-L53)
+    <!-- ===JAVASDK_SP_MIN_FEE=== -->
+    
+=== "Go"
+    <!-- ===GOSDK_SP_MIN_FEE=== -->
+	```go
+	suggestedParams, err := algodClient.SuggestedParams().Do(context.Background())
+	if err != nil {
+		log.Fatalf("failed to %s", err)
+	}
+	log.Printf("Min fee from suggested params: %d", suggestedParams.MinFee)
+	```
+	[Snippet Source](https://github.com/algorand/go-algorand-sdk/blob/examples/examples/overview/main.go#L93-L98)
+    <!-- ===GOSDK_SP_MIN_FEE=== -->
+
+### DO bound fees for smart signatures
+
+In most scenarios, if you are using smart signatures, the transaction fee should be constrained by the smart signature, otherwise an attacker may be able to replay/send transactions with a much higher fee.
+
+Often, the best solution is to require the fee to be 0 and rely on [fee pooling](../../../transactions/#pooled-transaction-fees): the other transactions (that are not signed by a smart signature) should provide enough fees to cover all transactions.
+
+There are a few cases where forcing a 0 fee would not be appropriate: for example when a contract account is created to allow users to execute certain transactions.
+In this case, the transaction fee needs to be reasonably bounded depending on the exact use case (e.g., five times the minimum fee).
+
+### DO use 0 fee for inner transactions when possible
+
+The simplest solution for inner transaction fee is to set them to 0 and rely on [fee pooling](../../../transactions/#pooled-transaction-fees): the other transactions (that are not signed by a smart signature) should provide enough fees to cover all transactions.
+
+!!! tip
+    Setting the inner transaction fee to 0 is different from not setting it. When it is not set, the inner transaction fee is set to the minimum allowable, taking into account the minimum transaction fee and credit from overpaying in earlier transactions. It is recommended to always set the transaction fee.
+
+### DO handle congestion smoothly and securely
+
+In case of congestion, the blockchain may require higher fees.
+
+This is a complex subject with [a discussion in progress on the forum](https://forum.algorand.org/t/brainstorm-on-default-valid-window-length-and-lease/8208).
+
+!!! tip
+    Inner transaction fees are not subject to congestion fees. Inner transaction fees can always be set to the minimum fee (see guideline above how to access it) or to 0 (the recommended solution). When set to 0, the inner transaction will take the minimum fee from [fee pooling](../../../transactions/#pooled-transaction-fees).
+
+## DO validate carefully incoming transactions
+
+When validating an incoming transaction to an application account to validate payment for the action of a smart contract, do not forget to:
+
+* Always check the `Type` or `TypeEnum` field to ensure the transaction is of the expected type.
+* Always check the asset ID for asset transfer.
+    * Smart contract developers may be tempted to optimize the contract by remarking that asset transfers can only work for assets that have been opted in by the application account. However, using the opt-in mechanism for that purpose is extremely error-prone. This is extremely strong discouraged.
+* Always check the recipient is the application account.
+* Always check the amount.
+
+
+These guidelines are not exhaustive.
+
+Similar guidelines apply to validate incoming transactions for smart signatures, in which case the recipient account may not be the application account.
+
+
+## DO manage key carefully
+
+If the smart contract is not updatable and the dApp is fully web3 (users interacting with it have their own wallet), then the only account needed for deployment is the creator account.
+The simplest solution is most likely to deploy the smart contract with a throw away account.
+
+The account may then rekey to an account without a known secret key (e.g., `737777777777777777777777777777777777777777777777777UFEJ2CI`, the reward pool) so that the account essentially is locked forever.
+However, note that you must be sure the creator account will never be used for any other purpose (like validating the dApp before rekeying).
+
+If the smart contract is updatable, then extreme care should be taken to secure the key allowing for example.
+This document is not meant to provide exhaustive key management guidelines as key management is an extremely complex topic that requires an expert to find the proper trade-off for the specific applications.
+However, here are some points:
+
+* Do *NOT* use a hardware or software wallet without multisig. 
+    * Note that using a hardware or software wallet with multisigs and multiple people holding a subkey may *NOT* be appropriate either. Appropriateness needs to be assesed by an expert considering all the aspects of the project
+* Do *NOT* store secret keys (or mnemonics) in unencrypted/unsecure location such as environment variables.
+* *NEVER* store secret keys (or mnemonics) in code (e.g., Github).
+
+If the dApp requires the use of custodial accounts, then key management is even more complex.
+In some cases, technical solutions can be used to limit risks, see for example [this forum post](https://forum.algorand.org/t/could-i-implement-an-asa-with-its-own-custom-wallet/3139/2).
+However, as for the keys to update smart contract, it is strongly recommended to consult a security expert.
+
+## DO follow these additional guidelines for smart contracts (and smart signatures)
+
+### General
+
+* Use [Beaker](https://github.com/algorand-devrel/beaker) instead of plain PyTeal or TEAL, unless you need to go in production very quickly. Note however that Beaker may introduce breaking changes.
+* If using plain TEAL or plain PyTEAL (without Beaker):
+    * Explicitly handling all `OnComplete` actions, including delete/update.
+* Follow ARCs:
+    * Strictly follow [ARC-4](https://arc.algorand.foundation/ARCs/arc-0004)
+    * Check if there exists an [ARC](https://arc.algorand.foundation) standardizing what the smart contract will do.
+
+* DO NOT hard-code the minimum balance requirements: those are consensus parameters that can change with consensus upgrades:
+    * Ensure that your smart contract can work if the minimum balance requirements change.
+    * Use the proper API endpoints or TEAL/PyTEAL opcode to read the minimum balance requirement of an account.
+* DO NOT enforce group size as this prevents composability. But BE extremely careful to not allow your smart contract to consider twice the same payment transaction for the same method call. (An insecure example if to have a method A that looks for a payment transaction just before its call and a method B that looks for a payment transaction two transactions before. then the same payment transaction can be used to make both call A and B, which is in most cases insecure.) 
+
+### Updatability and deletability
+
+* Carefully decide whether the smart contracts are updatable / deletable:
+    * Pros of updatable smart contracts
+        * Can add features after creation
+        * Can fix bugs after creation
+    * Cons of updatable smart contracts
+        * Can introduce bugs in updates
+        * Generally means some sense of trust is involved
+* Ensure that the smart contract cannot be deleted or made unusable while the application account still has funds.
+
+
+### Local state, boxes, clear state
+
+* Do **NOT** use local state for data that cannot be lost:
+    * Local state can always be cleared by the user. There is no trustless way to recover data.
+    * Ideally make clear to the user consequences of clearing user data (often this implies loss of funds).
+    * Use boxes to store data that should never be cleared.
+    * Be sure to allow the user opting out easily of the smart contract and recover their minimum balance.
+* Write a clear program that properly handle clear state by users and that can never fail:
+    * Do not use boxes or any foreign account/asset/application when clearing, as the user may not provide them in the transaction.
+    * Remember that the state will be cleared even if the TEAL code fails.
+    * A usual example is when the user sends some funds to the application account and the amount is recorded in local storage (e.g., for retrieval). In this case, a solution can keep in global storage a counter of the "lost funds" by users that cleared they state.
+* Delete all boxes before deleting a smart contract:
+    * Each box increases the minimum balance requirement of the application account. If the smart contract is deleted, the minimum balance is forever lost.
+    * The above is true even if the application account is rekeyed to another account. Rekeying the application account to another account will allow to transfer all the funds out of the application account even if the smart contract is deleted, **except** for the minimum balance due to boxes.
+
+### Oracle, interactions, and randomness
+
+* Use randomness beacon such as [this one](https://developer.algorand.org/articles/usage-and-best-practices-for-randomness-beacon) to generate random values and follow strictly the [best practices](https://developer.algorand.org/articles/usage-and-best-practices-for-randomness-beacon). In addition:
+    * Do **NOT** use the block hash or a PRG/Hash function (such as SHA256 or SHA3) on any block or transaction field information. This is **NOT** secure. For more information read the [randomness on Algorand article](https://developer.algorand.org/articles/randomness-on-algorand/).
+    * Take some time to read very carefully and thoroughly the documents linked above to fully understand what is happening and what the trust model is. Before using a randomness oracle, check whether the required trust assumption is sufficient for your purpose. (As an extreme example, it may not be wise to use a randomness oracle for a 10B$ lottery.)
+* Remember that smart contracts and smart signatures **CANNOT KEEP SECRETS** and **MUST NOT USE PASSWORDS**:
+    * Everything that a smart contract operates on is made public to everyone on the blockchain. In particular, any input and output of the smart contract is public. (This is the case for all major blockchains.)
+    * Oracles might be used but like for randomness beacons above, the exact trust model need to be studied in a lot of details. For example, Intel SGX may or may not be appropriate in certain cases, due to its known vulnerabilities.
+    * Direct or indirect uses of passwords by smart contracts or smart signatures are 99.9% of the time insecure. If your dApp uses password, we strongly recommend that a cryptography expert fully review the design. Most of the documentation and examples on the Internet are wrong or misleading. (As an example amongst many others, looking for PBKDF2 will give examples with number of iterations is only 1,024 which is completely inadequate.)
+* Remember that smart contract and smart signatures **CANNOT** interact by themselves with the outside world:
+    * Smart contracts and smart signatures can only read on-chain data.
+    * Oracles may provide a way for them to interact with the outside world. But as for the randomness beacon above, it is necessary to study the trust model. 
+
+### Overflows and underflows
+
+* Be particularly careful with **integer arithmetic**: overflow and underflow can cause issues. See for example the [(since corrected) TinyMan pool overflow errors](https://docs.tinyman.org/known-issues/2021-11-12-pool-overflow-errors). Any time integer arithmetic is used, do a semi-formal analysis proving that overflow and underflow can never happen.
+    * A semi-formal analysis works by manually writing invariants such as "the value XYZ is always between 1 and 42" and proving (with pen and paper) these invariants hold whatever operation is done on the smart contract. "Proving" here really means "making a proper mathematical proof". "Handwaving" is strongly not recommended.
+* Similarly as integer arithmetic overflow/underflow, do an analysis that that byte arrays never go beyond the limits of the AVM. This is a rarer issue but this still needs to be manually checked.
+
+
+
+## DO follow these additional guidelines for dApps beyond smart contract and smart signature code
+
+### Algod, indexer, and caching
+
+* If using third-party API services:
+    * Understand the trust model: if you do not run the node or indexer, you need to fully trust the provider to operate honestly. A malicious provider can return invalid answers.
+    * Understand the SLA and maximum number load that the provider allows: free tiers may have limited SLA or limited throughput. If your dApp attracts many users, this may prevent proper functioning.
+* For web3 application, use the algod/indexer endpoints provided by the user wallet if the user wallet provides it.
+* Consider whether adding cache is necessary. Like for direct access to database in web2, direct access to blockchain will never be as cheap and as fast as serving cached answers.
+    * Note that cache does not make a dApp non-web3. For example, an NFT galleries may use a cache to quickly display NFTs but then check the hashes of the retrieved cache items against the blockchain (ideally asynchronously).
+
+### Standard security guidelines
+
+Blockchains do not automatically make something secure.
+Traditional security guidelines still need to be strictly followed.
+Actually, due to the nature of blockchains, those guidelines are even more important: in a web3 project, a bug can easily cost millions of dollars without possibility to recover the money through the justice system.
+
+Here we highlight some of them (the list is non-exhaustive):
+
+* **NEVER** store any key or mnemonic in source code. It is almost impossible to securely remove a key or mnemonic from a git repo.
+* Perform regular audits.
+* Have a security expert review any security critical part of the system, particularly key management and anything cryptography related (including any use of password).
+* Ensure highest quality of code, following best practices (including outstanding documentation, full test coverage, proper CI). Review [classical security issues](https://owasp.org/www-project-top-ten/).
+* Ensure proper safeguards preventing a single employees to merge and deploy code for example. 
+* Actively monitor both the dApp on-chain and all the systems around the dApps. Have a response plan as well as a person available 24/7 to mitigate any risk (especially for high value DeFi apps).
+* Have mitigation systems in place:
+    * Some projects have some form of kill switch for example at the beginning. The kill switch is sometimes disabled after some time.
+* Actively limit dependencies and attack surface. Constantly monitor used libraries for any exploit and update as soon as possible. 
+* If using servers, follow [NIST recommendation](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-123.pdf ).
+* Operations should typically fail rather than default to insecure modes. For example if the keys are unavailable, it is usually better to fail than to store sensitive material in the clear. When failing is not an option, at the very least there has to be a very visible warning displayed.
+
+## More about smart signatures vs smart contracts
+
+### Issues with smart signatures
+
+* Smart signatures are much harder to audit than smart contracts in most settings.
+* Smart signatures cannot be used in inner transactions from smart contracts, which strongly limits composability of smart contracts (at least for TEAL v8 and before).
+* Smart signatures are much less flexible than smart contracts. While some simple dApps could be based on smart signatures and using smart signatures could slightly reduce fees, adding any feature would become problematic and any upgrade would most likely be impossible.
+* Contrary to smart contract, smart signatures do not have a standardized ABI (Application Binary Interface). Smart contracts have [ARC-4](https://arc.algorand.foundation/ARCs/arc-0004).
+* (For delegated logic signatures only) Most wallets do not support signing delegated logic signatures, as this is a potentially dangerous operation: a malicious delegated logic signature can remain dormant for years and can allow to siphon out funds of an account much later. There is no way to check whether an account signed a malicious delegated logic signature until the actual fund siphoning occurs.
+
+#### Examples comparing smart signature and applications
+
+To highlight how easier applications are to analyze comparent to smart signatures, see the following PyTEAL examples.
+
+A smart signature like
+
+```python
+return Seq(
+  Assert(Txn.Amount() == Int(1)),
+  Assert(Txn.TypeEnum() == TxnType.Payment),
+  Assert(Txn.Receiver() == intended_receiver)
+)
+```
+
+has the following issues:
+* This contract can get drained via `CloseRemainderTo`.
+* This contract can lose authorization via `RekeyTo`.
+* This contract can get drained via fees.
+
+Compared with the following application
+
+```python
+return Seq(
+  InnerTxnBuilder.Begin(),
+  InnerTxnBuilder.SetFields({
+      TxnField.type_enum: TxnType.AssetTransfer,
+      TxnField.receiver: intended_receiver,
+      TxnField.amount: Int(1)
+  }),
+  InnerTxnBuilder.Submit(),
+)
+```
+
+where:
+* Contract account can't be closed
+* Can't be rekeyed
+* Fee will always be minimum fee required
+
+### (Niche) use cases for smart signatures
+
+There are three main (niche) use cases for smart signatures:
+
+* As a contract account, smart signatures can be used when very costly operations need to be performed, such as `ed25519verify` or `vrf_verify`. A smart contract needing to perform such operations would require to be called (in a group of transactions) just after a transaction from the contract account. 
+    * Importantly, this mechanism can only be used for smart contract methods that are not meant to be called from another smart contract, as smart contracts currently cannot issue inner transaction signed by a logic signature.
+    * An alternative solution is to [increase the opcode budget](../../../dapps/avm/teal/#dynamic-operational-cost-of-teal-opcodes) of the smart contract using group transactions and inner transactions. PyTeal actually includes a [budget increase utility](https://pyteal.readthedocs.io/en/stable/opup.html). This method however is more expensive in terms of transaction fees, compared to using a smart signature contract account. ON the other hand, it has the advantages of being easier to code and of not breaking composability.
+* As a contract account, smart signatures can be used to allow any user (even without a blockchain account) to send certain transactions for free:
+    * This is only meaningful if there are only a limited number of transactions that can be executed in a given amount of time. 
+    * A concrete example would be a smart signature allowing to call a smart contract acting as a third-party blockchain light client. Only when the third-party blockchain has new valid blocks can the smart contract be called succesfully.
+* As a delegated logic signature, smart signatures can be used in complex systems to delegate certain operations on an account to another signature key or another smart contract. Here are a few examples:
+    * Delegation of the issuance of "change offline" transactions to a lower-security key to give the ability to very quickly send "change offline" transactions in case of a participation node issue.
+    * Delegation of ASA transfers to a "hot key." This allows using the Algorand blockchain to record token ownership in a custodial system (e.g., for a loyalty reward program). The actual keys of the custodial accounts can be kept in cold storage, while the system uses hot keys whose only ability is to transfer tokens between custodial accounts. This way, the system is no less secure than a centralized system with a centralized DB: in case of leak of keys, the only thing the attacker can do is to transfer the tokens incorrectly, but the attacker is not able to rekey accounts or steal Algos (if Algos are used for any other purpose).
+
+Note that the second use case can often be done using a smart contract and inner transactions. However, a delegated logic signature is often easier to write and use for that purpose.
+
+### Migration from smart signatures to smart contracts
+
+In the past, smart signatures were used as companions of smart contracts in the following scenarios:
+
+* **Escrow accounts** for smart contracts before inner transactions (AVM 1.0 / TEAL v5). Now inner transactions should be used. Notes:
+    * Since AVM 1.0 / TEAL v5, escrow accounts can be either a smart signature contract account or an application account (associated to a smart contract). Application accounts use inner transactions and are preferred.
+    * There are a few rare corner cases where inner transactions cannot be used. For example TEAL v8 does not allow making an inner transaction from a (smart signature) contract account nor allow making an application call inner transaction for a TEAL v2/v3/v4 smart contract. In those cases, it may be needed to use a contract account as escrow account. However, it is strongly recommended to restrict the use of such an escrow account to the rare method calls that need it. Indeed, such method calls would themselves not be callable from inner transactions perpetuating the above issue.
+    * In case multiple escrow accounts are needed (instead of a globa escrow account), the simplest solution is to rekey accounts to the application account.
+    * Before AVM 1.1 / TEAL v6, only a small subsets of inner transactions were supported, making use of contract accounts for escrow accounts sometimes necessary. This is no more an issue.
+* **Un-erasable local storage** for smart contracts before boxes (TEAL v8). Local storage can be erased at any time by the account associated to the local storage. Sometimes, this is not a desirable property. In the past, special contract accounts holding local storages may have been used. Boxes are now the proper solution.
+* **Infinite storage** for smart contracts before boxes (TEAL v8). Global storage is limited and the solution to get more global storage in the past was to use local storage of contract accounts (or accounts rekeyed to the application account). Boxes are now the proper solution.
+
+### Note on the terminology
+
+Smart signatures are also called **logic signature** or **LogicSig**.
+
+Smart signatures were also called in the past **stateless smart contracts** or just "Algorand smart contracts (ASC1)" before TEAL version 2. 
+In particular, any TEAL program that does not start with `#pragma version <N>` is a TEAL v1 smart signature and should not be used at all.
+
+## Additional guidelines specific to smart signatures
+
+!!! info
+    As mentioned above, smart signatures should only be used in very few niche use cases. Most likely you should not be using them. These guidelines are only there for these very few niche use cases.
+   
+These guidelines are specific to smart signatures. They complement the other guidelines in this document. Smart signatures should also obey the other guidelines.
+   
+* **Only use smart signatures when absolutely required.** See section above for details.
+* Do not use TEAL v1 smart signatures (i.e., TEAL codes not starting with any `#pragma version ...`):
+    * If you need to migrate a TEAL v1 smart signature to a more recent version, be extra careful. In particular, add a test checking that `RekeyTo` is the `ZeroAddress`. Not doing so most likely allows any attacker to 
+* Check as many transaction fields (accessible via `txn`/`Txn` in TEAL/PyTEAL) as possible to constrain the transactions approved by the smart signature as much as possible to avoid security issues. In particular (this is not an exhaustive list):
+    * Always check the `Type` or `TypeEnum` field to ensure the transaction is of the expected type.
+    * Always check the following fields: `RekeyTo`, `CloseRemainderTo` (for payments), and `AssetCloseTo` (for asset transfers).
+        * For most cases, these fields must be set to the `ZeroAddress`.
+    * Follow the guidelines for transaction validation and for fee management above.
+* Be careful that the same smart signature can be used for multiple transactions in a group:
+    * Either check the current transaction fields using `txn` / `Txn.` (instead of `gtxn` / `Gtxn`);
+    * Or use `gtxn` / `Gtxn` for an index `i` and verify that the current transaction is the `i`-th ().
+    * Not doing the above can allow an attacker to call twice the smart signature in the same group: the first transaction obeys the rule of the smart signature and is safe, but the second one is unconstrained and can allow the attacker to siphon out all funds.
+* If the use case permits it, set up an expiration mechanism:
+    * Contract accounts should allow the sender to reclaim their assets after a certain round/time (`txn FirstValid > NNNN` or `txn FirstValidTime > TTTT`).
+    * Delegated logic signatures should specify an expiration round in the future after which they will no longer function.
+* Be extra careful when combining multiple contract accounts in a group of transaction and to perform multiple checks. The simplest solution is to enforce the transaction group size 
+* Remember that, as for smart contracts, the smart signature code, the transaction fields, and the arguments of the smart signature are all **public**. In particular:
+    * An attacker can replay a transaction signed by a smart signature (whether in contract account or logic signature mode).
+    * For example, a delegated logic signature allowing approving any change offline transaction is insecure. The first time it is used, an attacker can replay it many times and empty the account (using all the fees)! The delegated logic signature needs to 
+* Be careful about the fact that, contrary to arguments of smart contracts, arguments of smart signatures are **NOT** signed by the sender account and are **NOT** part of the computation of the group ID. In other words, an attacker can intercept a transaction signed by a smart signature and change its arguments (as long as it is still accepted by the smart signature).
+* Be careful about the fact that the same smart signature can be used in multiple networks.
+  * For instance, if a smart signature is signed with the intent of using it on TestNet, that same transaction can be sent to MainNet with that same smart signature.
+  * Always use new accounts when using TestNet (or any other network) to avoid reusing the same account that signed a smart signature.
+  * Make sure to write a smart signature that checks which network it is being run on. You can use:
+
+=== "PyTeal"
+    ```py
+    Global.genesis_hash()
+    ```
+
+=== "TEAL"
+    ```teal
+    global GenesisHash
+    ```
+
+## Additional resources
+
+* [Trails of Bits guideslines](https://github.com/crytic/building-secure-contracts/tree/master/not-so-smart-contracts/algorand)
+* [ASC Security Guidelines from Joe Polny](https://github.com/joe-p/algo-edu/blob/master/resources/en-US/asc_security.md) on which this document is partially based

package/dist/resources/knowledge/taxonomy/developer:docs:details:dapps:smart-contracts:index.md

@@ -0,0 +1,41 @@
+title: Introduction
+
+Algorand Smart Contracts (ASC1) are small programs that serve various functions on the blockchain and operate on layer-1. Smart contracts are separated into two main categories, smart contracts, and smart signatures. These types are also referred to as stateful and stateless contracts respectively. The type of contract that is written will determine when and how the logic of the program is evaluated. See the following sections to understand how each type of contract is used on the Algorand blockchain. Both types of contracts are written in the [Transaction Execution Approval Language (TEAL)](../avm/teal), which is an assembly-like language that is interpreted by the [Algorand Virtual Machine (AVM)](../avm) running within an Algorand node. TEAL programs can be written by hand or by using the Python language with the PyTEAL compiler. 
+
+
+!!! warning
+    When writing smart contracts, make sure to follow [TEAL guidelines](../avm/teal/guidelines). This is very important in order to prevent smart contracts from being compromised.
+
+# Quick start videos
+
+If you prefer videos, take a look at this 6 minute guide to learn about Smart Contracts Overview.
+
+<iframe width="100%" style="aspect-ratio:16/9" src="https://www.youtube-nocookie.com/embed/_8vLEeJDjlc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+
+# Smart contracts
+Smart contracts are contracts that, once deployed, are remotely callable from any node in the Algorand blockchain. Once deployed, the on-chain instantiation of the contract is referred to as an Application and assigned an Application Id. These applications are triggered by a specific type of transaction called an Application Call transaction.  These on-chain applications handle the primary decentralized logic of a dApp. 
+
+- Applications can [modify state](./apps/#modifying-state-in-smart-contract) associated with the application (global state) or a per application+account (local state) basis. 
+- Applications can [access](./apps/#using-assets-in-smart-contracts) on-chain values, such as account balances, asset configuration parameters, or the latest block time.
+- Applications can [execute transactions](./apps/#inner-transactions) as part of the execution of the logic. One type of transaction they can perform, as of AVM 1.1, is an Application Call transaction which allows one application to call another.  This ability to call other applications enables composability between applications. 
+- Applications have an associated [Application Account](./apps/#using-a-smart-contract-as-an-escrow) that can hold Algos or ASAs balances and can be used as on-chain escrow accounts. 
+
+To provide a standard method for exposing an API and encoding/decoding data types from application call transactions, the [ABI](/docs/get-details/dapps/smart-contracts/ABI/) should be used. 
+
+For more information on smart contracts, see the [smart contract documentation](./apps). For more information on building smart contracts in PyTeal see the [build with python documentation](/docs/get-details/dapps/writing-contracts/pyteal).
+For more information on using smart contracts with the SDKs see the [Interacting with smart contracts documentation](./frontend/smartsigs.md).
+For more information on debugging a smart contract, see the [debugging](./debugging.md) page.
+
+# Smart signatures
+Smart signatures contain logic that is used to sign transactions, primarily for signature delegation. The logic of the smart signature is submitted with a transaction. While the logic in the smart signature is stored on the chain as part of resolving the transaction, the logic is not remotely callable. Any new transaction that relies on the same smart signature would resubmit the logic. When the logic is submitted to a node the AVM evaluates the logic, where it either fails or succeeds. If a smart signature’s logic fails when executed by the AVM, the associated transaction will not be executed. 
+
+Smart signatures can be used in two different modes. When compiled smart signatures produce an Algorand account that functions similar to any other account on the blockchain. These accounts can hold Algos or assets. These funds are only allowed to leave the account if a transaction occurs from the account that successfully executes the logic within the smart signature. This is similar in functionality to a smart contract escrow, but the logic must be submitted for every transaction from the account. Smart signatures can also also be used to delegate some portion of authority to another account. In this case, an account can sign the smart signature which can then be used at a later time to sign a transaction from the original signer’s account. This is referred to as account delegation. See the [modes of use documentation](./smartsigs/modes.md) for more details on these two types of smart signatures.   
+
+Once a transaction that is signed with a smart signature, is submitted it is evaluated by an Algorand node using the Algorand Virtual Machine. These contracts only have access to a few global variables, some temporary scratch space, and the properties of the transaction(s) they are submitted with. 
+
+For more information on smart signatures, see the [smart signature documentation](./smartsigs). For more information on building contracts in PyTeal see the [build with Python documentation](/docs/get-details/dapps/writing-contracts/pyteal).
+For more information on using smart signatures with the SDKs see the [Interacting with smart signature documentation](./frontend/smartsigs).
+For more information on debugging a smart contract, see the [debugging](./debugging.md) page.
+
+
+For more information on the [AVM](../avm) or the [TEAL language](../avm/teal) see the developer documentation.

package/dist/resources/knowledge/taxonomy/developer:docs:details:dapps:smart-contracts:smartsigs:index.md

@@ -0,0 +1,15 @@
+title: SmartSig details
+
+**Algorand Smart Contracts (ASC1)**, provides both smart contracts and smart signatures. The intended use case for the contract will determine the appropriate type to use. Smart signatures are primarily used to delegate signature authority. Smart signatures can also be used as escrow or contract accounts, but in most cases it is preferable to use a [smart contract](../apps/) when an escrow is required.
+
+Most Algorand transactions are authorized by a [signature from a single account](../../../transactions/signatures.md#single-signatures) or a [multisignature account](../../../transactions/signatures#multisignatures). Algorand’s smart signatures allow for a third type of signature using a **Transaction Execution Approval Language (TEAL)** program, called a **logic signature (LogicSig)**. Smart signatures provide two modes for TEAL logic to operate as a LogicSig, to create a contract account that functions similar to an escrow or to delegate signature authority to another account. These two modes are discussed in detail in [Usage Modes](./modes/).
+
+These smart signatures can be written in [TEAL](/docs/get-details/dapps/avm/teal/) or in Python using the [PyTeal library](/docs/get-details/dapps/writing-contracts/pyteal). If written in Python the library will return the automatically generated TEAL to be used by either the SDKs or the `goal` command-line tool.  
+
+To learn more about the TEAL language specification see the [TEAL Specification Reference](../../avm/teal/specification.md). To get a high-level understanding of how TEAL is processed see the [TEAL Overview guide](../../avm/teal/).
+
+To compile and use a TEAL program as a smart signature with `goal`, see [CLI smart signatures](walkthrough).
+
+To start working with smart signatures with the SDKs, visit the [Interact with smart signatures](../frontend/smartsigs/) section.
+
+

package/dist/resources/knowledge/taxonomy/developer:docs:details:dapps:smart-contracts:smartsigs:modes.md

@@ -0,0 +1,34 @@
+title: Modes of use
+
+Smart signatures have two basic usage scenarios; as a [**contract account**](#contract-account) or as a [**delegated signature**](#delegated-approval). These modes are used to approve transactions in different ways which are described below. Both modes make use of Logic Signatures. While using smart signatures for contract accounts is possible, it is now possible to create a contract account using a [smart contract](../apps/index.md).
+
+# Logic signatures
+Logic Signatures, referenced as LogicSig, are structures that contain the following four parts.
+
+
+<center>![Logic Signature Structure](../../../../imgs/modes-0.png)</center>
+<center>*Logic Signature Structure*</center>
+
+Before a LogicSig can be used with a transaction, it first must be a valid Logic Signature. The LogicSig is considered valid if one of the following scenarios is true.
+
+> * Sig contains a valid Signature of the program from the account that is sending the Transaction
+> * Msig contains a valid Multi-Signature of the program from the Multi-Signature account sending the Transaction
+> * The hash of the program is equal to the Sender's Address
+  
+
+The first two cases are examples of delegation. An account owner can declare that on their behalf the signed logic can authorize transactions. These accounts can be either single or multi-signature accounts. Account delegation is described in further detail below.
+
+The third case is an account wholly governed by the program. The program cannot be changed. Once Algos or assets have been sent to that account, Algos or assets only leave when there is a transaction that approves it. This usage case is considered a contract account which is described below.
+# Contract account
+For each unique compiled smart signature program there exists a single corresponding Algorand address, output by `goal clerk compile`. To use a TEAL program as a contract account, send Algos to its address to turn it into an account on Algorand with a balance. Outwardly, this account looks no different from any other Algorand account and anyone can send it Algos or Algorand Standard Assets to increase its balance.  The account differs in how it authenticates spends _from_ it, in that the logic determines if the transaction is approved. To spend from a contract account, create a transaction that will evaluate to True against the TEAL logic, then add the compiled TEAL code as its logic signature. It is worth noting that anyone can create and submit the transaction that spends from a contract account as long as they have the compiled TEAL contract to add as a logic signature.
+
+<center>![Contract Account](../../../../imgs/modes-1.png)</center>
+<center>*TEAL Contract Account*</center>
+
+# Delegated approval
+Smart signatures can also be used to delegate signature authority, which means that a private key can sign a TEAL program and the resulting output can be used as a signature in transactions on behalf of the account associated with the private key. The owner of the delegated account can share this logic signature, allowing anyone to spend funds from his or her account according to the logic within the TEAL program.
+For example, if Alice wants to set up a recurring payment with her utility company for up to 200 Algos every 50000 rounds, she creates a TEAL contract that encodes this logic, signs it with her private key, and gives it to the utility company. The utility company uses that logic signature in the transaction they submit every 50000 rounds to collect payment from Alice.
+The logic signature can be produced from either a single or multi-signature account.
+
+<center>![Delegated Signature](../../../../imgs/modes-2.png)</center>
+<center>*TEAL Delegated Signature*</center>