diff --git a/.env.example b/.env.example index 5f78ed827..8dfe325ac 100644 --- a/.env.example +++ b/.env.example @@ -2,7 +2,8 @@ MAINNET_RPC_URL=https://eth-mainnet.alchemyapi.io/v2/ # -------- For scripts -------- -# Etherscan API key for mainnet/goerli/sepolia, primarily used for contract verification. +# Etherscan API key, primarily used for contract verification. When deploying and verifying +# contracts, the API key needs to match the network of the `SCRIPT_RPC_URL`. # Note that this can also be helpful for running tests to provide more information on # traces during fork tests. For that use case, you may want to include a mainnet API key here when # running `forge test` diff --git a/CODEOWNERS b/CODEOWNERS index 269e52e41..36f60de7d 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1 +1 @@ -* @austingreen @0xrajath @dd0sxx +* @austingreen @0xrajath diff --git a/README.md b/README.md index d20338ca8..93390ae1f 100644 --- a/README.md +++ b/README.md @@ -67,12 +67,14 @@ The comments in that file explain what each variable is for and when they're nee | LlamaRelativeUniqueHolderQuorum | [0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb](https://etherscan.io/address/0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb) | [0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb](https://optimistic.etherscan.io/address/0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb) | [0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb](https://arbiscan.io/address/0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb) | [0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb](https://basescan.org/address/0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb) | [0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb](https://polygonscan.com/address/0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb) | | LlamaAbsoluteQuorum | [0x68f153D5F50e66CC0c6D9802362137BCF2aE5631](https://etherscan.io/address/0x68f153D5F50e66CC0c6D9802362137BCF2aE5631) | [0x68f153D5F50e66CC0c6D9802362137BCF2aE5631](https://optimistic.etherscan.io/address/0x68f153D5F50e66CC0c6D9802362137BCF2aE5631) | [0x68f153D5F50e66CC0c6D9802362137BCF2aE5631](https://arbiscan.io/address/0x68f153D5F50e66CC0c6D9802362137BCF2aE5631) | [0x68f153D5F50e66CC0c6D9802362137BCF2aE5631](https://basescan.org/address/0x68f153D5F50e66CC0c6D9802362137BCF2aE5631) | [0x68f153D5F50e66CC0c6D9802362137BCF2aE5631](https://polygonscan.com/address/0x68f153D5F50e66CC0c6D9802362137BCF2aE5631) | | LlamaAbsolutePeerReview | [0x0092CD4044E1672c9c513867eb75e6213AF9742f](https://etherscan.io/address/0x0092CD4044E1672c9c513867eb75e6213AF9742f) | [0x0092CD4044E1672c9c513867eb75e6213AF9742f](https://optimistic.etherscan.io/address/0x0092CD4044E1672c9c513867eb75e6213AF9742f) | [0x0092CD4044E1672c9c513867eb75e6213AF9742f](https://arbiscan.io/address/0x0092CD4044E1672c9c513867eb75e6213AF9742f) | [0x0092CD4044E1672c9c513867eb75e6213AF9742f](https://basescan.org/address/0x0092CD4044E1672c9c513867eb75e6213AF9742f) | [0x0092CD4044E1672c9c513867eb75e6213AF9742f](https://polygonscan.com/address/0x0092CD4044E1672c9c513867eb75e6213AF9742f) | -|_Account logic contract_| -| LlamaAccount (logic contract) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://etherscan.io/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://optimistic.etherscan.io/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://arbiscan.io/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://basescan.org/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://polygonscan.com/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | +|_Account logic contracts_| +| LlamaAccount | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://etherscan.io/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://optimistic.etherscan.io/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://arbiscan.io/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://basescan.org/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://polygonscan.com/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | +| LlamaAccountWithDelegation | [0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b](https://etherscan.io/address/0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b) | [0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b](https://optimistic.etherscan.io/address/0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b) | [0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b](https://arbiscan.io/address/0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b) | [0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b](https://basescan.org/address/0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b) | [0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b](https://polygonscan.com/address/0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b) | |_Helper contract_| | LlamaLens | [0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB](https://etherscan.io/address/0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB) | [0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB](https://optimistic.etherscan.io/address/0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB) | [0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB](https://arbiscan.io/address/0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB) | [0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB](https://basescan.org/address/0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB) | [0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB](https://polygonscan.com/address/0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB) | |_Script contracts_| | LlamaGovernanceScript | [0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335](https://etherscan.io/address/0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335) | [0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335](https://optimistic.etherscan.io/address/0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335) | [0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335](https://arbiscan.io/address/0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335) | [0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335](https://basescan.org/address/0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335) | [0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335](https://polygonscan.com/address/0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335) | +| LlamaAccountTokenDelegationScript | [0xC60Ab709CA5BbD73fC2b46D232344740A8903b51](https://etherscan.io/address/0xC60Ab709CA5BbD73fC2b46D232344740A8903b51) | [0xC60Ab709CA5BbD73fC2b46D232344740A8903b51](https://optimistic.etherscan.io/address/0xC60Ab709CA5BbD73fC2b46D232344740A8903b51) | [0xC60Ab709CA5BbD73fC2b46D232344740A8903b51](https://arbiscan.io/address/0xC60Ab709CA5BbD73fC2b46D232344740A8903b51) | [0xC60Ab709CA5BbD73fC2b46D232344740A8903b51](https://basescan.org/address/0xC60Ab709CA5BbD73fC2b46D232344740A8903b51) | [0xC60Ab709CA5BbD73fC2b46D232344740A8903b51](https://polygonscan.com/address/0xC60Ab709CA5BbD73fC2b46D232344740A8903b51) | ## Testnet deployments @@ -90,12 +92,14 @@ The comments in that file explain what each variable is for and when they're nee | LlamaRelativeUniqueHolderQuorum | [0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb](https://sepolia.etherscan.io/address/0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb) | [0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb](https://goerli.etherscan.io/address/0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb) | [0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb](https://goerli-optimism.etherscan.io/address/0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb) | [0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb](https://goerli.basescan.org/address/0xa5B2B5Ae8F278530270f44D7CFC2440292583BEb) | | LlamaAbsoluteQuorum | [0x68f153D5F50e66CC0c6D9802362137BCF2aE5631](https://sepolia.etherscan.io/address/0x68f153D5F50e66CC0c6D9802362137BCF2aE5631) | [0x68f153D5F50e66CC0c6D9802362137BCF2aE5631](https://goerli.etherscan.io/address/0x68f153D5F50e66CC0c6D9802362137BCF2aE5631) | [0x68f153D5F50e66CC0c6D9802362137BCF2aE5631](https://goerli-optimism.etherscan.io/address/0x68f153D5F50e66CC0c6D9802362137BCF2aE5631) | [0x68f153D5F50e66CC0c6D9802362137BCF2aE5631](https://goerli.basescan.org/address/0x68f153D5F50e66CC0c6D9802362137BCF2aE5631) | | LlamaAbsolutePeerReview | [0x0092CD4044E1672c9c513867eb75e6213AF9742f](https://sepolia.etherscan.io/address/0x0092CD4044E1672c9c513867eb75e6213AF9742f) | [0x0092CD4044E1672c9c513867eb75e6213AF9742f](https://goerli.etherscan.io/address/0x0092CD4044E1672c9c513867eb75e6213AF9742f) | [0x0092CD4044E1672c9c513867eb75e6213AF9742f](https://goerli-optimism.etherscan.io/address/0x0092CD4044E1672c9c513867eb75e6213AF9742f) | [0x0092CD4044E1672c9c513867eb75e6213AF9742f](https://goerli.basescan.org/address/0x0092CD4044E1672c9c513867eb75e6213AF9742f) | -|_Account logic contract_| -| LlamaAccount (logic contract) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://sepolia.etherscan.io/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://goerli.etherscan.io/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://goerli-optimism.etherscan.io/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://goerli.basescan.org/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | +|_Account logic contracts_| +| LlamaAccount | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://sepolia.etherscan.io/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://goerli.etherscan.io/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://goerli-optimism.etherscan.io/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | [0x915Af6753f03D2687Fa923b2987625e21e2991aE](https://goerli.basescan.org/address/0x915Af6753f03D2687Fa923b2987625e21e2991aE) | +| LlamaAccountWithDelegation | [0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b](https://sepolia.etherscan.io/address/0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b) | [0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b](https://goerli.etherscan.io/address/0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b) | [0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b](https://goerli-optimism.etherscan.io/address/0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b) | [0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b](https://goerli.basescan.org/address/0x28CeeDA47db26612882a56BaC9EFc0B6DeA2C91b) | |_Helper contract_| | LlamaLens | [0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB](https://sepolia.etherscan.io/address/0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB) | [0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB](https://goerli.etherscan.io/address/0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB) | [0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB](https://goerli-optimism.etherscan.io/address/0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB) | [0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB](https://goerli.basescan.org/address/0x1D74803D4939aFa3CC9fF1B8667bE4d119d925cB) | |_Script contracts_| | LlamaGovernanceScript | [0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335](https://sepolia.etherscan.io/address/0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335) | [0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335](https://goerli.etherscan.io/address/0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335) | [0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335](https://goerli-optimism.etherscan.io/address/0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335) | [0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335](https://goerli.basescan.org/address/0x21f45e61213a13Dc6B7Ba2eC157c4e95810cD335) | +| LlamaAccountTokenDelegationScript | [0xC60Ab709CA5BbD73fC2b46D232344740A8903b51](https://sepolia.etherscan.io/address/0xC60Ab709CA5BbD73fC2b46D232344740A8903b51) | [0xC60Ab709CA5BbD73fC2b46D232344740A8903b51](https://goerli.etherscan.io/address/0xC60Ab709CA5BbD73fC2b46D232344740A8903b51) | [0xC60Ab709CA5BbD73fC2b46D232344740A8903b51](https://goerli-optimism.etherscan.io/address/0xC60Ab709CA5BbD73fC2b46D232344740A8903b51) | [0xC60Ab709CA5BbD73fC2b46D232344740A8903b51](https://goerli.basescan.org/address/0xC60Ab709CA5BbD73fC2b46D232344740A8903b51) | ## Documentation @@ -113,11 +117,12 @@ $ forge doc -o reference/ -b -s ### Audits -We received two audits from Spearbit and one from Code4rena. You can find links to the reports below: +We've received three audits from Spearbit and one from Code4rena. You can find links to the reports below: - [Llama Spearbit Audit (June 2023)](https://github.com/llamaxyz/llama/blob/main/audits/Llama-Spearbit-Audit.pdf) - [Llama Code4rena Audit](https://github.com/llamaxyz/llama/blob/main/audits/Llama-Code4rena-Audit.md) - [Llama Spearbit Audit (August 2023)](https://github.com/llamaxyz/llama/blob/main/audits/Llama-Spearbit-Audit-2.pdf) +- [Llama v1.1.0 Spearbit Audit (January 2024)](https://github.com/llamaxyz/llama/blob/main/audits/Llama-Spearbit-Audit-3.pdf) ### Bug bounty program @@ -127,14 +132,14 @@ Llama policyholders are trusted participants of a Llama instance based on what t We adapted the [Immunefi Vulnerability Severity Classification System](https://immunefi.com/immunefi-vulnerability-severity-classification-system-v2-3/) to determine classification. -| **Level** | **Example** | **Maximum Bug Bounty** | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | -| 5. Critical | - Unauthorized action state transitions
- Major manipulation of approval or disapproval results
- Vulnerabilities in the roles and permissions system that result in unauthorized ability to create, approve, or disapprove actions
- Permanent freezing of funds in accounts | Up to 100,000 USDC | +| **Level** | **Example** | **Maximum Bug Bounty** | +| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | +| 5. Critical | - Unauthorized action state transitions
- Major manipulation of approval or disapproval results
- Vulnerabilities in the roles and permissions system that result in unauthorized ability to create, approve, or disapprove actions
- Permanent freezing of funds in accounts | Up to 100,000 USDC | | 4. High | - Minor manipulation of approval or disapproval results that are unlikely to affect outcomes
- Minor vulnerabilities in the roles and permissions system that are unlikely to affect outcomes
- Temporary freezing of funds in accounts | Up to 20,000 USDC | -| 3. Medium | - Griefing that disrupts an instance's action flow | Up to 5,000 USDC | -| 2. Low | - Contract fails to deliver promised returns, but doesn't lose value | Up to 1,000 USDC | -| 1. None | - Best practices | | -| Not sure? | | Email us | +| 3. Medium | - Griefing that disrupts an instance's action flow | Up to 5,000 USDC | +| 2. Low | - Contract fails to deliver promised returns, but doesn't lose value | Up to 1,000 USDC | +| 1. None | - Best practices | | +| Not sure? | | Email us | Email us at [security@llama.xyz](mailto:security@llama.xyz) to get in contact. diff --git a/audits/Llama-Spearbit-Audit-3.pdf b/audits/Llama-Spearbit-Audit-3.pdf new file mode 100644 index 000000000..0c82625e2 Binary files /dev/null and b/audits/Llama-Spearbit-Audit-3.pdf differ diff --git a/docs/README.md b/docs/README.md index a490800f7..06ad01e8a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -33,3 +33,4 @@ To learn more about how the Llama framework works, read our documentation and us - [Strategies](https://github.com/llamaxyz/llama/blob/main/docs/strategies.md) - [Accounts](https://github.com/llamaxyz/llama/blob/main/docs/accounts.md) - [Instance deployment](https://github.com/llamaxyz/llama/blob/main/docs/instance-deployment.md) +- [Scripts](https://github.com/llamaxyz/llama/blob/main/docs/scripts.md) diff --git a/docs/accounts.md b/docs/accounts.md index c86b1ab73..c38aca204 100644 --- a/docs/accounts.md +++ b/docs/accounts.md @@ -13,9 +13,16 @@ There are also additional functions to batch transfer tokens to multiple recipie Instances can deploy dedicated accounts for different organizational functions and permission each function independently. For more granular fund management rules, instances can implement [guards](https://github.com/llamaxyz/llama/blob/main/docs/actions.md#guards) to set requirements based on token amount, frequency of transfer, market conditions, or any other rule(s) that can be expressed as code. -## Arbitrary execute +## Arbitrary Execute The account contract also includes an `execute` function that allows for arbitrary calls and code execution. Actions that call this function can be used to call or delegatecall a target contract with specified calldata. This ensures that non-standard tokens will not be stuck in the account and accounts can interact directly with external contracts when necessary. Allowing delegatecalls means that accounts can expand their functionality over time. They can use periphery contracts that enable token streaming, vesting, swapping, and allow those contracts to execute code in the account’s context. Arbitrary execution is a powerful concept with important security considerations, so best practices should be followed when using this function. Instances should stick to the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) and limit which policyholders are granted permission to create actions for this function. Guards are recommended to define which targets can be called, whether it uses a call or delegatecall, and to limit acceptable parameters that can be used. + +## Account With Token Delegation + +In addition to the standard [LlamaAccount](https://github.com/llamaxyz/llama/blob/main/src/accounts/LlamaAccount.sol) logic contract, we've also created a logic contract for governance token delegation. +[LlamaAccountWithDelegation](https://github.com/llamaxyz/llama/blob/main/src/accounts/LlamaAccountWithDelegation.sol) inherits all the functionality provided in [LlamaAccount](https://github.com/llamaxyz/llama/blob/main/src/accounts/LlamaAccount.sol), but also includes functions for delegating governance tokens to a delegatee and batch delegating multiple governance tokens to multiple delegates. +This is useful for unlocking the voting power of governance tokens. +For example, these tokens can be delegated to an instance's executor contract, so the instance can vote with the governance tokens held in its accounts. diff --git a/docs/actions.md b/docs/actions.md index 9b069b7a0..cbc9ff990 100644 --- a/docs/actions.md +++ b/docs/actions.md @@ -14,6 +14,7 @@ Actions are composed of the following parameters: ## Key Concepts +- Llama Instance: The unique `LlamaCore`, `LlamaPolicy`, and `LlamaExecutor` addresses for a deployment. - [`LlamaCore`](https://github.com/llamaxyz/llama/blob/main/src/LlamaCore.sol): Manages the action process from creation to execution. - Actions: Proposals made by policyholders to execute onchain transactions. - Strategies: A contract that holds all of the logic to determine the rules and state of an action. For example, strategies determine whether or not an action is approved/disapproved, canceled, or able to be executed. They also determine details around who is allowed to cast approvals/disapprovals. @@ -24,7 +25,6 @@ Actions are composed of the following parameters: - Roles: A signifier that is used to permission action creation, approval, and disapproval. Any role can be given to one or more policyholders. - Permission IDs: A unique identifier that can be assigned to roles to enable action creation. Permission IDs are represented as a hash of the target contract, function selector, and strategy contract. Actions cannot be created unless a policyholder holds a role with the correct permission. - [`LlamaExecutor`](https://github.com/llamaxyz/llama/blob/main/src/LlamaExecutor.sol): The single exit point of a Llama instance. All actions that are executed will be sent from the Llama executor. This is the address that should be the `owner` or other privileged role in a system controlled by the llama instance. -- Llama Instance: The unique `LlamaCore,`LlamaPolicy`, and`LlamaExecutor` addresses for a deployment. - `approvalPeriod`: The length of time that policyholders can approve an action. - `queuingPeriod`: The inverse of the approval period that can also be thought of as the disapproval period; defines the amount of time that policyholders have to disapprove an action. @@ -101,13 +101,14 @@ Like the name suggests, if a policyholder with a force role casts their approval ## Scripts -Scripts are the term used to refer to target contracts that are called via `DELEGATECALL` instead of a normal `CALL`. -The main use-case for scripts is to batch multiple calls together into one action. -In particular, scripts should be used to batch calls that are regularly made in tandem with one another to perform maintenance or other recurring tasks. +By default [LlamaExecutor](https://github.com/llamaxyz/llama/blob/main/src/LlamaExecutor.sol) will call its targets using a low level `call` unless that target is a script. +Scripts are target contracts that are called using `delegatecall` instead of `call`. +To specify a target as a script, a policyholder must create an action that calls the `setScriptAuthorization` function on `LlamaCore` with the target address and `isAuthorized` set to `true`. +Targets can be removed as scripts by creating an action that calls the `setScriptAuthorization` function with the same target address and `isAuthorized` set to `false`. -`DELEGATECALL` is dangerous to use by default, so scripts must be authorized before use. -To authorize a script, a policyholder must create an action that calls the `setScriptAuthorization` function on `LlamaCore`. -Scripts may also be unauthorized using the same function. +Scripts allow Llama instances to execute arbitrary code in the context of `LlamaExecutor`. +This makes them useful for defining repeatable workflows that aren't included in the `LlamaCore`, `LlamaPolicy`, or in the instance's protocol contracts. +Although most scripts will be protocol specific, the [Scripts](https://github.com/llamaxyz/llama/blob/main/docs/scripts.md) section documents examples that are useful across all instances. ## Guards diff --git a/docs/scripts.md b/docs/scripts.md new file mode 100644 index 000000000..46dbe5337 --- /dev/null +++ b/docs/scripts.md @@ -0,0 +1,26 @@ +# Scripts + +By default [LlamaExecutor](https://github.com/llamaxyz/llama/blob/main/src/LlamaExecutor.sol) will call its targets using a low level `call` unless that target is a script. +Scripts are target contracts that are called using `delegatecall` instead of `call`. +To specify a target as a script, a policyholder must create an action that calls the `setScriptAuthorization` function on `LlamaCore` with the target address and `isAuthorized` set to `true`. +Targets can be removed as scripts by creating an action that calls the `setScriptAuthorization` function with the same target address and `isAuthorized` set to `false`. + +Scripts allow Llama instances to execute arbitrary code in the context of `LlamaExecutor`. +This makes them useful for defining repeatable workflows that aren't included in the `LlamaCore`, `LlamaPolicy`, or in the instance's protocol contracts. + +## Security + +Any low level calls made by scripts will use the instance's executor as `msg.sender`. +Policyholders should review target contracts being authorized to ensure that this power isn't being abused. + +Llama's architecture is designed to limit this attack surface area. +Since the `executeAction` on `LlamaCore` does not call targets directly and only interacts with external contracts through the `LlamaExecutor`, scripts can't access `LlamaCore`'s storage. + +## Examples + +All the scripts listed below have been audited and deployed to all networks supported by Llama unless otherwise stated. +The contract addresses can be found in the [deployments section](https://com/llamaxyz/llama/blob/main/README.md#deployments) of the README. + +- **LlamaGovernanceScript:**: defines common governance workflows and batch functions for managing a Llama instance. +- **LlamaAccountTokenDelegationScript:** leverages the `LlamaAccount` arbitrary execute function to allow users to delegate governance tokens from their Llama accounts. This is useful if an instance is using a standard `LlamaAccount` and doesn't want to transfer assets. +- **LlamaInstanceConfigScriptTemplate:** can be used in conjunction with [ConfigureAdvancedLlamaInstance](https://github.com/llamaxyz/llama/blob/main/script/ConfigureAdvancedLlamaInstance.s.sol) to deploy and configure a new Llama instance by writing code. This is more expressive than the default JSON-based configurations.