Merge branch 'main' into client-l1-txHash

Author: bitwiseguy

.env

@@ -4,42 +4,36 @@ VITE_ALICE_SK=0x2d999770f7b5d49b694080f987b82bbc9fc9ac2b4dcc10b0f8aba7d700f69c6d
 VITE_ALICE_ADDRESS=0xAAA6628Ec44A8a742987EF3A114dDFE2D4F7aDCE
 
 VITE_ALICE_CHAIN_URL=https://rpc.public.zkevm-test.net
+VITE_ALICE_ENTRYPOINT_ADDRESS=0x65B786ab8b81286f33953aC751b85E2C08D6CFef
+VITE_ALICE_SCW_ADDRESS=0xAC5f6d0130Ad82e0677b5ACF788926F5DDA76ca5
 
 # BOB
 VITE_BOB_SK=0x0279651921cd800ac560c21ceea27aab0107b67daf436cdd25ce84cad30159b4
 VITE_BOB_ADDRESS=0xBBB676f9cFF8D242e9eaC39D063848807d3D1D94
 
 VITE_BOB_CHAIN_URL=https://sepolia-rpc.scroll.io
-
+VITE_BOB_ENTRYPOINT_ADDRESS=0x30CE8e965155dc56bD061C5FBf8fa3a32775fDAD
+VITE_BOB_SCW_ADDRESS=0x705DBe0E96E172e95d56eB689dE3Fc43E29b8236
 
 # Charlie
-VITE_CHARLIE_SK=0x827d8121978e93d2e9b01be98fd8bdb08eaa0145184442bb6ab0be17f6ab4248,
-VITE_CHARLIE_ADDRESS=0xccc182e9C61ABed84B4df353C8a066EB7a2FeE6f,
+VITE_CHARLIE_SK=0x827d8121978e93d2e9b01be98fd8bdb08eaa0145184442bb6ab0be17f6ab4248
+VITE_CHARLIE_ADDRESS=0xccc182e9C61ABed84B4df353C8a066EB7a2FeE6f
 
 # Debbie,
-VITE_DEBBIE_SK=0x07dbfb9cdfa0dcddcc82f86da46ca63db210eaddeab7410d5dda9a18bbf3eb5f,
-VITE_DEBBIE_ADDRESS=0xddd63cb783fF61D683e4BED42a03Aa6b5AF7De2B,
+VITE_DEBBIE_SK=0x07dbfb9cdfa0dcddcc82f86da46ca63db210eaddeab7410d5dda9a18bbf3eb5f
+VITE_DEBBIE_ADDRESS=0xddd63cb783fF61D683e4BED42a03Aa6b5AF7De2B
 
 # Eve,
-VITE_EVE_SK=0x22215c87ad66bed27b715e39c3fd105a6616eb139a4106773b1b67233b7796d4,
-VITE_EVE_ADDRESS=0xeeef433cD1EF1714d176202D0Aa7680F20aa7F89,
+VITE_EVE_SK=0x22215c87ad66bed27b715e39c3fd105a6616eb139a4106773b1b67233b7796d4
+VITE_EVE_ADDRESS=0xeeef433cD1EF1714d176202D0Aa7680F20aa7F89
 
 # Fred,
-VITE_FRED_SK=0x1234f96c85acb25dff1f20e03ba287a008c99a02541ba5a9ae8b4392dd12d4ff,
-VITE_FRED_ADDRESS=0xfff1b9434a6B6402508911028545Aa9CE080ab12,
-
-
+VITE_FRED_SK=0x1234f96c85acb25dff1f20e03ba287a008c99a02541ba5a9ae8b4392dd12d4ff
+VITE_FRED_ADDRESS=0xfff1b9434a6B6402508911028545Aa9CE080ab12
 
 # IRENE
 VITE_IRENE_SK=0xfebb3b74b0b52d0976f6571d555f4ac8b91c308dfa25c7b58d1e6a7c3f50c781
 VITE_IRENE_ADDRESS=0x111A00868581f73AB42FEEF67D235Ca09ca1E8db
 
-# If Alice and Bob are on seperate chains they could use seperate entrypoints
-VITE_ALICE_ENTRYPOINT_ADDRESS=0x65B786ab8b81286f33953aC751b85E2C08D6CFef
-VITE_BOB_ENTRYPOINT_ADDRESS=0x30CE8e965155dc56bD061C5FBf8fa3a32775fDAD
-
-VITE_ALICE_SCW_ADDRESS=0xAC5f6d0130Ad82e0677b5ACF788926F5DDA76ca5
-VITE_BOB_SCW_ADDRESS=0x705DBe0E96E172e95d56eB689dE3Fc43E29b8236
-
 VITE_SCW_DEPOSIT=10000000000000000 # 0.01 ETH
 VITE_INTERMEDIARY_BALANCE=5000000000000000 # 0.005 ETH

