[NEP-582]: Wallet Method - Sign and Return Signature

neps/nep-0582.md

@@ -0,0 +1,107 @@
+---
+NEP: 582
+Title: Wallet Method - Sign and Return Signed Transaction
+Authors: Guille <[email protected]>
+Status: Review
+DiscussionsTo: https://github.com/nearprotocol/neps/pull/582
+Type: Wallet Standard
+Version: 1.0.0
+Created: 2024-12-18
+LastUpdated: 2024-12-18
+---
+
+## Summary
+
+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, 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** for applications to choose from.
+
+## Specification
+
+Wallets will need to implement a new method called `signAndReturnSignature` with the following interface:
+
+```typescript
+export interface Transaction {
+    actions: Array<any>;
+    hash: string;
+    nonce: bigint;
+    public_key: string;
+    receiver_id: string;
+    signature: string;
+    signer_id: string;
+
+    encode(): Uint8Array; // Borsh serialization
+}
+
+export interface Signature {
+    signature: Uint8Array;
+    publicKey: PublicKey;
+}
+
+interface Wallet {
+  signAndReturnSignature(transaction: Uint8Array): Promise<Signature>;
+}
+```
+
+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
+
+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
+
+As the user will still have to sign transactions through their wallet, this method does not introduce any new security risks.
+
+## Alternatives
+
+An alternative would be to make wallets handle the transaction lifecycle, but implement methods to allow applications to query the status of a transaction.
+
+However, this would add more complexity to wallets - which will now need to store the transaction status, and implement methods for apps to query it - while not providing any true benefit to applications, since apps will have to track the status of transactions anyway.
+
+## Consequences
+
+We will have to request all wallets to implement this new method, and update the `wallet selector` to make the feature widely available to all applications.
+
+## Changelog
+
+### 1.0.0 - Initial Version
+
+> Placeholder for the context about when and who approved this NEP version.
+
+#### Benefits
+
+> List of benefits filled by the Subject Matter Experts while reviewing this version:
+
+- Benefit 1
+- Benefit 2
+
+#### Concerns
+
+> Template for Subject Matter Experts review for this version:
+> Status: New | Ongoing | Resolved
+
+|   # | Concern | Resolution | Status |
+| --: | :------ | :--------- | -----: |
+|   1 |         |            |        |
+|   2 |         |            |        |
+
+## Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).