Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add redirect field to 1.1 spec #193

Merged
merged 3 commits into from
Feb 28, 2023
Merged

Add redirect field to 1.1 spec #193

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8717cdd
Add success-redirect field to 1.1 spec
mcintyre94 Feb 7, 2023
3e39ca1
Refactor to redirect field + update wording
mcintyre94 Feb 10, 2023
ff89896
Add redirect field to message signing spec
mcintyre94 Feb 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions SPEC1.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ A standard URL protocol for requesting native SOL transfers, SPL Token transfers

These URLs may be encoded in QR codes or NFC tags, or sent between users and applications to request payment and compose transactions.

Applications should ensure that a transaction has been confirmed and is valid before they release goods or services being sold, or grant access to objects or events.
Applications should ensure that a transaction has been confirmed and is valid before they release goods or services being sold, or grant access to objects or events.

Mobile wallets should register to handle the URL scheme to provide a seamless yet secure experience when Solana Pay URLs are encountered in the environment.

Expand All @@ -29,6 +29,7 @@ solana:<recipient>
&label=<label>
&message=<message>
&memo=<memo>
&redirect=<redirect>
```

The request is non-interactive because the parameters in the URL are used by a wallet to directly compose a transaction.
Expand Down Expand Up @@ -78,6 +79,13 @@ The wallet must [URL-decode](https://developer.mozilla.org/en-US/docs/Web/JavaSc

If the field is provided, the wallet must include a `MemoProgram` instruction as the second to last instruction of the transaction, immediately before the SOL or SPL Token transfer instruction, to avoid ambiguity with other instructions in the transaction.

### Redirect
A single `redirect` field is allowed as an optional query parameter. The value must be a [URL-encoded](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) absolute HTTPS or `solana:` URL.

The wallet must [URL-decode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent) the value. If it is a HTTPS URL then the wallet should display the decoded value to the user.

Redirect URLs should only be followed if the transaction is successful. A transaction should be considered successful if the user approves it and the broadcast transaction has a Confirmed or Finalized status. If the redirect is a HTTPS URL then the wallet should open the URL using any browser. This may be a browser included in the wallet. If it is a `solana:` URL then the wallet should treat it as a new Solana Pay request.

### Examples

##### URL describing a transfer request for 1 SOL.
Expand All @@ -95,6 +103,11 @@ solana:mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN?amount=0.01&spl-token=EPjFWdd
solana:mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN&label=Michael
```

##### URL describing a transfer request for 1 SOL with a redirect
```
solana:mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN?amount=1&label=Michael&message=Thanks%20for%20all%20the%20fish&memo=OrderId12345&redirect=https%3A%2F%2Fexample.com
```

## Specification: Transaction Request

A Solana Pay transaction request URL describes an interactive request for any Solana transaction.
Expand Down Expand Up @@ -187,10 +200,22 @@ The `<message>` value must be a UTF-8 string that describes the nature of the tr

For example, this might be the name of an item being purchased, a discount applied to the purchase, or a thank you note. The wallet should display the value to the user.

The application may also include an optional `redirect` field in the response body:

```json
{"redirect":"<redirect>","transaction":"<transaction>"}
mcintyre94 marked this conversation as resolved.
Show resolved Hide resolved
```

The `redirect` field must be an absolute HTTPS or `solana:` URL.

If it is a HTTPS URL then the wallet should display the decoded value to the user.

Redirect URLs should only be followed if the transaction is successful. A transaction should be considered successful if the user approves it and the broadcast transaction has a Confirmed or Finalized [Commitment Status](https://docs.solana.com/cluster/commitments). If the redirect is a HTTPS URL then the wallet should open the URL using any browser. This may be a browser included in the wallet. If it is a `solana:` URL then the wallet should treat it as a new Solana Pay request.

The wallet and application should allow additional fields in the request body and response body, which may be added by future specification.

#### Error Handling
If the application responds with an HTTP [client](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses) or [server](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) error in response to the POST or PUT operations, the wallet must consider the entire transaction request as failed.
If the application responds with an HTTP [client](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses) or [server](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) error in response to the POST or PUT operations, the wallet must consider the entire transaction request as failed.

Client and server errors may optionally be accompanied by a JSON body containing a UTF-8 string `message` field describing the nature of the error:
```json
Expand Down Expand Up @@ -252,7 +277,8 @@ Content-Type: application/json
Content-Length: 298
Content-Encoding: gzip

{"message":"Thanks for all the fish","transaction":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAECC4JMKqNplIXybGb/GhK1ofdVWeuEjXnQor7gi0Y2hMcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQECAAAMAgAAAAAAAAAAAAAA"}
{"message":"Thanks for all the fish","transaction":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAECC4JMKqNplIXybGb/GhK1ofdVWeuEjXnQor7gi0Y2hMcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQECAAAMAgAAAAAAAAAAAAAA",
"redirect": "https://example.com"}
```

## Extensions
Expand Down
11 changes: 11 additions & 0 deletions message-signing-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,15 @@ The `<message>` value must be a UTF-8 encoded string that describes the nature o

For example, this might be the name of the application with which the user is interacting or context about how the sign-message request is being used. The wallet must display at least the first 80 characters of the message field to the user if it is included in the response.

The application may also include an optional `redirect` field in the response body:
```json
{"redirect":"<redirect>", "message":"<message>","data":"<data>","state":"<state>"}
```

The `redirect` field must be an absolute HTTPS or solana URL.

If it is a HTTPS URL then the wallet should display the decoded value to the user.

The wallet and application should allow additional fields in the request body and response body, which may be added by future specification.

#### PUT Request
Expand All @@ -115,6 +124,8 @@ The wallet should display the domain of the URL as the request is being made. If

The wallet must handle HTTP [client](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses) and [server](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) errors in accordance with the [error handling](#error-handling) specification. [Redirect responses](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages) must be handled appropriately. The application must respond with these, or with an HTTP `OK` response. An HTTP `OK` response indicates that signature verification was successful.

If signature verification was successful and there was a `redirect` field in the POST response, then the decoded redirect URL should be followed. If the redirect is a HTTPS URL then the wallet should open the URL using any available browser. This may be a browser included in the wallet. If it is a `solana:` URL then the wallet should treat it as a new Solana Pay request.

The wallet and application should allow additional fields in the request body and response body, which may be added by future specification.

#### Error Handling
Expand Down