1369

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: Run tests
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "feature/optimisation" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "main", "feature/optimisation" ]
 
 jobs:
   test:

.gitignore

@@ -1,5 +1,4 @@
 node_modules
 temp
-build
 .idea
 .env

README.md

@@ -1,59 +1,89 @@
-# Wallet V5
+# W5: wallet smart contract v5
 
-This is an extensible wallet specification aimed at replacing V4 and allowing arbitrary extensions.
+New version of wallet smart contract, the previous one was [v4r2](https://github.com/ton-blockchain/wallet-contract).
 
-Wallet V5 has 25% lower fees, can delegate payments for gas to third parties and supports flexible extension mechanism.
+The entire concept is proposed by the [Tonkeeper team](https://tonkeeper.com/).
 
-## Warning! Contest note! 
+New Features:
 
-<div align="center">
-<img alt="Contest logo" src="contest.png" height="280" width="280">
-</div>
+- Send up to 255 messages at once;
 
-**Because of the extreme amount of optimizations, developer's discretion is advised!** *Evil laugh*
+- Signed actions can be sent not only by external message, but also by internal messages (can be used for gasless transactions);
 
-The build system is the same as in the original Wallet V5, **no security features have been sacrificed**
-for performance improvements, that is - there are **practically no tradeoffs or compromises**.
+- Unlimited extensions;
 
-Message and storage layouts were **not changed**, although some rearragement might squeeze a little more gas,
-but that may break existing optimizations due to stack reordering.
+- Extension can prohibit signed actions in the wallet (can be used for 2fa or key recovery);
 
-Also, **tests were improved** - a **Global Gas Counter** mechanism was added that accounts for gas in all transactions
-of all test suites and cases (except for negative and getter ones). This allows to keep an eye on other non-contest
-cases to track how bad is tradeoff when performing optimizations here and there.
+- Optimizations to reduce network fees;
 
-Another utility that was developed for contest is ***scalpel script***, that allows for a detailed, *really* detailed optimizations
-of the code by comparing lines of code function by function, printing out diffs, and providing detailed TVM files with
-stack comments and rewrites. This utility allowed to make some latter optimizations, since with each optimization
-next one becomes exponentionally harder to make. While result is not entirely precise and is needed to be verified
-by tests, this allows to instantly estimate whether there is some progress or not, since scalpel is executed immediately,
-while tests take approximately 10 seconds to execute.
-
-### Details of optimizations, their rationale and explanations, comparison of consumed gas both in test cases and not in test cases (global gas counter) are provided on a dedicated page: [Gas improvements](Improvements.rst).
+- Better foolproofing safety - reply-protection for external messages, wallet id rethinking;
 
 ## Project structure
 
 -   [Specification](Specification.md)
 -   `contracts` - source code of all the smart contracts of the project and their dependencies.
 -   `wrappers` - wrapper classes (implementing `Contract` from ton-core) for the contracts, including any [de]serialization primitives and compilation functions.
 -   `tests` - tests for the contracts.
--   `scripts` - scripts used by the project, mainly the deployment scripts.
--   **[Gas improvements](Improvements.rst)** (detailed by contest paths, global gas counters per commit)
+-   `scripts` - scripts used by the project, mainly the deployment scripts, additionally contains utilities for gas optimisation.
+-   `fift` - contains standard Fift v0.4.4 library including the assembler and disassembler for gas optimisation utilities.
 
 ## How to use
 
 ### Build
 
-`npm run build:v5`
+`npm run build`
 
 ### Test
 
 `npm run test`
 
 ### Deployment
-1. Deploy library: `npm run deploy-library`
-2. Deploy wallet: `npm run deploy-wallet`
 
-### Get wallet compiled code
+Deploy wallet: `npm run deploy-wallet`
+
+### Known issues
+
+1) Since the `valid_until` is uint32 it will not work after 2106 year. We believe new versions of wallet smart contract will be available by then.
+
+2) If the `action_send_msg` content is invalid and the sendmode has +2, the error will not be ignored. An update of the node is planned where this behaviour will be changed (with +2 sendmode and `action_send_msg` invalid content the error will be ignored).
+
+3) It would be good to do `end_parse()` for messages and contract data. But this is not done within optimisations.
+
+### Gasless flow
+
+1. When sending an USDt (or other Jetton) the user signs one message containing two outgoing USDt transfers:
+
+     * USDt transfer to the recipient's address.
+
+     * Transfer of a small amount of USDt in favor of the Service.
+
+2. This signed message is sent offchain by HTTPS to the Service backend. The Service backend checks message and sends it to the TON blockchain paying Toncoins for network fees.
+
+### Gasless known issues
+
+1) By requesting a gasless service, a user can have time to increase the seqno on his own, or via another service. 
+
+    In this case, the gasless service will incur gas costs. 
+
+    However, this is a non-scalable scenario, as it requires the user to incur gas costs as well. 
+
+    A blacklist on the service backend side solves the problem.
+
+2) The user can request a gasless service and by means of a specialised extension have time to withdraw the entire balance of Jettons without change seqno.
+
+    In this case, the Jetton transfer message from the service will encounter a balance shortage and the Toncoins attached to message will return to the user's wallet.
+
+    However, this is a non-scalable scenario, as it requires the user to incur gas costs as well. 
+
+    A blacklist on the service backend side solves the problem.
+
+### Suggested extensions
+
+1) Decentralised subscriptions. The extension can withdraw a given number of Toncoins or Jettons once in a given period.
+
+2) 2FA: Multisig extension is added, extension prohibits wallet signature;
+
+3) Key recovery: 2FA, but in multisig extension there is an option to change the control keys. Possible cooldown period when the other party can cancel the key change.
+
+4) Key compromise: An extension with a new key is added, extension prohibits wallet signature;
 