README.md

@@ -1,9 +1,9 @@
 <h1 align="center">
-<div><img src="./SCBridge-Wallet.png"><br>
+<div><img src="./docs/SCBridge-Wallet.png"><br>
 SCBridge-Wallet
 </h1>
 <h3 align="center">
-An L2 state channel bridge contract which is also an ERC-4337 compliant smart contract wallet.
+ERC-4337 compliant smart contract wallet that enables gasless, instant finality cross-chain payments
 </h3>
 
 # Quickstart
@@ -14,7 +14,7 @@ Run each of these commands from the repo root directory:
 yarn
 yarn chain:a
 yarn chain:b
-yarn deploy-and-start
+yarn deploy-and-start-local
 ```
 
 These commands do the following:
@@ -40,28 +40,21 @@ By having that Intermediary perform the same role in several users' smart contra
 
 This repo also contains Typescript source code for off-chain clients that can be run by a user and by a Intermediary, to enable to orchestrate the functionality described above.
 
-### Sequence Diagram
+### Sequence Diagrams
 
-Scenario: Alice wants to (a) pay Bob offchain and (b) execute a trade on Uniswap. Irene is an Intermediary actor.
+Scenario: Alice wants to (a) pay Bob offchain and (b) pay Charley, who does not have a state channel bridge. Irene is an Intermediary actor.
 
-In a typical state channel bridge architecture (green) she must deposit funds into the ID of a "ledger channel" in a Singleton adjudicator contract. Her counterparty in that ledger channel (Irene) must have deposited into another ledger channel with Bob. If Alice wants to execute her Uniswap trade with those deposited funds, she needs to close the ledger channel, withdraw the funds (in one L1 tx), and submit the trade (in another L1 tx).
+In a typical state channel bridge architecture she must deposit funds into the ID of a "ledger channel" in a Singleton adjudicator contract. Her counterparty in that ledger channel (Irene) must have deposited into another ledger channel with Bob. If Alice wants to send Charley money using those deposited funds, she needs to close the ledger channel, withdraw the funds (in one L1 tx), and submit the transfer to Charley (in another L1 tx).
 
-With the State Channel Bridge Wallet (SCBridge-Wallet) Architecture, she can instead propose the Uniswap trade to Irene, who checks that it doesn't compromise any HTLC payments, and then countersigns it and submits it to Alice's SCBridge-Wallet via en entrypoint contract. The SCBridge-Wallet validates the countersigned transaction and calls into Uniswap to execute the trade.
-
-In either case, executing a multihop payment from Alice to Bob (white) is as easy as executing the well known HTLC (Hash Timelocked Contract) protocol, which is the same technology that powers the Bitcoin Lightning Network.
-
-![Sequence Diagram](./SCBridge-Wallet-sequence.png)
+![Sequence Diagram](./docs/seq-typical-sc.png)
 
 <!-- diagram source, edit at sequencediagram.org
 fontawesome f182 Alice
 fontawesome f233 Irene
 fontawesome f183 Bob
 
 fontawesome f0e3 Adjudicator #red
-fontawesome f1c9 SCW-Alice #green
-fontawesome f1c9 SCW-Bob #green
-fontawesome f1c9 Uniswap
-
+fontawesome f183 Charley
 
 group #lightgreen Typical State Channel Bridge
 
@@ -71,35 +64,59 @@ Alice-#red>Adjudicator: deposit 10
 Bob->Irene: ledger 0/10
 Bob<-Irene: ack
 Irene-#red>Adjudicator: deposit 10
-group L1 transaction flow
+group On-chain transaction flow
 Alice->Irene: close ledger
 Alice<-Irene: ack
-Alice-#red>Adjudicator: withdraw
-Alice-#red>Uniswap: uniswap trade
+Alice-#red>Adjudicator: withdraw 10
+Adjudicator--#red>Alice: withdraw 10
+Alice-#red>Charley: transfer 10
 end
 end
+-->
+
+With the State Channel Bridge Wallet (SCBridge-Wallet) Architecture, she can instead send Irene the proposed transfer to Charley. Irene checks that this new payment doesn't compromise any HTLC payments, and then countersigns it and submits it to Alice's SCBridge-Wallet via en EntryPoint contract. The SCBridge-Wallet validates the countersigned transaction, then transfers some of the wallet funds to Charley.
+
+![Sequence Diagram](./docs/seq-sc-bridge-wallet.png)
+
+<!-- diagram source, edit at sequencediagram.org
+fontawesome f182 Alice
+fontawesome f233 Irene
+fontawesome f183 Bob
+
+fontawesome f1c9 EntryPoint
+fontawesome f1c9 SCW-Alice #green
+fontawesome f1c9 SCW-Bob #green
+fontawesome f183 Charley
 
 group #ff00ff State Channel Bridge Wallet
 Alice-#red>SCW-Alice: transfer 10 (direct from exchange, perhaps)
 Bob->Irene: ledger Irene:10
 Bob<-Irene: ack
 Irene-#red>SCW-Bob: transfer 10
-group L1 transaction flow
-Alice->Irene: proposed uniswap trade
-Irene-#red>SCW-Alice: countersigned uniswap trade
-
-SCW-Alice->Uniswap: uniswap trade
+group On-chain transaction flow
+Alice->Irene: proposed transfer
+Irene-#red>EntryPoint: countersigned transfer
+EntryPoint-#red>SCW-Alice: transfer 10
+SCW-Alice->Charley: transfer 10
+end
 end
+-->
 
+In either case, executing a multihop payment from Alice to Bob is as easy as executing the well known HTLC (Hash Timelocked Contract) protocol, which is the same technology that powers the Bitcoin Lightning Network.
 
-end
+![Sequence Diagram](./docs/seq-off-chain-pay.png)
+
+<!-- diagram source, edit at sequencediagram.org
+fontawesome f182 Alice
+fontawesome f233 Irene
+fontawesome f183 Bob
 
-group Multihop L2 payment from Alice to Bob via Irene
+group Off-chain payment from Alice to Bob via Irene
 Alice->Bob: request an invoice
 Bob->Alice: hash
 Alice->Irene: add HTLC(hash,timeout,amount, sig, turnNum)
 Irene->Bob: add HTLC
-Bob->Irene:  preimage + updated signed state
+Bob->Irene: preimage + updated signed state
 Irene->Alice: preimage + updated signed state
 Irene->Bob: countersigned updated state
 Alice->Irene: countersigned updated state
@@ -108,7 +125,7 @@ end
 
 ### Future work
 
-This repo originated as an entry for the ETHGlobal 2023 hackathon. Therefore some shortcuts were taken to enable an end-to-end demo given the time constraints. The following list identifies future areas for improvement if this foundation was used to build a production-ready application.
+This repo originated as an entry for the ETHGlobal 2023 hackathon. Therefore the code takes some shortcuts to enable an end-to-end demo given the time constraints. The following list identifies future areas for improvement if this foundation was used to build a production-ready application.
 
 1. `Messaging`: currently in-browser [BroadcastChannels](https://nodejs.org/api/worker_threads.html#class-broadcastchannel-extends-eventtarget) are used to communicate between the different users. A proper messaging service should allow users to exchange messages when they are on different machines with different IP addresses. Possible technologies include: WebSockets, WebRTC, HTTP requests, etc.
 2. `Key management`: currently the private signing keys used by each user to sign blockchain txs and state channel messages are stored in a static [.env](./.env) file. These keys are read by the browser code and inserted in the the JavaScript running on the page. Since these keys control the movement of funds, they should be stored more securely, i.e. in Metamask or another crypto wallet.

clients/OwnerClient.ts

@@ -175,6 +175,11 @@ export class OwnerClient extends StateChannelWallet {
 
   // Create L1 payment UserOperation and forward to intermediary
   async payL1(payee: string, amount: bigint): Promise<string> {
+    const balance = await this.getOwnerBalance();
+    if (amount > balance) {
+      throw new Error("Requested payment amount exceeds owner balance");
+    }
+
     // Only need to encode 'to' and 'amount' fields (i.e. no 'data') for basic eth transfer
     const callData = IAccount.encodeFunctionData("execute", [
       payee,

SCBridge-Wallet-sequence.png docs/SCBridge-Wallet-sequence.png

@@ -265,7 +265,7 @@ const Wallet: React.FunctionComponent<{ role: Role }> = (props: {
                 ) : (
                   <AccessTimeIcon style={{ marginRight: "5px" }} />
                 )}
-                L1 Pay
+                Chain Pay
               </Button>
               <Button
                 size="medium"
@@ -280,7 +280,7 @@ const Wallet: React.FunctionComponent<{ role: Role }> = (props: {
                     });
                 }}
               >
-                <BoltIcon /> L2 Pay
+                <BoltIcon /> Bridge Pay
               </Button>
             </ButtonGroup>
           </Stack>