docs: Add Safe smart account reference (#624)

* Owner and module functions * Remaining events and functions * Add redirections for root folders * Fix vale errors * Implement requested changes (owners) * Fix links * Various fixes * Format files * Minor fix * Implement requested changes (utilities) * Implement requested changes (fallback) * Implement requested changes (guards) * Implement requested changes (modules) * Implement requested changes (signatures) * Implement requested changes (setup) * Implement requested changes (transactions) * Various fixes * Fix vale errors * Fix redirections * Fix missing imports * Implement requested formatting; add and remove white spaces; implement requested indentation; * Implement requested indentation; * Fix indentation * Capitalize module guards * Edit definition for setModuleGuard * Update pages/reference-smart-account/modules/execTransactionFromModuleReturnData.mdx Co-authored-by: Germán Martínez <[email protected]> * Fix indentation * Edit definition for execTransactionFromModuleReturnData * Update pages/reference-smart-account/modules/execTransactionFromModule.mdx Co-authored-by: Germán Martínez <[email protected]> * Update pages/reference-smart-account/modules/execTransactionFromModule.mdx Co-authored-by: Germán Martínez <[email protected]> * Update pages/reference-smart-account/modules/execTransactionFromModuleReturnData.mdx Co-authored-by: Germán Martínez <[email protected]> * Update pages/reference-smart-account/modules/execTransactionFromModuleReturnData.mdx Co-authored-by: Germán Martínez <[email protected]> * Update pages/reference-smart-account/owners/getThreshold.mdx Co-authored-by: Germán Martínez <[email protected]> * Update pages/reference-smart-account/owners/swapOwner.mdx Co-authored-by: Germán Martínez <[email protected]> * Edit wording * Fix indentation * Update pages/reference-smart-account/modules/enableModule.mdx Co-authored-by: Germán Martínez <[email protected]> * Edit definition for enableModule * Implement requested changes * Update pages/reference-smart-account/transactions/encodeTransactionData.mdx Co-authored-by: Tanay Pant <[email protected]> * Update pages/reference-smart-account/signatures/checkNSignatures.mdx Co-authored-by: Tanay Pant <[email protected]> * Update pages/reference-smart-account/transactions/execTransaction.mdx Co-authored-by: Tanay Pant <[email protected]> * Update pages/reference-smart-account/transactions/execTransaction.mdx Co-authored-by: Tanay Pant <[email protected]> * Update pages/reference-smart-account/modules/execTransactionFromModule.mdx Co-authored-by: Tanay Pant <[email protected]> * Update pages/reference-smart-account/signatures/checkNSignatures.mdx Co-authored-by: Tanay Pant <[email protected]> * Update pages/reference-smart-account/modules/isModuleEnabled.mdx Co-authored-by: Tanay Pant <[email protected]> * Update pages/reference-smart-account/modules/getModulesPaginated.mdx Co-authored-by: Tanay Pant <[email protected]> * Update pages/reference-smart-account/guards/setGuard.mdx Co-authored-by: Tanay Pant <[email protected]> * Update pages/reference-smart-account/guards/setGuard.mdx Co-authored-by: Tanay Pant <[email protected]> * Update pages/reference-smart-account/fallback/receive.mdx Co-authored-by: Tanay Pant <[email protected]> * Update pages/reference-smart-account/signatures/checkNSignatures.mdx Co-authored-by: Tanay Pant <[email protected]> * Update pages/reference-smart-account/signatures/checkNSignatures.mdx Co-authored-by: Tanay Pant <[email protected]> * Implement requested changes * Make `prevOwner` definition more detailed * Fix typos * Update pages/reference-smart-account/signatures/checkSignatures.mdx * Add Smart account version to reference index * Factorize callouts * Factorize callouts * Disambiguate `0`, `0x`, `0x...` and `address(0)` --------- Co-authored-by: Germán Martínez <[email protected]> Co-authored-by: Germán Martínez <[email protected]> Co-authored-by: Tanay Pant <[email protected]>
safe-global · Nov 21, 2024 · b38f3f6 · b38f3f6
1 parent 3a9be1f
commit b38f3f6
Show file tree

Hide file tree

Showing 60 changed files with 2,625 additions and 1 deletion.
diff --git a/.github/styles/config/vocabularies/default/accept.txt b/.github/styles/config/vocabularies/default/accept.txt
@@ -13,6 +13,7 @@
 [Bb]inance
 [Bb]lockchain
 [Bb]lockchains
+[Bb]oolean
 [Bb]undler
 [Bb]undlers
 [Cc]hainlist
@@ -252,7 +253,6 @@ Zora
 address_full_match
 auditable
 auth_code
-boolean
 bytestrings
 checksummed
 createTransaction

diff --git a/components/callouts/ModuleCallout.mdx b/components/callouts/ModuleCallout.mdx
@@ -0,0 +1,7 @@
+import { Callout } from 'nextra/components'
+
+<Callout type='error' emoji='🚨'>
+  Since a guard has the full power to block Safe transaction executions, a
+  broken guard can cause a denial of service for the Safe. Make sure to
+  carefully audit the guard code, and design recovery mechanisms.
+</Callout>
diff --git a/components/callouts/OnlySafeTxCallout.mdx b/components/callouts/OnlySafeTxCallout.mdx
@@ -0,0 +1,5 @@
+import { Callout } from 'nextra/components'
+
+<Callout type='warning'>
+  This action can only be done via a Safe transaction.
+</Callout>
diff --git a/pages/_meta.json b/pages/_meta.json
@@ -35,6 +35,11 @@
     "title": "Advanced",
     "type": "page"
   },