-`npm run print-wallet-code`

Specification.md

@@ -7,8 +7,6 @@ This is an extensible wallet specification aimed at replacing V4 and allowing ar
 * [Features](#features)
 * [Overview](#overview)
 * [Discussion](#discussion)
-* [Wallet ID](#wallet-id)
-* [Packed address](#packed-address)
 * [TL-B definitions](#tl-b-definitions)
 * [Source code](#source-code)
 
@@ -19,34 +17,35 @@ Thanks to [Andrew Gutarev](https://github.com/pyAndr3w) for the idea to set c5 r
 
 Thanks to [@subden](https://t.me/subden), [@botpult](https://t.me/botpult) and [@tvorogme](https://t.me/tvorogme) for ideas and discussion.
 
+Thanks to [Skydev](https://github.com/Skydev0h) for optimization and preparing the second revision of the contract.
+
 
 ## Features
 
 * 25% smaller computation fees.
 * Arbitrary amount of outgoing messages is supported via action list.
-* Wallet code can be upgraded transparently without breaking user's address in the future.
 * Wallet code can be extended by anyone in a decentralized and conflict-free way: multiple feature extensions can co-exist.
 * Extensions can perform the same operations as the signer: emit arbitrary messages on behalf of the owner, add and remove extensions.
 * Signed requests can be delivered via internal message to allow 3rd party pay for gas.
 * For consistency and ease of indexing, external messages also receive a 32-bit opcode.
+* To lay foundation for support of scenarios like 2FA or access recovery it is possible to disable signature authentication by extension.
 
 ## Overview
 
-Wallet V5 supports **2 authentication modes**, all standard output actions (send message, set library, code replacement) plus additional **3 operation types**.
+Wallet V5 supports **2 authentication modes** and **3 operations types**.
 
 Authentication:
 * by signature
 * by extension
 
-Operation types:
-* standard output actions
-* “set data” operation
-* install extension
-* remove extension
+Operations:
+* standard "send message" action (up to 255 messages at once),
+* enable/disable signature authentication (can be invoked only by extension),
+* install/remove extension.
 
 Signed messages can be delivered both by external and internal messages.
 
-All operation types are available to all authentication modes.
+All operations are available to all authentication modes.
 
 ## Discussion
 
@@ -63,40 +62,12 @@ User may delegate this job to other apps via extensions.
 
 ### Extending the wallet
 
-**A. Use extensions**
-
 The best way to extend functionality of the wallet is to use the extensions mechanism that permit delegating access to the wallet to other contracts.
 
 From the perspective of the wallet, every extension can perform the same actions as the owner of a private key. Therefore limits and capabilities can be embedded in such an extension with a custom storage scheme.
 
 Extensions can co-exist simultaneously, so experimental capabilities can be deployed and tested independently from each other.
 
-**B. Code optimization**
-
-Backwards compatible code optimization **can be performed** with a single `set_code` action (`action_set_code#ad4de08e`) signed by the user. That is, hypothetical upgrade from `v5R1` to `v5R2` can be done in-place without forcing users to change their wallet address.
-
-If the optimized code requires changes to the data layout (e.g. reordering fields) the user can sign a request with two actions: `set_code` (in the standard action) and `set_data` (an extended action per this specification). Note that `set_data` action must make sure `seqno` is properly incremented after the upgrade as to prevent replays. Also, `set_data` must be performed right before the standard actions to not get overwritten by extension actions. The updated wallet **must** have the new subwallet ID to prevent accidental repeated migrations.
-
-User agents **should not** make `set_code` and `set_data` actions available via general-purpose API to prevent misuse and mistakes. Instead, they should be used as a part of migration logic for a specific wallet code.
-
-To restore the wallet by a seed phrase, user agent should use the original code and should expect the upgraded code to work in exactly the same way as previously.
-
-**C. Emergency upgrades**
-
-This is a variant of (B), so the same consideration apply. The difference is that functionality may be modified as to prevent user from suffering loss of funds. E.g. some previously possible actions or signed messages would lead to a failure.
-
-Just like with (B), user agents **should not** make `set_code` and `set_data` actions available via general-purpose API to prevent misuse and mistakes. Instead, they should be used as a part of migration logic for a specific wallet code.
-
-New users’ wallets **should not** be deployed with upgraded code. Instead, the improved wallet code should also be released as a new wallet version (e.g. v6, with a separate subwallet ID) and new wallets should be deployed with that code. This way `set_code` would be used as an emergency patch for existing wallets, while new wallets would be deployed directly with the major next version.
-
-
-**D. Substantial upgrades**
-
-We **do not recommend** performing substantial wallet upgrades in-place using `set_code`/`set_data` actions. Instead, user agents should have support for multiple accounts and easy switching between them.
-
-In-place migration requires maintaining backwards compatibility for all wallet features, which in turn could lead to increase in code size and higher gas and rent costs.
-
-
 ### Can the wallet outsource payment for gas fees?
 
 Yes! You can deliver signed messages via an internal message from a 3rd party wallet. Also, the message is handled exactly like an external one: after the basic checks the wallet takes care of the fees itself, so that 3rd party does not need to overpay for users who actually do have TONs.
@@ -123,92 +94,24 @@ You need to put two requests in your message body:
 
 Yes. We have considered constant-size schemes where the wallet only stores trusted extension code. However, extension authentication becomes combursome and expensive: plugin needs to transmit additional data and each request needs to recompute plugin’s address. We estimate that for the reasonably sized wallets (less than 100 plugins) authentication via the dictionary lookup would not exceed costs of indirect address authentication.
 
+### Why it can be useful to disallow authentication with signature?
+
+Ability to disallow authentication with signature enables two related use-cases:
+
+1. Two-factor authentication schemes: where control over wallet is fully delegated to an extension that checks two signatures: the user’s one and the signature from the auth service. Naturally, if the signature authentication in the wallet remains allowed, the second factor check is bypassed.
+
+2. Account recovery: delegating full control to another wallet in case of key compromise or loss. Wallet may contain larger amount of assets and its address could be tied to long-term contracts, therefore delegation to another controlling account is preferred to simply transferring the assets.
+
 ### What is library on masterchain?
 
 Library is a special code storage mechanism that allows to reduce storage cost for a new Wallet V5 contract instance. Wallet V5 contract code is stored into a masterchain library. 
 When wallet contract is being deployed, original code hash is being used as the contract code.
 Library contract itself data and code are empty cells. That leads to the inability to change the library code, delete the contract, or withdraw funds from it.
 Therefore, any Wallet V5 user can top up the library contract balance if they are afraid that the library code of their wallet will be frozen.
 
-## Wallet ID
-
-Wallet ID disambiguates requests signed with the same public key to different wallet versions (V3/V4/V5) or wallets deployed on different chains.
-
-For Wallet V5 we suggest using the following wallet ID:
-
-```
-wallet_id$_ global_id:int32 wc:int8 version:(## 8) subwallet_number:(## 32) = WalletID;
-```
-
-- `global_id` is a TON chain identifier. TON Mainnet `global_id = -239` and TON Testnet `global_id = -3`.
-- `wc` is a Workchain. -1 for Masterchain and 0 for Basechain. 
-- `version`: current version of wallet v5 is `0`.
-- `subwallet_number` can be used to get multiplie wallet contracts binded to the single keypair.
-
-## Packed address
-
-To make authorize extensions efficiently we compress 260-bit address (workchain + sha256 of stateinit) into a 256-bit integer:
-
-```
-int addr = addr_hash ^ (wc + 1)
-```
-
-Previously deployed wallet v4 was packing the address into a cell which costs ≈500 gas, while access to dictionary costs approximately `120*lg2(N)` in gas, that is serialization occupies more than half of the access cost for wallets with up to 16 extensions. This design makes packing cost around 50 gas and allows cutting the authentication cost 2-3x for reasonably sized wallets.
-
-As of 2023 TON network consists of two workchains: -1 (master) and 0 (base). This means that the proposed address packing reduces second-preimage resistance of sha256 by 1 bit which we consider negligible. Even if the network is expanded with 254 more workchains in a distant future, our scheme would reduce security of extension authentication by only 8 bits down to 248 bits. Note that birthday attack is irrelevant in our setting as the user agent is not installing random extensions, although the security margin is plenty anyway (124 bits).
-
-
-
 ## TL-B definitions
 
-Action types:
-
-```tl-b
-// Standard actions from block.tlb:
-out_list_empty$_ = OutList 0;
-out_list$_ {n:#} prev:^(OutList n) action:OutAction
-  = OutList (n + 1);
-action_send_msg#0ec3c86d mode:(## 8) 
-  out_msg:^(MessageRelaxed Any) = OutAction;
-action_set_code#ad4de08e new_code:^Cell = OutAction;
-action_reserve_currency#36e6b809 mode:(## 8)
-  currency:CurrencyCollection = OutAction;
-libref_hash$0 lib_hash:bits256 = LibRef;
-libref_ref$1 library:^Cell = LibRef;
-action_change_library#26fa1dd4 mode:(## 7) { mode <= 2 }
-  libref:LibRef = OutAction;
-
-// Extended actions in W5:
-action_list_basic$0 {n:#} actions:^(OutList n) = ActionList n 0;
-action_list_extended$1 {m:#} {n:#} action:ExtendedAction prev:^(ActionList n m) = ActionList n (m+1);
-
-action_set_data#1ff8ea0b data:^Cell = ExtendedAction;
-action_add_ext#1c40db9f addr:MsgAddressInt = ExtendedAction;
-action_delete_ext#5eaef4a4 addr:MsgAddressInt = ExtendedAction;
-```
-
-Authentication modes:
-
-```tl-b
-signed_request$_ 
-  signature:    bits512                   // 512
-  subwallet_id: uint32                    // 512+32
-  valid_until:  uint32                    // 512+32+32
-  msg_seqno:    uint32                    // 512+32+32+32 = 608
-  inner: InnerRequest = SignedRequest;
-
-internal_signed#7369676E signed:SignedRequest = InternalMsgBody;
-internal_extension#6578746E inner:InnerRequest = InternalMsgBody;
-external_signed#7369676E signed:SignedRequest = ExternalMsgBody;
-
-actions$_ {m:#} {n:#} actions:(ActionList n m) = InnerRequest;
-```
-
-Contract state:
-```tl-b
-wallet_id$_ global_id:int32 wc:int8 version:(## 8) subwallet_number:(## 32) = WalletID;
-contract_state$_ seqno:# wallet_id:WalletID public_key:(## 256) extensions_dict:(HashmapE 256 int8) = ContractState;
-```
+See `types.tlb`.
 
 ## Source code
 

build/library-deployer.compiled.json

@@ -0,0 +1 @@
+{"hash":"7b886902938fda7f8ee72fe31ee250744bf82489579c0b8e502105a49cb72e2a","hashBase64":"e4hpApOP2n+O5y/jHuJQdEv4JIlXnAuOUCEFpJy3Lio=","hex":"b5ee9c72410106010030000114ff00f4a413f4bcf2c80b0102012002050202d1030400053c006000193b511cbec1b232483ec13b55200006f2f0014136d496"}

build/wallet_v5.compiled.json

@@ -0,0 +1 @@
+{"hash":"20834b7b72b112147e1b2fb457b84e74d1a30f04f737d4f62a668e9552d2b72f","hashBase64":"IINLe3KxEhR+Gy+0V7hOdNGjDwT3N9T2KmaOlVLSty8=","hex":"b5ee9c7241021401000281000114ff00f4a413f4bcf2c80b01020120020d020148030402dcd020d749c120915b8f6320d70b1f2082106578746ebd21821073696e74bdb0925f03e082106578746eba8eb48020d72101d074d721fa4030fa44f828fa443058bd915be0ed44d0810141d721f4058307f40e6fa1319130e18040d721707fdb3ce03120d749810280b99130e070e2100f020120050c020120060902016e07080019adce76a2684020eb90eb85ffc00019af1df6a2684010eb90eb858fc00201480a0b0017b325fb51341c75c875c2c7e00011b262fb513435c280200019be5f0f6a2684080a0eb90fa02c0102f20e011e20d70b1f82107369676ebaf2e08a7f0f01e68ef0eda2edfb218308d722028308d723208020d721d31fd31fd31fed44d0d200d31f20d31fd3ffd70a000af90140ccf9109a28945f0adb31e1f2c087df02b35007b0f2d0845125baf2e0855036baf2e086f823bbf2d0882292f800de01a47fc8ca00cb1f01cf16c9ed542092f80fde70db3cd81003f6eda2edfb02f404216e926c218e4c0221d73930709421c700b38e2d01d72820761e436c20d749c008f2e09320d74ac002f2e09320d71d06c712c2005230b0f2d089d74cd7393001a4e86c128407bbf2e093d74ac000f2e093ed55e2d20001c000915be0ebd72c08142091709601d72c081c12e25210b1e30f20d74a111213009601fa4001fa44f828fa443058baf2e091ed44d0810141d718f405049d7fc8ca0040048307f453f2e08b8e14038307f45bf2e08c22d70a00216e01b3b0f2d090e2c85003cf1612f400c9ed54007230d72c08248e2d21f2e092d200ed44d0d2005113baf2d08f54503091319c01810140d721d70a00f2e08ee2c8ca0058cf16c9ed5493f2c08de20010935bdb31e1d74cd0b4d6c35e"}