diff --git a/.github/styles/config/vocabularies/default/accept.txt b/.github/styles/config/vocabularies/default/accept.txt index c30eb78f..b0e96ca7 100644 --- a/.github/styles/config/vocabularies/default/accept.txt +++ b/.github/styles/config/vocabularies/default/accept.txt @@ -202,6 +202,7 @@ Safe Module Safe Modules Safe [Ss]mart [Aa]ccount Safe Transaction Service +Safenet Safe{Core} Account Abstraction SDK Safe{DAO} Sei @@ -228,6 +229,7 @@ Telos Tenet ThunderCore Transaction Service +Transciever U2U UI Kit Ultron diff --git a/assets/safenet-account.png b/assets/safenet-account.png new file mode 100644 index 00000000..8fe59c3b Binary files /dev/null and b/assets/safenet-account.png differ diff --git a/assets/safenet-chains.png b/assets/safenet-chains.png new file mode 100644 index 00000000..1ee499e2 Binary files /dev/null and b/assets/safenet-chains.png differ diff --git a/assets/safenet-highlevel-overview.png b/assets/safenet-highlevel-overview.png new file mode 100644 index 00000000..a505d000 Binary files /dev/null and b/assets/safenet-highlevel-overview.png differ diff --git a/assets/safenet-introduction.png b/assets/safenet-introduction.png new file mode 100644 index 00000000..db1a4536 Binary files /dev/null and b/assets/safenet-introduction.png differ diff --git a/assets/safenet-protocol-overview.png b/assets/safenet-protocol-overview.png new file mode 100644 index 00000000..4053ba47 Binary files /dev/null and b/assets/safenet-protocol-overview.png differ diff --git a/assets/safenet-transaction-phases.png b/assets/safenet-transaction-phases.png new file mode 100644 index 00000000..e0dc7a5d Binary files /dev/null and b/assets/safenet-transaction-phases.png differ diff --git a/pages/_meta.json b/pages/_meta.json index 8eb6f6ee..c18afc06 100644 --- a/pages/_meta.json +++ b/pages/_meta.json @@ -3,6 +3,10 @@ "title": "Home", "type": "page" }, + "safenet": { + "title": "Safenet", + "type": "page" + }, "sdk": { "title": "SDK", "type": "page" diff --git a/pages/safenet/_meta.json b/pages/safenet/_meta.json new file mode 100644 index 00000000..0c43fada --- /dev/null +++ b/pages/safenet/_meta.json @@ -0,0 +1,24 @@ +{ + "-- introduction": { + "type": "separator", + "title": "Introduction" + }, + "overview": "Overview", + "introduction": "Why Safenet", + "chains": "Multi-Chain", + "architecture": "Architecture", + "safenet-account": "Safenet Account", + "safenet-transaction": "Safenet Transaction", + "optimistic-validity-proof": "Optimistic Validity Proof", + "-- details": { + "type": "separator", + "title": "Details" + }, + "core-components": { + "type": "separator", + "title": "Core Components" + }, + "concepts": "Concepts", + "protocol": "Protocol" +} + \ No newline at end of file diff --git a/pages/safenet/architecture.mdx b/pages/safenet/architecture.mdx new file mode 100644 index 00000000..494d4204 --- /dev/null +++ b/pages/safenet/architecture.mdx @@ -0,0 +1,24 @@ +# Architecture + +Safenet is a hybrid network that combines on-chain smart contracts across [multiple blockchains](./chains.mdx) and rollups with a decentralized network of off-chain actors that process transactions across these chains. + +![Safenet-highlevel-overview](../../assets/safenet-highlevel-overview.png) + +Safenet is composed of the following key components: + +### Safe Smart Accounts +Each Safenet Account is spread across multiple blockchains, with one Safe Smart Account per chain. +Every Safenet Account is anchored by a [Home Safe Smart Account](./protocol/home-safe.mdx) deployed on the Ethereum mainnet. + +### Safenet Smart Contracts +These contracts are deployed on every supported chain, with the Ethereum mainnet as the primary hub for configuration and coordination. + +### Decentralized off-chain actors +Safenet introduces several key roles for off-chain transaction processing: + * **[Processors](./core-components/processor.mdx)**: Handle the heavy lifting of processing, signing, and [settling](./concepts/settlement.mdx) [transactions](./safenet-transaction.mdx). + * **[Validators](./core-components/validator.mdx)**: Ensure the security and correctness of transactions by validating the work of processors. + * **[Liquidity Providers](./core-components/liquidity-provider.mdx)**: Supply liquidity on-chain to facilitate seamless transactions across different blockchains. + +### External Bridges +External bridges are only used for dispute resolution when a validator challenges a Safenet transaction. + diff --git a/pages/safenet/chains.mdx b/pages/safenet/chains.mdx new file mode 100644 index 00000000..640bc9ca --- /dev/null +++ b/pages/safenet/chains.mdx @@ -0,0 +1,33 @@ +# Multi-Chain + +Safenet provides a unified user experience over multiple blockchains. +Safenet connects the liquidity of multiple chains, enabling users to spend their assets on any supported chain without the need for traditional bridging. +A Safenet transaction can happen on one or multiple chains. +In a [Safenet transaction](./safenet-transaction.mdx), chains can take up the following roles: + +![Safenet-chains](../../assets/safenet-chains.png) + +### Spend Chain + +This is where the user wants to execute an action. +Safenet makes sure the required funds are available instantly on the spend chain. +Another name is *target chain*. + +### Debit Chain + +This is where a user owns the required assets for the action. +The user does not have to select the debit chain, as Safenet finds the required funds over all connected chains. +Another name is *source chain*. + +### Home Chain + +Safenet uses Ethereum Mainnet as the home chain for configuration and coordination. +For example, the configurable set of safety guarantees for a user's [Safenet account](./safenet-account.mdx) is stored on Ethereum Mainnet. + +## Chains vary per transaction + +For example, when a user wants to execute a transaction to spend funds on Optimism, while the funds are on Gnosis Chain, the spend chain will be Optimism, and the debit chain will be Gnosis Chain for this particular transaction. + +When a user wants to execute a transaction on the same chain where the funds are, the spend chain and debit chain are the same. + +Ethereum mainnet will always be Safenet's home chain. \ No newline at end of file diff --git a/pages/safenet/concepts/_meta.json b/pages/safenet/concepts/_meta.json new file mode 100644 index 00000000..f46fc4e3 --- /dev/null +++ b/pages/safenet/concepts/_meta.json @@ -0,0 +1,8 @@ +{ + "settlement": "Settlement", + "challenge": "Challenge", + "attestation": "Attestation", + "guarantee": "Guarantee", + "resource-lock": "Resource Lock", + "universal-balance": "Universal Balance" +} \ No newline at end of file diff --git a/pages/safenet/concepts/attestation.mdx b/pages/safenet/concepts/attestation.mdx new file mode 100644 index 00000000..a4fc1eb4 --- /dev/null +++ b/pages/safenet/concepts/attestation.mdx @@ -0,0 +1,11 @@ +# Attestation + +The [processor](../core-components/processor.mdx) uses an attestation to prove the validity of a [settlement](../concepts/settlement.mdx). +It serves as a cryptographic proof that the fulfillment of a Safenet [transaction](../safenet-transaction.mdx) is valid under the specific conditions defined by the user's configured [guarantees](../concepts/guarantee.mdx). + +The attestation has to be sent from the spend [chain](../chains.mdx) to the home chain, where it is validated by the [guarantee engine](../protocol/guarantee-engine.mdx). +It is then sent from the guarantee engine to the [settlement engine](../protocol/settlement-engine.mdx) on the debit chain to finalize the settlement. +The attestation data is sent through external bridges, which can be costly and slow. + +The processor has to provide the attestation when a [validator](../core-components/validator.mdx) [challenges](challenge.mdx) a [settlement](../concepts/settlement.mdx). +The processor can voluntarily provide the attestation with the settlement request to ensure the settlement is processed directly. diff --git a/pages/safenet/concepts/challenge.mdx b/pages/safenet/concepts/challenge.mdx new file mode 100644 index 00000000..d71f75e1 --- /dev/null +++ b/pages/safenet/concepts/challenge.mdx @@ -0,0 +1,5 @@ +# Challenge + +A [validator](../core-components/validator.mdx) can challenge the [settlement](./settlement.mdx) request of a [processor](../core-components/processor.mdx). +In this case, the processor has to provide an [attestation](./attestation.mdx) to prove the validity of the [transaction](../safenet-transaction.mdx). +If the processor fails to provide the attestation, the settlement process is considered invalid, and the validator can slash the processor's stake to reimburse the [liquidity provider](../core-components/liquidity-provider.mdx). \ No newline at end of file diff --git a/pages/safenet/concepts/guarantee.mdx b/pages/safenet/concepts/guarantee.mdx new file mode 100644 index 00000000..2bce4817 --- /dev/null +++ b/pages/safenet/concepts/guarantee.mdx @@ -0,0 +1,47 @@ +# Guarantee + +One of Safenet's core value propositions is the **enhanced security** it provides to users. +This security goes beyond the simple mechanisms of pre-funding and settlement; it is deeply embedded in Safenet's architecture through its **guarantee system**, which enforces specific conditions before transactions can be executed. +These guarantees protect users from various external risks, including hacks, phishing attacks, address poisoning, and other forms of fraud. + +Safenet introduces two types of guarantees, each serving a distinct purpose: + +## Core Guarantees + +Core guarantees are integral to Safenet's security model and form the foundation of the system. +They ensure the integrity of the pre-funding and settlement process, protecting users from malicious actors, such as a processor attempting to execute invalid transactions. +These guarantees are mandatory and automatically applied to all Safenet transactions. + +### Examples of core Guarantees + +- **Transaction Validity**: Ensures that all transactions executed by the processor are valid and follow the rules set by Safenet's validity-proof engine. +- **Settlement Fraud Protection**: Enables validators to intervene if they detect fraudulent or incorrect transactions during the settlement process. + +## User-Configured Guarantees + +In addition to the mandatory core guarantees, Safenet allows users to enhance their security by customizing transaction rules through **user-configured guarantees**. +These guarantees offer additional protection against external threats, giving users more control over how and where their funds are sent. + +User-configured guarantees are optional and tailored to the user's specific needs. +They provide additional security layers that can be applied based on personal risk tolerance and transaction preferences. + +### Examples of User-Configured Guarantees + +- **Recipient Signature Enforcement**: Requires the recipient to sign a message before the transaction is executed, ensuring that funds are sent to the correct address (for example, to `0xb0b1` instead of a similar, malicious `0xbab1` address to prevent address poisoning). +- **Account Type Restrictions**: Limits the transaction to approved types, such as externally owned accounts (EOA) or smart accounts, preventing funds from being sent to unknown or exotic accounts. +- **Protocol Whitelisting**: Ensures that the transaction interacts only with trusted protocols, reducing the risk of sending funds to malicious or unverified contracts. +- **Third-Party Approval**: Requires the transaction to be signed by a trusted third party (for example, [BlockAid](https://blockaid.xyz)) to protect against fraud. +- **Spending Limits**: Enforces a daily spending limit, restricting the amount that can be transferred in a single transaction and providing protection against unauthorized large transfers. +- **Address Book Validation**: Ensures that the recipient is part of an on-chain address book, adding another layer of verification to prevent sending funds to unintended recipients. + +If a processor executes a transaction that violates one of these guarantees (for instance, by sending funds to an incorrect address), the transaction can be challenged, and the user can be refunded. +This functions similarly to a chargeback on a credit card, where the lock on the funds is removed, and the transaction does not [settle](./settlement.mdx), leaving the user's funds in the account. + +## Technical details + +A guarantee is implemented by a [guarantee implementation](../protocol/guarantee-implementation.mdx), registered within the [Guarantee Engine](../protocol/guarantee-engine.mdx) on the Home Chain by the [SafeDAO](../protocol/safe-dao.mdx), and installed individually by an [end user](../core-components/end-user.mdx). +They prove that a Safenet transaction is valid under the specific conditions defined by the user's configured guarantees. + +Unlike atomic operations proven in a single Ethereum transaction, guarantees in Safenet are not necessarily atomic. +This allows for more complex guarantees, such as nested optimistic validity zero-knowledge (ZK) proofs, which can be used to ensure the validity of transactions in a more scalable and secure manner. + diff --git a/pages/safenet/concepts/resource-lock.mdx b/pages/safenet/concepts/resource-lock.mdx new file mode 100644 index 00000000..590c9dda --- /dev/null +++ b/pages/safenet/concepts/resource-lock.mdx @@ -0,0 +1,8 @@ +# Resource lock + +The Resource Lock is a mechanism in Safenet that ensures the availability of user funds for transactions by locking a portion of the [End User's](../core-components/end-user.mdx) assets. +This lock guarantees that sufficient resources are set aside to [settle](./settlement.mdx) transactions securely and efficiently. + +The resource lock is issued on the funds on the debit [chain](../chains.mdx) before the fulfillment is done on the spend chain. The lock is maintained until the transaction is settled on the debit chain. + +The [processor](../core-components/processor.mdx) manages the resource lock, ensuring that no transactions can move funds out of the End User's Safe Smart Account on the debit chain while the resource lock is in effect. diff --git a/pages/safenet/concepts/settlement.mdx b/pages/safenet/concepts/settlement.mdx new file mode 100644 index 00000000..74970f2a --- /dev/null +++ b/pages/safenet/concepts/settlement.mdx @@ -0,0 +1,136 @@ +import { Callout, Steps, Tabs } from 'nextra/components' + +# Settlement + +Settlement is the process by which a [processor](../core-components/processor.mdx) debits funds from a [Safenet account](../safenet-account.mdx) to repay the [liquidity provider](../core-components/liquidity-provider.mdx) for the short-term loan (pre-funding) used in a [Safenet transaction](../safenet-transaction.mdx). + +The [settlement engine](../protocol/settlement-engine.mdx) handles debit requests on the debit [chain](../chains.mdx) by transferring funds from the Safenet Safe to a [beneficiary](../protocol/beneficiary.mdx) designated by the liquidity provider. +This occurs after the liquidity provider has fronted funds on the spend chain. + +Once settlement is initiated, a delay period begins, during which [validators](../core-components/validator.mdx) can verify the settlement's correctness and challenge it if necessary. +If no challenge is made during this period, the processor completes the settlement, debiting the Safe and transferring the funds to the beneficiary, which includes repayment of the liquidity provision and relayer fees. + +If a validator [challenges](../concepts/challenge.mdx) the settlement, the cross-chain challenge process begins: + +## Challenge Process + + + +### Challenge Initiation +The validator initiates a transaction with the settlement engine to start a challenge on the debit chain, with a separate challenge delay. +During this delay, the processor must prove the settlement's correctness. + +### Correctness Proof +The processor sends an [attestation](./attestation.mdx) from the spend chain (where the Safenet transaction was executed) to the home chain to validate the settlement. + +### Challenge Resolution +The processor proves the settlement's validity to the guarantee engine on the home chain, which then informs the settlement contract on the debit chain: + * If the settlement is validated, the settlement can proceed immediately, bypassing the remaining settlement delay. + * If the processor fails to prove the settlement's validity, the challenge delay expires, and the settlement is deemed invalid, meaning it can never be executed. + +When a challenge is successful, the processor or liquidity provider loses the fronted funds, and the user does not pay anything. +The user could benefit from the outgoing transaction. + + + +## Flow Diagrams + +### Happy Flow + +```mermaid +sequenceDiagram + box MVP Processor + actor P as Processor + actor LP as Liquidity Provider + end + actor V as Validator + participant S as Settlement Engine + participant A as Account + + P->>S: settle (WITH COLLATERAL Ξ) + Note over S: Settlement Delay... + V->>V: check settlement correctness + Note over S: ...Settlement Delay + P->>+S: executeSettlement + A-->>LP: transferFrom(Account, Liquidity Provider) + deactivate S +``` + +The happy flow diagram illustrates the process of a successful settlement. +The processor initiates the settlement process by debiting the Safe and transferring funds to the beneficiary. +The validator verifies the settlement's correctness and, if no challenge is made, the settlement is completed. + +### Sad Flow + +```mermaid +sequenceDiagram + box MVP Processor + actor P as Processor + actor LP as Liquidity Provider + end + actor V as Validator + box rgb(255,165,0,0.2) + participant G as Guarantee Engine
(HOME CHAIN) + end + participant B as Bridge + participant S as Settlement Engine + participant A as Account + + P->>S: settle + Note over S: Settlement Delay... + V->>V: check settlement correctness + + opt Incorrect Settlement + V->>S: challenge (WITH COLLATERAL Ξ) + end + + alt Correctness Proven + G-->>+B: correctnessProven + B->>S: correctnessProven + A-->>LP: transferFrom(Account, Liquidity Provider) + deactivate B + else + Note over S: ...Settlement Delay + P-->>P: punished: loses fronted funds + end +``` + +The sad flow diagram illustrates the process of a failed settlement. +The validator challenges the settlement, and the processor must prove the settlement's validity. +If the processor fails to provide proof, the settlement is deemed invalid, and the funds are not transferred. + +### Correctness Proof (Attestation) + +```mermaid +sequenceDiagram + box MVP Processor + actor P as Processor + end + box rgb(255,165,0,0.2) + participant E as Entry Point
(SPEND CHAIN) + participant S as Settlement Engine
(DEBIT CHAIN) + end + participant TS as Transceiver
for Spend Chain + participant TD as Transceiver
for Debit Chain + participant G as Guarantee Engine + participant G1 as Guarantee 1... + participant GN as ...Guarantee N + + P->>+E: sendReceipt() + E-->>+TS: receipt + deactivate E + TS->>G: safenetReceipt() + deactivate TS + + P->>+G: prove() + G->>G1: checkGuarantee() + G->>GN: checkGuarantee() + G->>-TD: correctnessProven() + TD-->>S: correctnessProven +``` + +The correctness proof diagram illustrates the process of proving the settlement's validity. +The processor sends information from the spend chain to the home chain, where the guarantee engine validates the settlement. +If the settlement is proven correct, the settlement can proceed immediately. + +The processor can voluntarily provide the attestation at the moment of settlement to bypass the challenge delay and ensure a faster settlement process. \ No newline at end of file diff --git a/pages/safenet/concepts/universal-balance.mdx b/pages/safenet/concepts/universal-balance.mdx new file mode 100644 index 00000000..b3a82773 --- /dev/null +++ b/pages/safenet/concepts/universal-balance.mdx @@ -0,0 +1,9 @@ +# Universal Balance + +Universal Balance in Safenet refers to a unified account balance across multiple supported [blockchains](../chains.mdx). +It allows users to interact with any chain without manually bridging assets between chains. + +Rather than holding separate balances on each chain, the Universal Balance aggregates the user's funds across all chains and manages liquidity dynamically. +This enables chain abstraction, with the user spending from a single balance while the underlying system handles the complexities of settling funds on different chains. + +The Universal Balance simplifies user experience by removing the need for manual asset transfers and allowing instant liquidity access across chains. \ No newline at end of file diff --git a/pages/safenet/core-components/_meta.json b/pages/safenet/core-components/_meta.json new file mode 100644 index 00000000..21205651 --- /dev/null +++ b/pages/safenet/core-components/_meta.json @@ -0,0 +1,5 @@ +{ + "processor": "Processor", + "validator": "Validator", + "liquidity-provider": "Liquidity Provider" +} \ No newline at end of file diff --git a/pages/safenet/core-components/end-user.mdx b/pages/safenet/core-components/end-user.mdx new file mode 100644 index 00000000..d340783b --- /dev/null +++ b/pages/safenet/core-components/end-user.mdx @@ -0,0 +1,4 @@ +# End User + +The End User is an individual with one or more [Safenet accounts](../safenet-account.mdx), using [Safe\{Wallet\}](https://app.safe.global/welcome) to interact with Safenet. + diff --git a/pages/safenet/core-components/liquidity-provider.mdx b/pages/safenet/core-components/liquidity-provider.mdx new file mode 100644 index 00000000..268606b1 --- /dev/null +++ b/pages/safenet/core-components/liquidity-provider.mdx @@ -0,0 +1,3 @@ +# Liquidity Provider + +The Liquidity Provider supplies assets at a premium for [Safenet transactions](../safenet-transaction.mdx). They front the necessary funds and are reimbursed an additional fee during [settlement](../concepts/settlement.mdx). \ No newline at end of file diff --git a/pages/safenet/core-components/processor.mdx b/pages/safenet/core-components/processor.mdx new file mode 100644 index 00000000..c81c9278 --- /dev/null +++ b/pages/safenet/core-components/processor.mdx @@ -0,0 +1,12 @@ +# Processor + +The Processor is a service that executes [transactions](../safenet-transaction.mdx) on behalf of the End User when specific conditions are met: + +* The [End User](./end-user.mdx) is registered with Safenet (locking assets through a [Guard](../protocol/guard.mdx) acting as a co-signing). +* The End User has sufficient locked funds to settle transactions across one or more [chains](../chains.mdx). +* The End User's [guarantees](../concepts/guarantee.mdx) are validated. +* The Processor or [liquidity provider](./liquidity-provider.mdx) has enough liquidity to pre-fund the End User's account on the spend chain. + +After fulfillment, the Processor handles the [settlements](../concepts/settlement.mdx) by initiating an optimistic settlement process. +This process, subject to delay, can be [challenged](../concepts/challenge.mdx) by a [Validator](./validator.mdx). +The Processor refunds itself or the liquidity provider by pulling funds from the End User's account. \ No newline at end of file diff --git a/pages/safenet/core-components/safenet-protocol.mdx b/pages/safenet/core-components/safenet-protocol.mdx new file mode 100644 index 00000000..cff1db6b --- /dev/null +++ b/pages/safenet/core-components/safenet-protocol.mdx @@ -0,0 +1,6 @@ +# Safenet Protocol + +The Safenet Protocol consists of smart contracts that enable trustless communication between all parties. +Both contract variables and events serve as communication channels. + +The [Safenet Protocol](../protocol/overview.mdx) section documents the different smart contracts. \ No newline at end of file diff --git a/pages/safenet/core-components/transaction-service.mdx b/pages/safenet/core-components/transaction-service.mdx new file mode 100644 index 00000000..5fb3054d --- /dev/null +++ b/pages/safenet/core-components/transaction-service.mdx @@ -0,0 +1,7 @@ +# Transaction Service + +The Transaction Service operates across all Safe-supported [chains](../chains.mdx) and indexes Safe Smart Accounts and transactions. +In Safenet, it functions as a **shared mempool**, recording transactions that the [processor](./processor.mdx) needs to execute. + +The Event Service works with the Transaction Service, triggering WebHooks for specific Safe events. + diff --git a/pages/safenet/core-components/validator.mdx b/pages/safenet/core-components/validator.mdx new file mode 100644 index 00000000..bc5cf09b --- /dev/null +++ b/pages/safenet/core-components/validator.mdx @@ -0,0 +1,4 @@ +# Validator + +The Validator ensures that the [Processor](./processor.mdx) correctly [settles](../concepts/settlement.mdx) transactions as per the guarantees signed by the [End User](./end-user.mdx). +If a settlement is invalid or fraudulent, the Validator can challenge it, initiating a dispute that requires the Processor to [prove](../concepts/attestation.mdx) the transaction's validity. \ No newline at end of file diff --git a/pages/safenet/introduction.mdx b/pages/safenet/introduction.mdx new file mode 100644 index 00000000..b5ac2af7 --- /dev/null +++ b/pages/safenet/introduction.mdx @@ -0,0 +1,29 @@ +## Why Safenet? + +Blockchains have the potential to become society's global settlement layer, enabling seamless coordination, transactions, and a more interconnected world. Achieving this vision means moving the world's entire GDP on-chain. + +However, several significant challenges need to be addressed: + +* **Fragmentation**: Different Layer 1 and Layer 2 solutions form isolated ecosystems, and blockchains are not yet fully integrated with traditional financial networks. +* **Latency**: Cross-chain transactions face delays due to bridging mechanisms and varying block times. +* **Complexity**: Security concerns and complicated user experiences hinder mainstream adoption. +* **Interoperability**: Blockchains are not natively compatible with the traditional financial system. + +## What is Safenet? + +Safenet is not a blockchain or layer 2 nor a bridge. +It's an optimistic, validity-proof transaction processing network anchored on the Ethereum mainnet. +It works on top of any existing or future chains and even connects on-chain and off-chain networks like Visa or centralized exchanges. +It separates transaction fulfillment from settlement, allowing users to interact with any supported blockchain protocol. +It uses [optimistic validity proofs](./optimistic-validity-proof.mdx) to ensure every transaction adheres to a set of security [guarantees](./concepts/guarantee.mdx). + +By offloading security and cross-chain bridging responsibilities to a network of processors, validators, and liquidity providers, Safenet eliminates the complexity of cross-chain interactions. Users gain the ability to transact across blockchains with unprecedented speed and security—without needing to worry about the underlying infrastructure. + +## What does Safenet enable? + +Safenet enables users to spend their funds on any supported blockchain without a delay and without traditional bridging. +It ensures that users fully control their assets and the level of transaction protection they desire. + +Behind the scenes, Safenet handles the settlement by coordinating funds from the various blockchains where the user holds assets. + +For the user, all they experience is a seamless, lightning-fast transaction. \ No newline at end of file diff --git a/pages/safenet/optimistic-validity-proof.mdx b/pages/safenet/optimistic-validity-proof.mdx new file mode 100644 index 00000000..cb6817b3 --- /dev/null +++ b/pages/safenet/optimistic-validity-proof.mdx @@ -0,0 +1,27 @@ +# Optimistic Validity Proof + +Optimistic validity proofs are the core concept of Safenet, which enables the centralized world's speed and convenience with the decentralized world's security and self-custody. + +They ensure that transactions are fast and gas-efficient in the vast majority of cases (the happy path) while still providing security [guarantees](./concepts/guarantee.mdx). +Only in rare dispute cases does the system return to a slow and gas-intense process. + +Optimistic validity proofs work similarly to [slashing](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/rewards-and-penalties/#slashing) in proof-of-stake networks. +The processors risk losing their stake or pre-funded funds when they process invalid transactions. +The validator risks losing their collateral when they challenge valid transactions. + +## Effects on transaction speed and gas efficiency + +* A [Safenet transaction's](./safenet-transaction.mdx) **fulfillment is always fast and gas-efficient**, because neither the [processor](./core-components/processor.mdx) nor the [liquidity provider](./core-components/liquidity-provider.mdx) have the incentive to send out funds to a user that they would not receive back (and the processor does not want to lose its stakes). +* The **[settlement](./concepts/settlement.mdx) is gas-efficient but slightly slower**, as it has a [challenge](./concepts/challenge.mdx) delay, in which a [validator](./core-components/validator.mdx) can challenge the settlement request. +It is gas-efficient, as the processor does not have to send a correctness proof ([attestation](./concepts/attestation.mdx)) initially (but is free to do so). +* Only a **challenged settlement is gas-intense and slow**. When a validator challenges the settlement request, the processor has to send an attestation. +The attestation has to be sent from the spend chain to the debit chain with a cross-chain bridge, which is costly and slow. + +## Economic incentives + +Optimistic validity proofs build on the following economic incentives: + +* The processor has an incentive to process transactions correctly, as they risk losing funds when they process invalid transactions. +* The stake of the processor secures the liquidity provider. +* The validator has an incentive to challenge invalid transactions, as they can earn a fee. +They have an incentive not to challenge valid transactions, as they risk losing funds if the transaction is valid. \ No newline at end of file diff --git a/pages/safenet/overview.mdx b/pages/safenet/overview.mdx new file mode 100644 index 00000000..0b6e725e --- /dev/null +++ b/pages/safenet/overview.mdx @@ -0,0 +1,21 @@ +![Safenet-introduction](../../assets/safenet-introduction.png) + +# Safenet Overview + +Safe announced Safenet on December 3rd, 2024. These docs describe the current state of technical vision. The current state of implementation can be found in the roadmap. + +The docs consist of the following sections: + +**[Introduction](./introduction.mdx)**: Provides a brief overview of Safenet, its high-level architecture, and the flow of a Safenet transaction. Reading this part will explain why Safe builds Safenet. It is recommended to start reading these docs with the Introduction in the given order. This page is part of the Introduction. + +## Details + +**[Core Components](./core-components/processor.mdx)**: Provides details of the different components of Safenet. Reading this part will provide an understanding of what Safenet is composed of. + +**[Concepts](./concepts/settlement.mdx)**: Describes the different concepts and procedures of Safenet. Reading this part will provide an understanding of how Safenet works. + +**[Protocol](./protocol/overview.mdx)**: Describes the smart contracts and their role in the Safenet protocol. Reading this part will provide an understanding of Safenet's technical details. + +## Next steps + +It is recommended to use the arrow buttons at the bottom of this page to read the introduction section in the given order. \ No newline at end of file diff --git a/pages/safenet/protocol/_meta.json b/pages/safenet/protocol/_meta.json new file mode 100644 index 00000000..cd21c3ea --- /dev/null +++ b/pages/safenet/protocol/_meta.json @@ -0,0 +1,13 @@ +{ + "overview": "Overview", + "settlement-engine": "Settlement Engine", + "transceiver": "Transceiver", + "guarantee-engine": "Guarantee Engine", + "guarantee-implementation": "Guarantee Implementation", + "home-safe": "Home Safe", + "entry-point": "Entry Point", + "guard": "Guard", + "beneficiary": "Beneficiary", + "relayer": "Relayer", + "safe-dao": "Safe DAO" +} diff --git a/pages/safenet/protocol/beneficiary.mdx b/pages/safenet/protocol/beneficiary.mdx new file mode 100644 index 00000000..f0bfbe61 --- /dev/null +++ b/pages/safenet/protocol/beneficiary.mdx @@ -0,0 +1,4 @@ +# Beneficiary + +The Beneficiary refers to the account receiving the debited funds during the [settlement](../concepts/settlement.mdx) process. +In more complex scenarios, the [processor](../core-components/processor.mdx) may collect all debited funds and distribute them to cover processor fees, [liquidity provider](../core-components/liquidity-provider.mdx) reimbursements, and [relayer](./relayer.mdx) compensation. \ No newline at end of file diff --git a/pages/safenet/protocol/entry-point.mdx b/pages/safenet/protocol/entry-point.mdx new file mode 100644 index 00000000..2116c717 --- /dev/null +++ b/pages/safenet/protocol/entry-point.mdx @@ -0,0 +1,11 @@ +# Entry Point + +The Entry Point is a smart contract deployed on every supported [chain](../chains.mdx). +It is distinct from the [ERC-4337](../../advanced/erc-4337/overview.mdx) entry point contract and is the primary gateway for [Safenet transactions](../safenet-transaction.mdx). +When the [processor](../core-components/processor.mdx) relays transactions, the entry point ensures on-chain bookkeeping and cross-chain communication. + +It executes Safe transactions signed by the owners and co-signed by the processor, meaning no further authentication is required. + +For on-chain bookkeeping, minimal data is stored in the form of storage and events, which validators use to verify the correctness of [settlements](../concepts/settlement.mdx). +If validity proofs are needed, information about executed Safenet transactions can be sent to the home chain to facilitate challenge resolution. +This requires additional authentication, as configured by the [Safe DAO](./safe-dao.mdx). \ No newline at end of file diff --git a/pages/safenet/protocol/guarantee-engine.mdx b/pages/safenet/protocol/guarantee-engine.mdx new file mode 100644 index 00000000..b6c53ba4 --- /dev/null +++ b/pages/safenet/protocol/guarantee-engine.mdx @@ -0,0 +1,8 @@ +# Guarantee engine + +The Guarantee Engine is a smart contract deployed on the Ethereum Mainnet (the [home chain](../chains.mdx)) that is responsible for issuing [guarantees](../concepts/guarantee.mdx) during challenge flows. + +It is designed to remain as general as possible, managing a list of [guarantee implementations](./guarantee-implementation.mdx) that verify the correctness of [settlements](../concepts/settlement.mdx). +The guarantee engine works in tandem with the [Transciever](./transceiver.mdx) contracts, which act as bridge adapters, ensuring compatibility across different chains. + +The [SafeDAO](./safe-dao.mdx) owns and governs the guarantee engine, making it the central authority for configuring and managing guarantees. diff --git a/pages/safenet/protocol/guarantee-implementation.mdx b/pages/safenet/protocol/guarantee-implementation.mdx new file mode 100644 index 00000000..856ff0fb --- /dev/null +++ b/pages/safenet/protocol/guarantee-implementation.mdx @@ -0,0 +1,7 @@ +# Guarantee Implementation + +A Guarantee Implementation is a smart contract registered with the [guarantee engine](./guarantee-engine.mdx). +It defines the rules and semantics for applying and validating a [guarantee](../concepts/guarantee.mdx). + +These implementations can vary in configuration, such as whether guarantees are turned on or off by default or certain guarantees are required for particular flows. +The flexibility of the guarantee implementation allows Safenet to support a range of use cases and transaction types. diff --git a/pages/safenet/protocol/guard.mdx b/pages/safenet/protocol/guard.mdx new file mode 100644 index 00000000..107bfa09 --- /dev/null +++ b/pages/safenet/protocol/guard.mdx @@ -0,0 +1,8 @@ +# Guard + +The Guard is a smart contract deployed on every chain in Safenet. It is a classic [Safe Guard](./../../advanced/smart-account-guards.mdx). +It functions as a security mechanism that verifies whether a transaction has been co-signed by the [processor](../core-components/processor.mdx). + +The Guard safeguards against fraudulent or unauthorized [transactions](../safenet-transaction.mdx), providing an additional layer of security to the Safenet protocol. +It also ensures that only authorized [processors](../core-components/processor.mdx) can initiate and approve transactions, maintaining the system's integrity. + diff --git a/pages/safenet/protocol/home-safe.mdx b/pages/safenet/protocol/home-safe.mdx new file mode 100644 index 00000000..36c4eb31 --- /dev/null +++ b/pages/safenet/protocol/home-safe.mdx @@ -0,0 +1,5 @@ +# Home Safe + +The Home Safe refers to a [Safe Smart Account](../../home/what-is-safe.mdx) on Ethereum Mainnet. It is the central hub for Safenet transactions. +It acts as the [home chain](../chains.mdx) account for managing assets and [guarantees](../concepts/guarantee.mdx), facilitating the proper [settlement](../concepts/settlement.mdx) and validation of cross-chain transactions. + diff --git a/pages/safenet/protocol/overview.mdx b/pages/safenet/protocol/overview.mdx new file mode 100644 index 00000000..7d78142a --- /dev/null +++ b/pages/safenet/protocol/overview.mdx @@ -0,0 +1,5 @@ +# Safenet Protocol + +This section describes the smart contracts deployed on the different chains that enable trustless communication in Safenet. + +![Safenet-protocol-overview](../../../assets/safenet-protocol-overview.png) diff --git a/pages/safenet/protocol/relayer.mdx b/pages/safenet/protocol/relayer.mdx new file mode 100644 index 00000000..6b175249 --- /dev/null +++ b/pages/safenet/protocol/relayer.mdx @@ -0,0 +1,7 @@ +# Relayer + +The Relayer is the externally owned account (EOA) that serves as the transaction originator for [Safenet transactions](../safenet-transaction.mdx). +It is responsible for fronting the gas costs associated with executing transactions. + +The [processor](../core-components/processor.mdx) reimburses the Relayer for these gas fees. +While this document does not cover the exact reimbursement mechanism, it ensures that relayers are compensated for their role in transaction execution. \ No newline at end of file diff --git a/pages/safenet/protocol/safe-dao.mdx b/pages/safenet/protocol/safe-dao.mdx new file mode 100644 index 00000000..d834f86b --- /dev/null +++ b/pages/safenet/protocol/safe-dao.mdx @@ -0,0 +1,8 @@ +# Safe DAO + +The Safe DAO is the governing body responsible for the ownership and configuration of the [guarantee engine](./guarantee-engine.mdx) and other parts of Safenet. +It is the only entity that can modify Safenet's configurations via the guarantee engine. +These configurations are managed on [Ethereum Mainnet](../chains.mdx) and can be updated based on the ecosystem's evolving needs. + +The Safe DAO ensures that Safenet operates decentralized and flexible, providing the necessary oversight for secure and efficient cross-chain operations. + diff --git a/pages/safenet/protocol/settlement-engine.mdx b/pages/safenet/protocol/settlement-engine.mdx new file mode 100644 index 00000000..2068f795 --- /dev/null +++ b/pages/safenet/protocol/settlement-engine.mdx @@ -0,0 +1,8 @@ +# Settlement Engine + +The Settlement Engine is a smart contract that processes debit requests on the [debit chain](../chains.mdx). +It is responsible for transferring funds from a Safenet Safe to the [beneficiary](./beneficiary.mdx) designated by the [liquidity provider](../core-components/liquidity-provider.mdx) who fronted funds on the spending chain. + +Once a [settlement](../concepts/settlement.mdx) is initiated, a delay period begins, allowing [validators](../core-components/validator.mdx) to verify the settlement's correctness. +If no [challenges](../concepts/challenge.mdx) are raised during this period, the processor can finalize the settlement, which triggers the debiting of the Safe and transfers funds to the beneficiary. + diff --git a/pages/safenet/protocol/transceiver.mdx b/pages/safenet/protocol/transceiver.mdx new file mode 100644 index 00000000..d762e32a --- /dev/null +++ b/pages/safenet/protocol/transceiver.mdx @@ -0,0 +1,7 @@ +# Transceiver + +The Transceiver is a bridge adapter used within Safenet to ensure that the [guarantee engine](./guarantee-engine.mdx) remains bridge-agnostic. +It enables seamless cross-chain communication, allowing the guarantee engine to interact with multiple blockchains. + +Transceivers are registered by the [SafeDAO](./safe-dao.mdx) within the [guarantee engine](./guarantee-engine.mdx) to support interoperability across different chains and [guarantee implementations](./guarantee-implementation.mdx). + diff --git a/pages/safenet/safenet-account.mdx b/pages/safenet/safenet-account.mdx new file mode 100644 index 00000000..78d2445f --- /dev/null +++ b/pages/safenet/safenet-account.mdx @@ -0,0 +1,8 @@ +# Safenet Account + +A Safenet account is a network of [Safe Smart Accounts](../home/what-is-safe.mdx) deployed on multiple [chains](./chains.mdx). +A Safe Smart Account is connected to a Safenet account by adding the Safenet [Guard](./protocol/guard.mdx) as a co-signer. + +Initially, one Safe Smart Account can be added per chain. In later phases of the roadmap, multiple Safe Smart Accounts can be added per chain. + +![Safenet-account](../../assets/safenet-account.png) \ No newline at end of file diff --git a/pages/safenet/safenet-transaction.mdx b/pages/safenet/safenet-transaction.mdx new file mode 100644 index 00000000..3fdaa3d1 --- /dev/null +++ b/pages/safenet/safenet-transaction.mdx @@ -0,0 +1,62 @@ +# Safenet Transaction + +This page describes the flow of a Safenet transaction. +The [Core Components](core-components/processor.mdx) section provides further details on the components and roles involved in a Safenet transaction. + +A Safenet transaction consists of three main phases: + +![Safenet-transaction-phases](../../assets/safenet-transaction-phases.png) + +### 1. Simulation + +In the first phase, security checks are performed off-chain to ensure the transaction is valid. + +1. The [processor](./core-components/processor.mdx) previews security checks. +2. The [End User](./core-components/end-user.mdx) signs the transactions. This involves signing a Safe transaction with enough Safe owners. +3. The transaction is published to [Safenet Transaction pool](./core-components/transaction-service.mdx). + +### 2. Fulfillment + +This is the main part of the transaction that the user is interested in. This part enables the users to send a transaction on the [spend chain](./chains.mdx) as if they possess the required funds on the spend chain. + +1. A [resource lock](./concepts/resource-lock.mdx) is issued on the Safe Smart Account on the debit chain. This prevents the user from withdrawing funds from the Safe Smart Account on the debit chain before the [liquidity provider](./core-components/liquidity-provider.mdx) is reimbursed. +2. The liquidity provider sends funds to the user's Safe Smart Account on the spend chain (pre-funding). +3. The user's Smart Account executes the intended transaction on the spend chain with the funds. + +### 3. The settlement + +In the last phase, the [settlement](./concepts/settlement.mdx) is executed on the debit chain. +This phase ensures the liquidity provider gets reimbursed for the pre-funding plus a fee. + +1. The processor requests a settlement on the debit chain. +2. The settlement request has a challenge delay, in which any [validator](./core-components/validator.mdx) can challenge the settlement request. +3. When the settlement is not challenged, the settlement is executed. The liquidity provider receives funds from the Safe Smart Account on the debit chain, and the Safe Smart Account is unlocked. + +When the settlement is [challenged](./concepts/challenge.mdx), the processors must prove the validity of the transaction. + +## Flow Diagram + +This flow diagram illustrates the first two phases of a Safenet transaction: + +``` mermaid +sequenceDiagram + box MVP Processor + actor P as Processor + actor R as Relayer + actor LP as Liquidity Provider + end + participant E as Entry Point + participant S as Settlement Engine + participant G as Guard + participant A as Account + participant T as Target + + P->>R: cosignature + R->>+E: executeSafenetAction() + LP-->>A: transferFrom(Liquidity Provider, Account) + E->>A: execTransaction() + E->>G: checkSafeTransaction() + G-->>P: ecrecover() + A->>T: CALL + deactivate E +``` \ No newline at end of file