NEP ready to be reviewed

neps/nep-0582.md

@@ -2,7 +2,7 @@
 NEP: 582
 Title: Wallet Method - Sign and Return Signed Transaction
 Authors: Guille <[email protected]>
-Status: Draft
+Status: Review
 DiscussionsTo: https://github.com/nearprotocol/neps/pull/582
 Type: Wallet Standard
 Version: 1.0.0
@@ -12,15 +12,19 @@ LastUpdated: 2024-12-18
 
 ## Summary
 
-This NEP proposes to add a new standardized method to all NEAR Wallets that allows applications to request a signature from the user and immediately returns the signed transaction, thus allowing applications to take full control of the transaction lifecycle.
+We propose a new standardized method for wallets that allows to request signing a transaction, which returns the signature immediately without broadcasting it to the network.
+
+This method will allow apps to take full control of the transaction life-cycle, providing them with an alternative to the current sign-and-submit behavior, which blocks the UI until the transaction resolves.
 
 ## Motivation
 
-Currently, all our wallets work by signing a transaction and then sending them to the blockchain, blocking the application until the transaction is either successful or failed. This generates a bad user experience, as the user has to wait for the transaction to be confirmed before they can continue interacting with the application.
+Currently, when applications ask for a transaction to be signed, the wallets automatically broadcast the signature to the chain and block the app until the transaction is either successful or failed.
+
+This generates a bad user experience, as the user has to wait for the transaction to be confirmed before they can continue interacting with the application.
 
 If apps can handle the transaction lifecycle, they can provide a better user experience by acting optimistically and showing the user the result of the transaction immediately, even before it is confirmed on the blockchain. In case of error, they can eventually raise the problem to the user and rollback the UI.
 
-It is important to stress that this NEP is not proposing to remove the current way of handling transactions, but to **add an alternative method** that allows applications to take full control of the transaction lifecycle.
+It is important to stress that this NEP is not proposing to remove the current way of handling transactions, but to **add an alternative method** for applications to choose from.
 
 ## Specification
 
@@ -35,6 +39,8 @@ export interface Transaction {
     receiver_id: string;
     signature: string;
     signer_id: string;
+
+    encode(): Uint8Array; // Borsh serialization
 }
 
 export interface Signature {
@@ -43,15 +49,21 @@ export interface Signature {
 }
 
 interface Wallet {
-  signAndReturnSignature(transaction: Transaction): Promise<Signature>;
+  signAndReturnSignature(transaction: Uint8Array): Promise<Signature>;
 }
 ```
 
-It is important to remark that the definitions of `Transaction` and `Signature` are taken from `near-api-js`
+where the `transaction` parameter represents the `sha256` hash of a [borsh serialized](https://borsh.io) `Transaction`.
+
+It is important to remark that the definitions of `Transaction` and `Signature` are taken from `near-api-js`.
+
+Furthermore, all Rust, JS and Python implementation of `near-api` have `Transactions` which readily implement the `encode` which serializes them on borsh.
 
 ## Reference Implementation
 
-An [existing implementation](https://github.com/near/near-api-js/blob/9cb7e89a688304fdd439411e2854235c358f4ab7/packages/client/src/transactions/sign_and_send.ts#L12-L31) with a very similar interface can be found in `near-api-js`
+I have uploaded a [working reference implementation](https://gist.github.com/gagdiez/bf0214d41052f043076bf000b7a1eb24) that uses [`near-api-js`](https://github.com/near/near-api-js) to simulate a `Wallet`, and a `WalletSelector` which abstracts the complexity away so an `Application` can easily consume it.
+
+This way, besides showcasing the expected interface for wallets, the reference implementation also gives some hints on how we could include this functionality in Near's[`wallet-selector`](https://github.com/near/wallet-selector/), as well as how an application could use it.
 
 ## Security Implications