+  "reference-smart-account": {
+    "title": "Smart Account Reference",
+    "type": "page",
+    "display": "hidden"
+  },
   "resource-hub": {
     "title": "Resource Hub",
     "type": "page",

diff --git a/pages/advanced/_meta.json b/pages/advanced/_meta.json
@@ -19,6 +19,10 @@
   },
   "smart-account-audits": "Audits",
   "smart-account-bug-bounty": "Bug Bounty",
+  "smart-account-reference": {
+    "title": "Reference",
+    "href": "/reference-smart-account/overview"
+  },
   "-- Features": {
     "type": "separator",
     "title": "Features"

diff --git a/pages/reference-smart-account/_meta.json b/pages/reference-smart-account/_meta.json
@@ -0,0 +1,23 @@
+{
+  "home": {
+    "title": "← Go Back",
+    "href": "/advanced/smart-account-overview"
+  },
+  "overview": "Overview",
+  "-- Safe Reference": {
+    "type": "separator",
+    "title": "Safe Reference"
+  },
+  "setup": "Setup",
+  "owners": "Owners",
+  "transactions": "Transactions",
+  "modules": "Modules",
+  "guards": "Guards",
+  "fallback": "Fallback Handler",
+  "signatures": "Signatures",
+  "utilities": "Utilities",
+  "events": {
+    "type": "page",
+    "display": "hidden"
+  }
+}
diff --git a/pages/reference-smart-account/events/AddedOwner.mdx b/pages/reference-smart-account/events/AddedOwner.mdx
@@ -0,0 +1,7 @@
+### `AddedOwner`
+
+```solidity
+event AddedOwner(address owner);
+```
+
+Emitted when an owner is added to the Safe.
diff --git a/pages/reference-smart-account/events/ApproveHash.mdx b/pages/reference-smart-account/events/ApproveHash.mdx
@@ -0,0 +1,7 @@
+### `ApproveHash`
+
+```solidity
+event ApproveHash(bytes32 approvedHash, address owner);
+```
+
+Emitted when a hash is approved by an owner.
diff --git a/pages/reference-smart-account/events/ChangedFallbackHandler.mdx b/pages/reference-smart-account/events/ChangedFallbackHandler.mdx
@@ -0,0 +1,7 @@
+### `ChangedFallbackHandler`
+
+```solidity
+event ChangedFallbackHandler(address handler);
+```
+
+Emitted when the Fallback Handler is changed.
diff --git a/pages/reference-smart-account/events/ChangedGuard.mdx b/pages/reference-smart-account/events/ChangedGuard.mdx
@@ -0,0 +1,7 @@
+### `ChangedGuard`
+
+```solidity
+event ChangedGuard(address guard);
+```
+
+Emitted when a guard is set for the Safe.
diff --git a/pages/reference-smart-account/events/ChangedModuleGuard.mdx b/pages/reference-smart-account/events/ChangedModuleGuard.mdx
@@ -0,0 +1,7 @@
+### `ChangedModuleGuard`
+
+```solidity
+event ChangedModuleGuard(address moduleGuard);
+```
+
+Emitted when a Module Guard is set for the Safe.
diff --git a/pages/reference-smart-account/events/ChangedThreshold.mdx b/pages/reference-smart-account/events/ChangedThreshold.mdx
@@ -0,0 +1,7 @@
+### `ChangedThreshold`
+
+```solidity
+event ChangedThreshold(uint256 threshold);
+```
+
+Emitted when the threshold for confirmations is changed.
diff --git a/pages/reference-smart-account/events/DisabledModule.mdx b/pages/reference-smart-account/events/DisabledModule.mdx
@@ -0,0 +1,7 @@
+### `DisabledModule`
+
+```solidity
+event DisabledModule(address module);
+```
+
+Emitted when a module is disabled for the Safe.
diff --git a/pages/reference-smart-account/events/EnabledModule.mdx b/pages/reference-smart-account/events/EnabledModule.mdx
@@ -0,0 +1,7 @@
+### `EnabledModule`
+
+```solidity
+event EnabledModule(address module);
+```
+
+Emitted when a module is enabled for the Safe.
diff --git a/pages/reference-smart-account/events/ExecutionFailure.mdx b/pages/reference-smart-account/events/ExecutionFailure.mdx
@@ -0,0 +1,7 @@
+### `ExecutionFailure`
+
+```solidity
+event ExecutionFailure(bytes32 txHash, uint256 payment);
+```
+
+Emitted when a transaction fails.
diff --git a/pages/reference-smart-account/events/ExecutionFromModuleFailure.mdx b/pages/reference-smart-account/events/ExecutionFromModuleFailure.mdx
@@ -0,0 +1,7 @@
+### `ExecutionFromModuleFailure`
+
+```solidity
+event ExecutionFromModuleFailure(address module);
+```
+
+Emitted when a transaction executed by a module fails.
diff --git a/pages/reference-smart-account/events/ExecutionFromModuleSuccess.mdx b/pages/reference-smart-account/events/ExecutionFromModuleSuccess.mdx
@@ -0,0 +1,7 @@
+### `ExecutionFromModuleSuccess`
+
+```solidity
+event ExecutionFromModuleSuccess(address to, uint256 value, bytes data);
+```
+
+Emitted when a transaction executed by a module succeeds.
diff --git a/pages/reference-smart-account/events/ExecutionSuccess.mdx b/pages/reference-smart-account/events/ExecutionSuccess.mdx
@@ -0,0 +1,7 @@
+### `ExecutionSuccess`
+
+```solidity
+event ExecutionSuccess(bytes32 txHash, uint256 payment);
+```
+
+Emitted when a transaction is executed successfully.
diff --git a/pages/reference-smart-account/events/RemovedOwner.mdx b/pages/reference-smart-account/events/RemovedOwner.mdx
@@ -0,0 +1,7 @@
+### `RemovedOwner`
+
+```solidity
+event RemovedOwner(address owner);
+```
+
+Emitted when an owner is removed from the Safe.
diff --git a/pages/reference-smart-account/events/SafeReceived.mdx b/pages/reference-smart-account/events/SafeReceived.mdx
@@ -0,0 +1,7 @@
+### `SafeReceived`
+
+```solidity
+event SafeReceived(address sender, uint256 value)
+```
+
+Emitted when the Safe contract receives a payment.
diff --git a/pages/reference-smart-account/events/SafeSetup.mdx b/pages/reference-smart-account/events/SafeSetup.mdx
@@ -0,0 +1,13 @@
+### `SafeSetup`
+
+```solidity
+event SafeSetup(
+  address initiator,
+  address[] owners,
+  uint256 threshold,
+  address initializer,
+  address fallbackHandler
+);
+```
+
+Emitted when the Safe is set up.
diff --git a/pages/reference-smart-account/events/SignMsg.mdx b/pages/reference-smart-account/events/SignMsg.mdx
@@ -0,0 +1,7 @@
+### `SignMsg`
+
+```solidity
+event SignMsg(bytes32 msgHash);
+```
+
+Emitted when a message is signed by an owner.
diff --git a/pages/reference-smart-account/fallback/_meta.json b/pages/reference-smart-account/fallback/_meta.json
@@ -0,0 +1,5 @@
+{
+  "fallback": "fallback",
+  "receive": "receive",
+  "setFallbackHandler": "setFallbackHandler"
+}
diff --git a/pages/reference-smart-account/fallback/fallback.mdx b/pages/reference-smart-account/fallback/fallback.mdx
@@ -0,0 +1,32 @@
+import { Tabs } from 'nextra/components'
+import SafeReceived from '../events/SafeReceived.mdx'
+
+# `fallback`
+
+This function emits the [`SafeReceived`](./fallback/receive.mdx#safereceived) event when it receives a payment.
+
+## Usage
+
+{/* <!-- vale off --> */}
+
+<Tabs items={['example.sol']}>
+  <Tabs.Tab>
+    ```solidity
+    interface ISafe {
+        fallback() external;
+    }
+
+    contract Example {
+        function example() ... {
+            (ISafe safe).fallback();
+        }
+    }
+    ```
+  </Tabs.Tab>
+</Tabs>
+
+{/* <!-- vale on --> */}
+
+## Events
+
+<SafeReceived />
diff --git a/pages/reference-smart-account/fallback/receive.mdx b/pages/reference-smart-account/fallback/receive.mdx
@@ -0,0 +1,30 @@
+import { Tabs } from 'nextra/components'
+import SafeReceived from '../events/SafeReceived.mdx'
+
+# `receive`
+
+Receive function accepts native token transactions.
+
+## Usage
+
+{/* <!-- vale off --> */}
+
+<Tabs items={['example.sol']}>
+  <Tabs.Tab>
+    ```solidity
+    interface ISafe {
+        receive() external payable;
+    }
+
+    contract Example {
+        function example() ... {
+            (ISafe safe).receive();
+        }
+    }
+    ```
+  </Tabs.Tab>
+</Tabs>
+
+## Events
+
+<SafeReceived />
diff --git a/pages/reference-smart-account/fallback/setFallbackHandler.mdx b/pages/reference-smart-account/fallback/setFallbackHandler.mdx
@@ -0,0 +1,51 @@
+import { Tabs, Callout } from 'nextra/components'
+import ChangedFallbackHandler from '../events/ChangedFallbackHandler.mdx'
+
+# `setFallbackHandler`
+
+Set Fallback Handler to `handler` for the Safe.
+
+<Callout type='warning'>
+  Only fallback calls without value and with data will be forwarded. This can
+  only be done via a Safe transaction. Cannot be set to the Safe itself.
+</Callout>
+
+## Usage
+
+{/* <!-- vale off --> */}
+
+<Tabs items={['example.sol']}>
+  <Tabs.Tab>
+    ```solidity
+    interface ISafe {
+        function setFallbackHandler(address handler) external;
+    }
+
+    contract Example {
+        function example() ... {
+            (ISafe safe).setFallbackHandler(0x...);
+        }
+    }
+    ```
+  </Tabs.Tab>
+</Tabs>
+
+{/* <!-- vale on --> */}
+
+## Parameters
+
+### `handler`
+
+- **Type:** `address`
+
+Contract to handle fallback calls.
+
+```solidity focus=2
+(ISafe safe).setFallbackHandler(
+    0x...
+);
+```
+
+## Events
+
+<ChangedFallbackHandler />
diff --git a/pages/reference-smart-account/guards/_meta.json b/pages/reference-smart-account/guards/_meta.json
@@ -0,0 +1,4 @@
+{
+  "setGuard": "setGuard",
+  "setModuleGuard": "setModuleGuard"
+}
diff --git a/pages/reference-smart-account/guards/setGuard.mdx b/pages/reference-smart-account/guards/setGuard.mdx
@@ -0,0 +1,49 @@
+import { Tabs, Callout } from 'nextra/components'
+import ChangedGuard from '../events/ChangedGuard.mdx'
+import OnlySafeTxCallout from '../../../components/callouts/OnlySafeTxCallout.mdx'
+import ModuleCallout from '../../../components/callouts/ModuleCallout.mdx'
+
+# `setGuard`
+
+Set Transaction Guard `guard` that checks transactions before execution.
+
+<OnlySafeTxCallout />
+<ModuleCallout />
+
+## Usage
+
+{/* <!-- vale off --> */}
+
+<Tabs items={['example.sol']}>
+  <Tabs.Tab>
+    ```solidity
+    interface ISafe {
+        function setGuard(address guard) external;
+    }
+
+    contract Example {
+        function example() ... {
+            (ISafe safe).setGuard(0x...);
+        }
+    }
+    ```
+  </Tabs.Tab>
+</Tabs>
+
+## Parameters
+
+### `guard`
+
+- **Type:** `address`
+
+The address of the guard to be used, or `address(0)` to disable the guard.
+
+```solidity focus=2
+(ISafe safe).setGuard(
+    0x...
+);
+```
+
+## Events
+
+<ChangedGuard />