From 015cb61cf6b6599e96434a74728f2a0cc202973d Mon Sep 17 00:00:00 2001 From: gagdiez Date: Wed, 18 Dec 2024 14:24:53 +0100 Subject: [PATCH 1/4] Wallet NEP: Sign and Return Signature This NEP proposes to add a new standardized wallet method that allows to request a signature from the user and immediately returns the signed transaction. Such a method will allow applications to take full control of the transaction life-cycle, which apps can profit from to enable better UX and UI by not blocking the user while the transaction is being executed on-chain. Instead, apps can act optimistically, and allow the user to continue the app journey, rolling it back only if the transaction failed. --- neps/nep-0xxx.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 neps/nep-0xxx.md diff --git a/neps/nep-0xxx.md b/neps/nep-0xxx.md new file mode 100644 index 000000000..c017bad22 --- /dev/null +++ b/neps/nep-0xxx.md @@ -0,0 +1,95 @@ +--- +NEP: XXX +Title: Wallet Method - Sign and Return Signature +Authors: Guille +Status: Draft +DiscussionsTo: https://github.com/nearprotocol/neps/pull/xxx +Type: Wallet Standard +Version: 1.0.0 +Created: 2024-12-18 +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. + +## 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. + +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. + +## Specification + +Wallets will need to implement a new method called `signAndReturnSignature` that will work as follows: + +```typescript +export interface Transaction { + actions: Array; + hash: string; + nonce: bigint; + public_key: string; + receiver_id: string; + signature: string; + signer_id: string; +} + +export interface Signature { + signature: Uint8Array; + publicKey: PublicKey; +} + +interface Wallet { + signAndReturnSignature(transaction: Transaction): Promise; +} +``` + +It is important to remark that the definitions of `Transaction` and `SignedTransaction` are taken from `near-api-js` + +## 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` + +## 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/). From 0a699e385b30a73337d18c3a831bb593d3764207 Mon Sep 17 00:00:00 2001 From: gagdiez Date: Wed, 18 Dec 2024 14:37:42 +0100 Subject: [PATCH 2/4] renamed nep file --- neps/{nep-0xxx.md => nep-0582.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename neps/{nep-0xxx.md => nep-0582.md} (100%) diff --git a/neps/nep-0xxx.md b/neps/nep-0582.md similarity index 100% rename from neps/nep-0xxx.md rename to neps/nep-0582.md From aa4bbe4af96fb8b04ea08cfb7ff962fafec5ebaa Mon Sep 17 00:00:00 2001 From: gagdiez Date: Wed, 18 Dec 2024 15:48:50 +0100 Subject: [PATCH 3/4] Minor fixes on text --- neps/nep-0582.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/neps/nep-0582.md b/neps/nep-0582.md index c017bad22..6b31d6490 100644 --- a/neps/nep-0582.md +++ b/neps/nep-0582.md @@ -1,9 +1,9 @@ --- -NEP: XXX -Title: Wallet Method - Sign and Return Signature +NEP: 582 +Title: Wallet Method - Sign and Return Signed Transaction Authors: Guille Status: Draft -DiscussionsTo: https://github.com/nearprotocol/neps/pull/xxx +DiscussionsTo: https://github.com/nearprotocol/neps/pull/582 Type: Wallet Standard Version: 1.0.0 Created: 2024-12-18 @@ -24,7 +24,7 @@ It is important to stress that this NEP is not proposing to remove the current w ## Specification -Wallets will need to implement a new method called `signAndReturnSignature` that will work as follows: +Wallets will need to implement a new method called `signAndReturnSignature` with the following interface: ```typescript export interface Transaction { @@ -47,7 +47,7 @@ interface Wallet { } ``` -It is important to remark that the definitions of `Transaction` and `SignedTransaction` are taken from `near-api-js` +It is important to remark that the definitions of `Transaction` and `Signature` are taken from `near-api-js` ## Reference Implementation From c772ca84b7564be92e97a69a5736aae4704bba6d Mon Sep 17 00:00:00 2001 From: gagdiez Date: Thu, 19 Dec 2024 14:51:22 +0100 Subject: [PATCH 4/4] NEP ready to be reviewed --- neps/nep-0582.md | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/neps/nep-0582.md b/neps/nep-0582.md index 6b31d6490..e1424b701 100644 --- a/neps/nep-0582.md +++ b/neps/nep-0582.md @@ -2,7 +2,7 @@ NEP: 582 Title: Wallet Method - Sign and Return Signed Transaction Authors: Guille -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; + signAndReturnSignature(transaction: Uint8Array): Promise; } ``` -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