From 9b2cbd7c325986175e7444d05966a52629aa0f6a Mon Sep 17 00:00:00 2001 From: janniks Date: Fri, 12 Jan 2024 17:17:54 +0100 Subject: [PATCH 01/46] feat: add wallet api sip --- sips/sip-02X/sip-02X-wallet-interface.md | 213 +++++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 sips/sip-02X/sip-02X-wallet-interface.md diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md new file mode 100644 index 00000000..772e1c24 --- /dev/null +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -0,0 +1,213 @@ +# Preamble + +SIP Number: `To be assigned` + +Title: Integration of WebBTC Request Standard for Stacks Wallets + +Authors: [janniks](https://github.com/janniks), `todo` + +Type: Standard + +Status: Draft + +Created: 10 October 2023 + +License: BSD 2-Clause + +# Abstract + +This SIP proposes the integration of the WebBTC request standard into the Stacks blockchain's Connect system. The goal is to replace the current Connect interface, primarily used by web applications to connect with browser extensions and mobile apps, with a more streamlined and efficient protocol. + +# Motivation + +The current Connect system, which has evolved since the Blockstack era, is now primarily utilized by web applaications for interfacing with wallets. However, many aspects of the existing "Connect" and "Auth" libraries are no longer required, leading to unnecessary complexity and brittleness in wallet connectivity. + +Recent attempts to standardize the interface have sparked valuable discussions but have not culminated in a ratified standard, largely due to the stable state of the existing system. This SIP aims to address these issues by adopting the WebBTC request standard, which offers a more suitable RPC-style interface for modern web applications. + +Additionally, this SIP is motivated by the increased traffic of Ordinal inscriptions on Bitcoin and the Stacks ecosystem growing closers to Bitcoin. The community has recognized the need for a more unified approach to wallet connectivity. Recently, diverging viewpoints and disagreements on methodologies have hindered progress. By adopting the WebBTC request standard, we aim to align the community towards a common, efficient, and modern protocol for wallet interaction in web applications. Importantly, the decision to use an existing standard rather than inventing a new one is intentional, to avoid further division or split ownership within the community. + +# Specification + +The proposed changes are as follows: + +Integration of WebBTC Request Standard: The WebBTC request standard will be adopted to replace the current Connect system. This standard provides a flexible RPC-style interface for web applications to interact with wallets. +The RPC payload is also standardized on its own for use in various contexts. + +Backward Compatibility for Wallets: Wallets are encouraged to implement the new webbtc request interface. To maintain backward compatibility, wallets may choose to retain the previous system alongside the new interface. This approach ensures uninterrupted service for applications that have not yet migrated to the new standard. +Detailed Implementation Guidelines: Detailed guidelines and best practices for integrating the webbtc request standard will be provided. This includes technical specifications, sample code, and migration strategies for both web applications and wallet providers. +Rationale + +The adoption of the webbtc request standard is driven by the need for a more robust and simplified connection protocol between web applications and wallets. This standard provides a modernized approach that aligns with current web development practices, offering better performance, security, and ease of use. + +# Backwards Compatibility + +The implementation of this proposal is not necessarily backward compatible. +However, wallets implementing the new standard are advised to maintain the previous system to support legacy applications during a transition period. +Existing applications using the current Auth system should continue to operate, but immediate changes are recommended once this SIP is ratified. + +# Implementation + +## Notes on Serialization + +The WebBTC request standard is inspired by JSON-RPC 2.0 for serialization. +To adhere to a generic serializability, the following notes are given. +Enums are serialized as humand-readable strings. +BigInts are serialized as numbers, strings, or anything else that can be parsed by the JavaScript BigInt constructor. +Bytes are serialized as hex-encoded strings (without the 0x prefix). +Predefined formats from previous SIPs are used where applicable. +Addresses are serialized as Stacks c32-encoded strings. +Clarity values, post-conditions, and transactions are serialized to bytes (defined by SIP-005) and used as hex-encoded strings. + +## Methods + +This section defines the available methods, their parameters, and result structure. +Parameters should be considered recommendations for the wallet. +The user/wallet may choose to ignore/override them. +Optional params are marked with a `?`. + +### Method Independent + +#### Transfer & Transaction Definitions + +`params` + +- `network?`: `'mainnet' | 'testnet' | 'regtest' | 'mocknet'` +- `fee?`: `number | string` (anything parseable by the BigInt constructor) +- `nonce?`: `number | string` (anything parseable by the BigInt constructor) +- `attachment?`: `string` hex-encoded +- `anchoreMode?`: `'onChainOnly' | 'offChainOnly' | 'any'` +- `postConditionMode?`: `'allow' | 'deny'` +- `postConditions?`: `PostCondition[]`, defaults to `[]` +- `sponsored?`: `boolean`, defaults to `false` +- `sender?`: `string` address, Stacks c32-encoded +- ~~`appDetails`~~ _removed_ +- ~~`onFinish`~~ _removed_ +- ~~`onCancel`~~ _removed_ + +`where` + +- `PostCondition`: `string` hex-encoded + +### `transferStx` + +`params` + +- `recipient`: `string` address, Stacks c32-encoded +- `amount`: `number | string` (anything parseable by the BigInt constructor) +- `memo?`: `string`, defaults to `''` + +`result` + +- `txId`: `string` hex-encoded +- `txRaw`: `string` hex-encoded + +### `transferFt` + +`todo: haven't existed yet, should we add them?` + +### `transferNft` + +`todo: haven't existed yet, should we add them?` + +### `contractCall` + +`params` + +- `contractAddress`: `string` address, Stacks c32-encoded +- `contractName`: `string` +- `functionName`: `string` +- `functionArgs`: `ClarityValue[]`, defaults to `[]` + +`where` + +- `ClarityValue`: `string` hex-encoded + +`result` + +- `txId`: `string` hex-encoded +- `txRaw`: `string` hex-encoded + +### `contractDeploy` + +`params` + +- `contractName`: `string` +- `codeBody`: `string` Clarity contract code +- `clarityVersion?`: `number` + +`result` + +- `txId`: `string` hex-encoded +- `txRaw`: `string` hex-encoded + +### `signTransaction` + +`params` + +- `txRaw`: `string` hex-encoded + +`result` + +- `txRaw`: `string` hex-encoded (signed) + +### `signMessage` + +`params` + +- `message`: `string` + +`result` + +- `signature`: `string` hex-encoded +- `publicKey`: `string` hex-encoded + +### `signStructuredMessage` + +`params` + +- `message`: `string` Clarity value, hex-encoded +- `domain?`: `string` hex-encoded (defined by SIP-018) + +> `domain` can be optional if the wallet (e.g. browser extension) can infer it from the origin of the request. + +### `updateProfile` + +`params` + +- `profile`: `object` Schema.org Person object + +`result` + +- `profile`: `object` updated Schema.org Person object + +## Provider Registration + +Wallets can register their aliased provider objects according to WBIP-004. + +# Ratification + +This SIP is considered ratified after at least two major wallets in the Stacks ecosystem have implemented and launched the new standard. + +# Commentary + +The Connect library should be updated to utilize the new standard, once Leather and Xverse have adopted the new standard. +The existing Connect interfaces should be kept compatible to provide a transition without breaking the interface. + +# Links + +Discussions + +- [Wallet JSON RPC API, Request Accounts #2378](https://github.com/leather-wallet/extension/pull/2378) +- [Sign-in with stacks #70](https://github.com/stacksgov/sips/pull/70) +- [Add API to request addresses #2371](https://github.com/leather-wallet/extension/issues/2371) +- [SIP for Wallet Protocol #59](https://github.com/stacksgov/sips/pull/59) +- [SIP for Authentication Protocol #50](https://github.com/stacksgov/sips/pull/50) + +References + +- [WebBTC Request Standard](https://balls.dev/webbtc/extendability/extending/) +- [WBIPs](https://webbtc.netlify.app/wbips) +- [Xverse WalletConnect JSON API](https://docs.xverse.app/wallet-connect/reference/api_reference) +- [Schema.org Person](https://schema.org/Person) + +`todo: any other relevant references` From 72781923ce9ec2e05f3efd79dbea2f10677e5eb7 Mon Sep 17 00:00:00 2001 From: janniks Date: Fri, 12 Jan 2024 17:28:02 +0100 Subject: [PATCH 02/46] fix: add note on namespaces --- sips/sip-02X/sip-02X-wallet-interface.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 772e1c24..a6e3c384 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -65,6 +65,9 @@ Parameters should be considered recommendations for the wallet. The user/wallet may choose to ignore/override them. Optional params are marked with a `?`. +Methods can be namespaced under `stx_` if used in settings like WebBTC (see WBIP-002). +In other cases (e.g. WalletConnect), the namespace may already be given by meta-data (e.g. a `chainId` field) and can be omitted. + ### Method Independent #### Transfer & Transaction Definitions From ad07fd033cd49767f5c403d0a2f0afa8bef8e6b6 Mon Sep 17 00:00:00 2001 From: janniks <6362150+janniks@users.noreply.github.com> Date: Tue, 30 Jan 2024 14:34:39 +0100 Subject: [PATCH 03/46] fix: update tx results --- sips/sip-02X/sip-02X-wallet-interface.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index a6e3c384..90aa9c32 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -101,8 +101,8 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- `result` -- `txId`: `string` hex-encoded -- `txRaw`: `string` hex-encoded +- `txid`: `string` hex-encoded +- `transaction`: `string` hex-encoded ### `transferFt` @@ -127,8 +127,8 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- `result` -- `txId`: `string` hex-encoded -- `txRaw`: `string` hex-encoded +- `txid`: `string` hex-encoded +- `transaction`: `string` hex-encoded ### `contractDeploy` @@ -140,8 +140,8 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- `result` -- `txId`: `string` hex-encoded -- `txRaw`: `string` hex-encoded +- `txid`: `string` hex-encoded +- `transaction`: `string` hex-encoded ### `signTransaction` @@ -151,7 +151,7 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- `result` -- `txRaw`: `string` hex-encoded (signed) +- `transaction`: `string` hex-encoded (signed) ### `signMessage` From 4ad74cdbc80883d1a04dc5e2ed3d2606dd8634b9 Mon Sep 17 00:00:00 2001 From: janniks Date: Tue, 30 Jan 2024 16:17:11 +0100 Subject: [PATCH 04/46] chore: minor updates --- sips/sip-02X/sip-02X-wallet-interface.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 90aa9c32..146d37e6 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -33,11 +33,11 @@ The proposed changes are as follows: Integration of WebBTC Request Standard: The WebBTC request standard will be adopted to replace the current Connect system. This standard provides a flexible RPC-style interface for web applications to interact with wallets. The RPC payload is also standardized on its own for use in various contexts. -Backward Compatibility for Wallets: Wallets are encouraged to implement the new webbtc request interface. To maintain backward compatibility, wallets may choose to retain the previous system alongside the new interface. This approach ensures uninterrupted service for applications that have not yet migrated to the new standard. -Detailed Implementation Guidelines: Detailed guidelines and best practices for integrating the webbtc request standard will be provided. This includes technical specifications, sample code, and migration strategies for both web applications and wallet providers. +Backward Compatibility for Wallets: Wallets are encouraged to implement the new WebBTC request interface. To maintain backward compatibility, wallets may choose to retain the previous system alongside the new interface. This approach ensures uninterrupted service for applications that have not yet migrated to the new standard. +Detailed Implementation Guidelines: Detailed guidelines and best practices for integrating the WebBTC request standard will be provided. This includes technical specifications, sample code, and migration strategies for both web applications and wallet providers. Rationale -The adoption of the webbtc request standard is driven by the need for a more robust and simplified connection protocol between web applications and wallets. This standard provides a modernized approach that aligns with current web development practices, offering better performance, security, and ease of use. +The adoption of the WebBTC request standard is driven by the need for a more robust and simplified connection protocol between web applications and wallets. This standard provides a modernized approach that aligns with current web development practices, offering better performance, security, and ease of use. # Backwards Compatibility @@ -147,7 +147,7 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- `params` -- `txRaw`: `string` hex-encoded +- `transaction`: `string` hex-encoded `result` From 6584e3a3ed5ec33c37649d2dba10fa2fa1bda17a Mon Sep 17 00:00:00 2001 From: janniks Date: Wed, 14 Feb 2024 19:59:26 +0100 Subject: [PATCH 05/46] chore: add open questions --- sips/sip-02X/sip-02X-wallet-interface.md | 32 ++++++++++++++++-------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 146d37e6..b0678b5a 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -14,6 +14,15 @@ Created: 10 October 2023 License: BSD 2-Clause +# OPEN QUESTIONS + + + +- [ ] Should we add `stx_transferFt` and `stx_transferNft`? +- [ ] Should `sender` in the params be renamed to `address`/`account`, or stay `sender for added clarity VS recipient/etc.? +- [ ] Should Clarity values and maybe other types be hex-encoded, or is there a better idea that has similar benefits (no dependencies, but is easier to work with)? + - For Clarity values, we could use strings (e.g. `u123`, `"text"`, `0x4be9`, `{ key: u3 }`) and parse the Clarity expression in the wallet. The only downside (I can think of) -- apart from additional wallet dev cost -- is cases like strings which need quotes, but this might not be clear to the user. + # Abstract This SIP proposes the integration of the WebBTC request standard into the Stacks blockchain's Connect system. The goal is to replace the current Connect interface, primarily used by web applications to connect with browser extensions and mobile apps, with a more streamlined and efficient protocol. @@ -65,8 +74,9 @@ Parameters should be considered recommendations for the wallet. The user/wallet may choose to ignore/override them. Optional params are marked with a `?`. -Methods can be namespaced under `stx_` if used in settings like WebBTC (see WBIP-002). +Methods can be namespaced under `stx_` if used in settings like WebBTC (see WBIP-002) and other more Ethereum inspired domains. In other cases (e.g. WalletConnect), the namespace may already be given by meta-data (e.g. a `chainId` field) and can be omitted. +On the predominant `StacksProvider` global object, the methods can be used without a namespace, but wallet may add namespaced aliases for convenience. ### Method Independent @@ -82,7 +92,7 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- - `postConditionMode?`: `'allow' | 'deny'` - `postConditions?`: `PostCondition[]`, defaults to `[]` - `sponsored?`: `boolean`, defaults to `false` -- `sender?`: `string` address, Stacks c32-encoded +- `address?`: `string` address, Stacks c32-encoded (sender or signer address), defaults to wallets current address - ~~`appDetails`~~ _removed_ - ~~`onFinish`~~ _removed_ - ~~`onCancel`~~ _removed_ @@ -91,7 +101,7 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- - `PostCondition`: `string` hex-encoded -### `transferStx` +### `stx_transferStx` `params` @@ -104,15 +114,15 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded -### `transferFt` +### `stx_transferFt` `todo: haven't existed yet, should we add them?` -### `transferNft` +### `stx_transferNft` `todo: haven't existed yet, should we add them?` -### `contractCall` +### `stx_contractCall` `params` @@ -130,7 +140,7 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded -### `contractDeploy` +### `stx_contractDeploy` `params` @@ -143,7 +153,7 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded -### `signTransaction` +### `stx_signTransaction` `params` @@ -153,7 +163,7 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- - `transaction`: `string` hex-encoded (signed) -### `signMessage` +### `stx_signMessage` `params` @@ -164,7 +174,7 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- - `signature`: `string` hex-encoded - `publicKey`: `string` hex-encoded -### `signStructuredMessage` +### `stx_signStructuredMessage` `params` @@ -173,7 +183,7 @@ In other cases (e.g. WalletConnect), the namespace may already be given by meta- > `domain` can be optional if the wallet (e.g. browser extension) can infer it from the origin of the request. -### `updateProfile` +### `stx_updateProfile` `params` From c3d503f4017bcdf2b3683f2d43dd1c81380660a7 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 15 Feb 2024 23:18:01 +0100 Subject: [PATCH 06/46] fix: update address and account methods --- sips/sip-02X/sip-02X-wallet-interface.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index b0678b5a..fd51065e 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -80,7 +80,9 @@ On the predominant `StacksProvider` global object, the methods can be used witho ### Method Independent -#### Transfer & Transaction Definitions +#### Common Definitions + +The following definitions can be used in multiple methods (mainly for transfer and transaction methods). `params` @@ -183,6 +185,24 @@ On the predominant `StacksProvider` global object, the methods can be used witho > `domain` can be optional if the wallet (e.g. browser extension) can infer it from the origin of the request. +### `stx_getAddresses` + +`result` + +- `addresses`: `{}[]` + - `address`: `string` address, Stacks c32-encoded + - `publicKey`: `string` hex-encoded + +### `stx_getAccounts` + +`result` + +- `addresses`: `{}[]` + - `address`: `string` address, Stacks c32-encoded + - `publicKey`: `string` hex-encoded + - `gaiaHubUrl`: `string` URL + - `gaiaAppKey`: `string` hex-encoded + ### `stx_updateProfile` `params` From d5375e6c8a701636708bab0d76f116211bd861c4 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 15 Feb 2024 23:54:19 +0100 Subject: [PATCH 07/46] chore: update sip --- sips/sip-02X/sip-02X-wallet-interface.md | 44 +++++++++++------------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index fd51065e..c4d3868d 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -21,38 +21,43 @@ License: BSD 2-Clause - [ ] Should we add `stx_transferFt` and `stx_transferNft`? - [ ] Should `sender` in the params be renamed to `address`/`account`, or stay `sender for added clarity VS recipient/etc.? - [ ] Should Clarity values and maybe other types be hex-encoded, or is there a better idea that has similar benefits (no dependencies, but is easier to work with)? - - For Clarity values, we could use strings (e.g. `u123`, `"text"`, `0x4be9`, `{ key: u3 }`) and parse the Clarity expression in the wallet. The only downside (I can think of) -- apart from additional wallet dev cost -- is cases like strings which need quotes, but this might not be clear to the user. + - For Clarity values, we could use strings (e.g. `u123`, `"text"`, `0x4be9`, `{ key: u3 }`) and parse the Clarity expression in the wallet. The only downside (I can think of) -- apart from additional wallet dev cost -- is cases like strings which need quotes, but this might not be clear to the user. A function/library for this would be provided by Stacks.js. # Abstract -This SIP proposes the integration of the WebBTC request standard into the Stacks blockchain's Connect system. The goal is to replace the current Connect interface, primarily used by web applications to connect with browser extensions and mobile apps, with a more streamlined and efficient protocol. +This SIP proposes the integration of the WebBTC request standard into the Stacks blockchain's Connect system. +The goal is to replace the current Connect interface, primarily used by web applications to connect with browser extensions and mobile apps, with a more straightforward protocol. # Motivation -The current Connect system, which has evolved since the Blockstack era, is now primarily utilized by web applaications for interfacing with wallets. However, many aspects of the existing "Connect" and "Auth" libraries are no longer required, leading to unnecessary complexity and brittleness in wallet connectivity. +The current Connect system, which has evolved since the Blockstack era, is primarily utilized by web applications for interfacing with wallets. +However, many aspects of the existing "Connect" and "Auth" libraries are no longer required, leading to unnecessary complexity and brittleness in wallet connectivity. -Recent attempts to standardize the interface have sparked valuable discussions but have not culminated in a ratified standard, largely due to the stable state of the existing system. This SIP aims to address these issues by adopting the WebBTC request standard, which offers a more suitable RPC-style interface for modern web applications. +Recent attempts to standardize the interface have sparked valuable discussions but have not culminated in a ratified standard, largely due to the stable state of the existing system. +This SIP aims to address these issues by adopting the WebBTC request standard, which offers a more suitable RPC-style interface for modern web applications. +The simplified protocol will allow integration without heavy dependencies (like Auth) and provider a more extendable interface for wallets. -Additionally, this SIP is motivated by the increased traffic of Ordinal inscriptions on Bitcoin and the Stacks ecosystem growing closers to Bitcoin. The community has recognized the need for a more unified approach to wallet connectivity. Recently, diverging viewpoints and disagreements on methodologies have hindered progress. By adopting the WebBTC request standard, we aim to align the community towards a common, efficient, and modern protocol for wallet interaction in web applications. Importantly, the decision to use an existing standard rather than inventing a new one is intentional, to avoid further division or split ownership within the community. +Additionally, this SIP is motivated by the increased traffic of Ordinal inscriptions on Bitcoin and the Stacks ecosystem growing closers to Bitcoin. +The community has recognized the need for a more unified approach to wallet connectivity. +Recently, diverging viewpoints and disagreements on methodologies have hindered progress. +By adopting the WebBTC request standard, we aim to align the community towards a common and modern protocol for wallet interaction in web applications. +Importantly, the decision to use an existing standard (rather than designing a new one or reworking Auth) is intentional — to avoid further division or split ownership within the community. # Specification -The proposed changes are as follows: +The proposed changes are listed as follows: -Integration of WebBTC Request Standard: The WebBTC request standard will be adopted to replace the current Connect system. This standard provides a flexible RPC-style interface for web applications to interact with wallets. -The RPC payload is also standardized on its own for use in various contexts. +Specify JSON-RPC 2.0 compatible methods and payloads for wallet interaction. +These can be used via the WebBTC request standard (i.e., via the `window.webbtc.request` method) or similar interfaces like WalletConnect. -Backward Compatibility for Wallets: Wallets are encouraged to implement the new WebBTC request interface. To maintain backward compatibility, wallets may choose to retain the previous system alongside the new interface. This approach ensures uninterrupted service for applications that have not yet migrated to the new standard. -Detailed Implementation Guidelines: Detailed guidelines and best practices for integrating the WebBTC request standard will be provided. This includes technical specifications, sample code, and migration strategies for both web applications and wallet providers. -Rationale - -The adoption of the WebBTC request standard is driven by the need for a more robust and simplified connection protocol between web applications and wallets. This standard provides a modernized approach that aligns with current web development practices, offering better performance, security, and ease of use. +Adopt the WebBTC request standard as the default interface between web-application and wallets — replacing components of the current Auth system in Connect. # Backwards Compatibility The implementation of this proposal is not necessarily backward compatible. However, wallets implementing the new standard are advised to maintain the previous system to support legacy applications during a transition period. Existing applications using the current Auth system should continue to operate, but immediate changes are recommended once this SIP is ratified. +The Connect library should be go live with the new standard, once most major wallets have adopted the new standard. # Implementation @@ -61,8 +66,8 @@ Existing applications using the current Auth system should continue to operate, The WebBTC request standard is inspired by JSON-RPC 2.0 for serialization. To adhere to a generic serializability, the following notes are given. Enums are serialized as humand-readable strings. -BigInts are serialized as numbers, strings, or anything else that can be parsed by the JavaScript BigInt constructor. -Bytes are serialized as hex-encoded strings (without the 0x prefix). +BigInts are serialized as numbers, strings, or anything that can be parsed by the JavaScript BigInt constructor. +Bytes are serialized as hex-encoded strings (without a 0x prefix). Predefined formats from previous SIPs are used where applicable. Addresses are serialized as Stacks c32-encoded strings. Clarity values, post-conditions, and transactions are serialized to bytes (defined by SIP-005) and used as hex-encoded strings. @@ -76,7 +81,7 @@ Optional params are marked with a `?`. Methods can be namespaced under `stx_` if used in settings like WebBTC (see WBIP-002) and other more Ethereum inspired domains. In other cases (e.g. WalletConnect), the namespace may already be given by meta-data (e.g. a `chainId` field) and can be omitted. -On the predominant `StacksProvider` global object, the methods can be used without a namespace, but wallet may add namespaced aliases for convenience. +On the predominant `StacksProvider` global object, the methods can be used without a namespace, but wallets may add namespaced aliases for convenience. ### Method Independent @@ -221,11 +226,6 @@ Wallets can register their aliased provider objects according to WBIP-004. This SIP is considered ratified after at least two major wallets in the Stacks ecosystem have implemented and launched the new standard. -# Commentary - -The Connect library should be updated to utilize the new standard, once Leather and Xverse have adopted the new standard. -The existing Connect interfaces should be kept compatible to provide a transition without breaking the interface. - # Links Discussions @@ -242,5 +242,3 @@ References - [WBIPs](https://webbtc.netlify.app/wbips) - [Xverse WalletConnect JSON API](https://docs.xverse.app/wallet-connect/reference/api_reference) - [Schema.org Person](https://schema.org/Person) - -`todo: any other relevant references` From 425f81ca2aacab06f92c84b8a88023a94a2a6b82 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 29 Feb 2024 15:03:18 +0100 Subject: [PATCH 08/46] docs: add new js representation --- sips/sip-02X/sip-02X-wallet-interface.md | 284 ++++++++++++++++++++--- 1 file changed, 256 insertions(+), 28 deletions(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index c4d3868d..8ba5c81e 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -18,9 +18,10 @@ License: BSD 2-Clause +- [ ] Should post-condition `type` be called `condition` or something (future overlap with clarity value?) or something else. Suffix `-condition`? - [ ] Should we add `stx_transferFt` and `stx_transferNft`? -- [ ] Should `sender` in the params be renamed to `address`/`account`, or stay `sender for added clarity VS recipient/etc.? -- [ ] Should Clarity values and maybe other types be hex-encoded, or is there a better idea that has similar benefits (no dependencies, but is easier to work with)? +- [x] Change sender to `address`~~/`account`, or stay `sender for added clarity VS recipient/etc.?~~ +- [x] Should Clarity values and maybe other types be hex-encoded, or is there a better idea that has similar benefits (no dependencies, but is easier to work with)? - For Clarity values, we could use strings (e.g. `u123`, `"text"`, `0x4be9`, `{ key: u3 }`) and parse the Clarity expression in the wallet. The only downside (I can think of) -- apart from additional wallet dev cost -- is cases like strings which need quotes, but this might not be clear to the user. A function/library for this would be provided by Stacks.js. # Abstract @@ -83,23 +84,21 @@ Methods can be namespaced under `stx_` if used in settings like WebBTC (see WBIP In other cases (e.g. WalletConnect), the namespace may already be given by meta-data (e.g. a `chainId` field) and can be omitted. On the predominant `StacksProvider` global object, the methods can be used without a namespace, but wallets may add namespaced aliases for convenience. -### Method Independent - -#### Common Definitions +#### Common definitions The following definitions can be used in multiple methods (mainly for transfer and transaction methods). `params` +- `address?`: `string` address, Stacks c32-encoded, defaults to wallets current address - `network?`: `'mainnet' | 'testnet' | 'regtest' | 'mocknet'` - `fee?`: `number | string` (anything parseable by the BigInt constructor) - `nonce?`: `number | string` (anything parseable by the BigInt constructor) - `attachment?`: `string` hex-encoded -- `anchoreMode?`: `'onChainOnly' | 'offChainOnly' | 'any'` -- `postConditionMode?`: `'allow' | 'deny'` +- `anchorMode?`: `'on-chain' | 'off-chain' | 'any'` - `postConditions?`: `PostCondition[]`, defaults to `[]` +- `postConditionMode?`: `'allow' | 'deny'` - `sponsored?`: `boolean`, defaults to `false` -- `address?`: `string` address, Stacks c32-encoded (sender or signer address), defaults to wallets current address - ~~`appDetails`~~ _removed_ - ~~`onFinish`~~ _removed_ - ~~`onCancel`~~ _removed_ @@ -108,7 +107,9 @@ The following definitions can be used in multiple methods (mainly for transfer a - `PostCondition`: `string` hex-encoded -### `stx_transferStx` +--- + +### Method `stx_transferStx` `params` @@ -121,22 +122,21 @@ The following definitions can be used in multiple methods (mainly for transfer a - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded -### `stx_transferFt` +### Method `stx_transferFt` `todo: haven't existed yet, should we add them?` -### `stx_transferNft` +### Method `stx_transferNft` `todo: haven't existed yet, should we add them?` -### `stx_contractCall` +### Method `stx_callContract` `params` -- `contractAddress`: `string` address, Stacks c32-encoded -- `contractName`: `string` -- `functionName`: `string` -- `functionArgs`: `ClarityValue[]`, defaults to `[]` +- `contract`: `string.string` address with contract name suffix, Stacks c32-encoded +- `function`: `string` +- `arguments`: `ClarityValue[]`, defaults to `[]` `where` @@ -147,12 +147,12 @@ The following definitions can be used in multiple methods (mainly for transfer a - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded -### `stx_contractDeploy` +### Method `stx_deployContract` `params` -- `contractName`: `string` -- `codeBody`: `string` Clarity contract code +- `name`: `string` +- `clarityCode`: `string` Clarity contract code - `clarityVersion?`: `number` `result` @@ -160,7 +160,7 @@ The following definitions can be used in multiple methods (mainly for transfer a - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded -### `stx_signTransaction` +### Method `stx_signTransaction` `params` @@ -170,7 +170,7 @@ The following definitions can be used in multiple methods (mainly for transfer a - `transaction`: `string` hex-encoded (signed) -### `stx_signMessage` +### Method `stx_signMessage` `params` @@ -181,16 +181,19 @@ The following definitions can be used in multiple methods (mainly for transfer a - `signature`: `string` hex-encoded - `publicKey`: `string` hex-encoded -### `stx_signStructuredMessage` +### Method `stx_signStructuredMessage` `params` - `message`: `string` Clarity value, hex-encoded -- `domain?`: `string` hex-encoded (defined by SIP-018) +- `domain`: `string` hex-encoded (defined by SIP-018) + +`result` -> `domain` can be optional if the wallet (e.g. browser extension) can infer it from the origin of the request. +- `signature`: `string` hex-encoded +- `publicKey`: `string` hex-encoded -### `stx_getAddresses` +### Method `stx_getAddresses` `result` @@ -198,7 +201,7 @@ The following definitions can be used in multiple methods (mainly for transfer a - `address`: `string` address, Stacks c32-encoded - `publicKey`: `string` hex-encoded -### `stx_getAccounts` +### Method `stx_getAccounts` `result` @@ -208,7 +211,7 @@ The following definitions can be used in multiple methods (mainly for transfer a - `gaiaHubUrl`: `string` URL - `gaiaAppKey`: `string` hex-encoded -### `stx_updateProfile` +### Method `stx_updateProfile` `params` @@ -218,7 +221,232 @@ The following definitions can be used in multiple methods (mainly for transfer a - `profile`: `object` updated Schema.org Person object -## Provider Registration +## JS Representations + +While discussing this SIP, it has become clear that the current Stacks.js representation is confusing to developers. +Rather, a better solution would be human-readable — for example, rely on string literal enumeration, rather than magic values, which need additional lookups. +Relying on soley a hex-encoded also poses difficulties when building Stacks enabled web applications. + +### Clarity values + +Proposed below is an updated interface representation for Clarity primitives for use in Stacks.js and JSON compatible environments. + +> For encoding larger than JS `Number` big integers, `string` is used. + +`0x00` `int` + +```ts +{ + type: "int", + value: string // `bigint` compatible +} +``` + +`0x01` `uint` + +```ts +{ + type: "uint", + value: string // `bigint` compatible +} +``` + +`0x02` `buffer` + +```ts +{ + type: "buffer", + value: string // hex-encoded string +} +``` + +`0x03` `bool` `true` + +```ts +{ + type: "true", +} +``` + +`0x04` `bool` `false` + +```ts +{ + type: "false", +} +``` + +`0x05` `address` (aka "standard principal") + +```ts +{ + type: "address", + value: string // Stacks c32-encoded +} +``` + +`0x06` `contract` (aka "contract principal") + +```ts +{ + type: "contract", + value: `${string}.${string}` // Stacks c32-encoded, with contract name suffix +} +``` + +`0x07` `ok` (aka "response ok") + +```ts +{ + type: "ok", + value: object // Clarity value +} +``` + +`0x08` `err` (aka "response err") + +```ts +{ + type: "err", + value: object // Clarity value +} +``` + +`0x09` `none` (aka "optional none") + +```ts +{ + type: "none", +} +``` + +`0x0a` `some` (aka "optional some") + +```ts +{ + type: "some", + value: object // Clarity value +} +``` + +`0x0b` `list` + +```ts +{ + type: "list", + value: object[] // Array of Clarity values +} +``` + +`0x0c` `tuple` + +```ts +{ + type: "tuple", + value: Record // Record of Clarity values +} +``` + +`0x0d` `ascii` + +```ts +{ + type: "ascii", + value: string // ASCII-compatible string +} +``` + +`0x0e` `utf8` + +```ts +{ + type: "utf8", + value: string +} +``` + +### Post conditions + +`0x00` STX + +```ts +{ + type: 'stx', + address: string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix + condition: 'eq' | 'gt' | 'gte' | 'lt' | 'lte', + amount: string // `bigint` compatible, amount in mirco-STX +} +``` + +`0x01` Fungible token + +```ts +{ + type: 'ft', + address: string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix + condition: 'eq' | 'gt' | 'gte' | 'lt' | 'lte', + asset: `${string}.${string}::${string}` // Stacks c32-encoded address, with contract name suffix, with asset suffix + amount: string // `bigint` compatible, amount in lowest integer denomination of fungible token +} +``` + +`0x02` Non-fungible token + +```ts +{ + type: 'nft', + address: string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix + condition: 'sent' | 'not-sent', + asset: `${string}.${string}::${string}` // address with contract name suffix with asset suffix, Stacks c32-encoded + assetId: object, // Clarity value +} +``` + +### Test vectors + +Listed below are some examples of the potentially unclear representations: + +- `u12` = `{ type: 'uint', value: "12" }` +- `0xbeaf` = `{ type: 'ascii', value: "hello there" }` +- `"hello there"` = `{ type: 'ascii', value: "hello there" }` +- `(list 4 8)` = + ``` + { + type: 'list', + value: [ + { type: 'int', value: "4"}, + { type: 'int', value: "8"}, + ] + } + ``` +- `(err u4)` = + ``` + { + type: 'err', + value: { type: 'uint', value: "4"}, + } + ``` +- "sends more than 10000 uSTX" = + ``` + { + type: 'stx', + address: 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6', + amount: '10000', + condition: 'gt' + } + ``` +- "does not send the `12` TKN non-fungible token" = + ``` + { + type: 'ntf', + address: 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.vault' + asset: 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.tokencoin::tkn', + assetId: { type: 'uint', value: '12' } + condition: 'not-sent' + } + ``` + +## Provider registration Wallets can register their aliased provider objects according to WBIP-004. From a32fb1143a645ab863a00374b7ec775918a37106 Mon Sep 17 00:00:00 2001 From: janniks Date: Tue, 5 Mar 2024 13:12:16 +0100 Subject: [PATCH 09/46] docs: update methods --- sips/sip-02X/sip-02X-wallet-interface.md | 125 ++++++++++++++--------- 1 file changed, 76 insertions(+), 49 deletions(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 8ba5c81e..8c58ad31 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -92,8 +92,8 @@ The following definitions can be used in multiple methods (mainly for transfer a - `address?`: `string` address, Stacks c32-encoded, defaults to wallets current address - `network?`: `'mainnet' | 'testnet' | 'regtest' | 'mocknet'` -- `fee?`: `number | string` (anything parseable by the BigInt constructor) -- `nonce?`: `number | string` (anything parseable by the BigInt constructor) +- `fee?`: `number | string` BigInt constructor compatible value +- `nonce?`: `number | string` BigInt constructor compatible value - `attachment?`: `string` hex-encoded - `anchorMode?`: `'on-chain' | 'off-chain' | 'any'` - `postConditions?`: `PostCondition[]`, defaults to `[]` @@ -105,47 +105,71 @@ The following definitions can be used in multiple methods (mainly for transfer a `where` -- `PostCondition`: `string` hex-encoded +- `PostCondition`: `string | object` hex-encoded or JSON representation --- ### Method `stx_transferStx` +> **Comment**: This method doesn't take post-conditions. + `params` - `recipient`: `string` address, Stacks c32-encoded -- `amount`: `number | string` (anything parseable by the BigInt constructor) +- `amount`: `number | string` BigInt constructor compatible value - `memo?`: `string`, defaults to `''` `result` - `txid`: `string` hex-encoded -- `transaction`: `string` hex-encoded +- `transaction`: `string` hex-encoded raw transaction ### Method `stx_transferFt` -`todo: haven't existed yet, should we add them?` +`params` + +- `recipient`: `string` address, Stacks c32-encoded +- `asset`: `string` address, Stacks c32-encoded, with contract name suffix +- `amount`: `number | string` BigInt constructor compatible value + +`result` + +- `txid`: `string` hex-encoded +- `transaction`: `string` hex-encoded raw transaction ### Method `stx_transferNft` -`todo: haven't existed yet, should we add them?` +`params` + +- `recipient`: `string` address, Stacks c32-encoded +- `asset`: `string` address, Stacks c32-encoded, with contract name suffix +- `assetId`: `ClarityValue` + +`where` + +- `ClarityValue`: `string | object` hex-encoded or JSON representation + +`result` + +- `txid`: `string` hex-encoded +- `transaction`: `string` hex-encoded raw transaction ### Method `stx_callContract` `params` - `contract`: `string.string` address with contract name suffix, Stacks c32-encoded -- `function`: `string` -- `arguments`: `ClarityValue[]`, defaults to `[]` +- `functionName`: `string` +- `functionArgs`: `ClarityValue[]`, defaults to `[]` `where` -- `ClarityValue`: `string` hex-encoded +- `ClarityValue`: `string | object` hex-encoded or JSON representation `result` - `txid`: `string` hex-encoded -- `transaction`: `string` hex-encoded +- `transaction`: `string` hex-encoded raw transaction ### Method `stx_deployContract` @@ -158,17 +182,17 @@ The following definitions can be used in multiple methods (mainly for transfer a `result` - `txid`: `string` hex-encoded -- `transaction`: `string` hex-encoded +- `transaction`: `string` hex-encoded raw transaction ### Method `stx_signTransaction` `params` -- `transaction`: `string` hex-encoded +- `transaction`: `string` hex-encoded raw transaction `result` -- `transaction`: `string` hex-encoded (signed) +- `transaction`: `string` hex-encoded raw transaction (signed) ### Method `stx_signMessage` @@ -203,6 +227,9 @@ The following definitions can be used in multiple methods (mainly for transfer a ### Method `stx_getAccounts` +> **Comment**: This method is similar to `stx_getAddresses`. +> It was added to provide better backwards compatibility for applications using Gaia. + `result` - `addresses`: `{}[]` @@ -221,7 +248,7 @@ The following definitions can be used in multiple methods (mainly for transfer a - `profile`: `object` updated Schema.org Person object -## JS Representations +## JSON Representations While discussing this SIP, it has become clear that the current Stacks.js representation is confusing to developers. Rather, a better solution would be human-readable — for example, rely on string literal enumeration, rather than magic values, which need additional lookups. @@ -231,13 +258,13 @@ Relying on soley a hex-encoded also poses difficulties when building Stacks enab Proposed below is an updated interface representation for Clarity primitives for use in Stacks.js and JSON compatible environments. -> For encoding larger than JS `Number` big integers, `string` is used. +> **Comment**: For encoding larger than JS `Number` big integers, `string` is used. `0x00` `int` ```ts { - type: "int", + type: 'int', value: string // `bigint` compatible } ``` @@ -246,7 +273,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "uint", + type: 'uint', value: string // `bigint` compatible } ``` @@ -255,7 +282,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "buffer", + type: 'buffer', value: string // hex-encoded string } ``` @@ -264,7 +291,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "true", + type: 'true', } ``` @@ -272,7 +299,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "false", + type: 'false', } ``` @@ -280,7 +307,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "address", + type: 'address', value: string // Stacks c32-encoded } ``` @@ -289,7 +316,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "contract", + type: 'contract', value: `${string}.${string}` // Stacks c32-encoded, with contract name suffix } ``` @@ -298,7 +325,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "ok", + type: 'ok', value: object // Clarity value } ``` @@ -307,7 +334,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "err", + type: 'err', value: object // Clarity value } ``` @@ -316,7 +343,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "none", + type: 'none', } ``` @@ -324,7 +351,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "some", + type: 'some', value: object // Clarity value } ``` @@ -333,7 +360,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "list", + type: 'list', value: object[] // Array of Clarity values } ``` @@ -342,7 +369,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "tuple", + type: 'tuple', value: Record // Record of Clarity values } ``` @@ -351,7 +378,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "ascii", + type: 'ascii', value: string // ASCII-compatible string } ``` @@ -360,12 +387,12 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: "utf8", + type: 'utf8', value: string } ``` -### Post conditions +### Post-conditions `0x00` STX @@ -406,43 +433,43 @@ Proposed below is an updated interface representation for Clarity primitives for Listed below are some examples of the potentially unclear representations: -- `u12` = `{ type: 'uint', value: "12" }` -- `0xbeaf` = `{ type: 'ascii', value: "hello there" }` -- `"hello there"` = `{ type: 'ascii', value: "hello there" }` +- `u12` = `{ type: "uint", value: "12" }` +- `0xbeaf` = `{ type: "ascii", value: "hello there" }` +- `"hello there"` = `{ type: "ascii", value: "hello there" }` - `(list 4 8)` = ``` { - type: 'list', + type: "list", value: [ - { type: 'int', value: "4"}, - { type: 'int', value: "8"}, + { type: "int", value: "4"}, + { type: "int", value: "8"}, ] } ``` - `(err u4)` = ``` { - type: 'err', - value: { type: 'uint', value: "4"}, + type: "err", + value: { type: "uint", value: "4"}, } ``` - "sends more than 10000 uSTX" = ``` { - type: 'stx', - address: 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6', - amount: '10000', - condition: 'gt' + type: "stx", + address: "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6", + amount: "10000", + condition: "gt" } ``` - "does not send the `12` TKN non-fungible token" = ``` { - type: 'ntf', - address: 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.vault' - asset: 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.tokencoin::tkn', - assetId: { type: 'uint', value: '12' } - condition: 'not-sent' + type: "ntf", + address: "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.vault" + asset: "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.tokencoin::tkn", + assetId: { type: "uint", value: "12" } + condition: "not-sent" } ``` From 2e74745b1e1acbfb84cdee6e10dc24f9ed05576e Mon Sep 17 00:00:00 2001 From: janniks Date: Tue, 5 Mar 2024 13:16:33 +0100 Subject: [PATCH 10/46] docs: update open questions --- sips/sip-02X/sip-02X-wallet-interface.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 8c58ad31..bb496b80 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -19,7 +19,8 @@ License: BSD 2-Clause - [ ] Should post-condition `type` be called `condition` or something (future overlap with clarity value?) or something else. Suffix `-condition`? -- [ ] Should we add `stx_transferFt` and `stx_transferNft`? +- [ ] Should clarit value representations use `.value` everywhere, or different properties (e.g. `.list`, `.buffer`)? +- [x] Should we add `stx_transferFt` and `stx_transferNft`? - [x] Change sender to `address`~~/`account`, or stay `sender for added clarity VS recipient/etc.?~~ - [x] Should Clarity values and maybe other types be hex-encoded, or is there a better idea that has similar benefits (no dependencies, but is easier to work with)? - For Clarity values, we could use strings (e.g. `u123`, `"text"`, `0x4be9`, `{ key: u3 }`) and parse the Clarity expression in the wallet. The only downside (I can think of) -- apart from additional wallet dev cost -- is cases like strings which need quotes, but this might not be clear to the user. A function/library for this would be provided by Stacks.js. From 1468025f063be02a913b4564023b51477015003d Mon Sep 17 00:00:00 2001 From: janniks <6362150+janniks@users.noreply.github.com> Date: Fri, 15 Mar 2024 10:07:35 +0100 Subject: [PATCH 11/46] fix: typo Co-authored-by: Marvin --- sips/sip-02X/sip-02X-wallet-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index bb496b80..7bc109f2 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -67,7 +67,7 @@ The Connect library should be go live with the new standard, once most major wal The WebBTC request standard is inspired by JSON-RPC 2.0 for serialization. To adhere to a generic serializability, the following notes are given. -Enums are serialized as humand-readable strings. +Enums are serialized as human-readable strings. BigInts are serialized as numbers, strings, or anything that can be parsed by the JavaScript BigInt constructor. Bytes are serialized as hex-encoded strings (without a 0x prefix). Predefined formats from previous SIPs are used where applicable. From fe54791a55fb0d6c1bdefdc2b54e62f82d81c2ad Mon Sep 17 00:00:00 2001 From: janniks <6362150+janniks@users.noreply.github.com> Date: Fri, 15 Mar 2024 10:07:59 +0100 Subject: [PATCH 12/46] fix: typo Co-authored-by: Marvin --- sips/sip-02X/sip-02X-wallet-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 7bc109f2..f952db89 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -59,7 +59,7 @@ Adopt the WebBTC request standard as the default interface between web-applicati The implementation of this proposal is not necessarily backward compatible. However, wallets implementing the new standard are advised to maintain the previous system to support legacy applications during a transition period. Existing applications using the current Auth system should continue to operate, but immediate changes are recommended once this SIP is ratified. -The Connect library should be go live with the new standard, once most major wallets have adopted the new standard. +The Connect library should go live with the new standard, once most major wallets have adopted the new standard. # Implementation From 560cffd94519696883970ebfb0e25e2506a2b54c Mon Sep 17 00:00:00 2001 From: janniks Date: Tue, 26 Mar 2024 22:38:33 +0100 Subject: [PATCH 13/46] docs: update sip --- sips/sip-02X/sip-02X-wallet-interface.md | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index f952db89..64864345 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -2,7 +2,7 @@ SIP Number: `To be assigned` -Title: Integration of WebBTC Request Standard for Stacks Wallets +Title: Integration of a Modern Stacks Wallet Interface Standard Authors: [janniks](https://github.com/janniks), `todo` @@ -20,15 +20,12 @@ License: BSD 2-Clause - [ ] Should post-condition `type` be called `condition` or something (future overlap with clarity value?) or something else. Suffix `-condition`? - [ ] Should clarit value representations use `.value` everywhere, or different properties (e.g. `.list`, `.buffer`)? -- [x] Should we add `stx_transferFt` and `stx_transferNft`? -- [x] Change sender to `address`~~/`account`, or stay `sender for added clarity VS recipient/etc.?~~ -- [x] Should Clarity values and maybe other types be hex-encoded, or is there a better idea that has similar benefits (no dependencies, but is easier to work with)? - - For Clarity values, we could use strings (e.g. `u123`, `"text"`, `0x4be9`, `{ key: u3 }`) and parse the Clarity expression in the wallet. The only downside (I can think of) -- apart from additional wallet dev cost -- is cases like strings which need quotes, but this might not be clear to the user. A function/library for this would be provided by Stacks.js. # Abstract -This SIP proposes the integration of the WebBTC request standard into the Stacks blockchain's Connect system. +This SIP proposes the integration of the standard into the Stacks blockchain's Connect and "auth" system. The goal is to replace the current Connect interface, primarily used by web applications to connect with browser extensions and mobile apps, with a more straightforward protocol. +The proposal consists mainly of standardizing JSON compatible interfaces for use with wallet interfaces. # Motivation @@ -36,13 +33,13 @@ The current Connect system, which has evolved since the Blockstack era, is prima However, many aspects of the existing "Connect" and "Auth" libraries are no longer required, leading to unnecessary complexity and brittleness in wallet connectivity. Recent attempts to standardize the interface have sparked valuable discussions but have not culminated in a ratified standard, largely due to the stable state of the existing system. -This SIP aims to address these issues by adopting the WebBTC request standard, which offers a more suitable RPC-style interface for modern web applications. +This SIP aims to address these issues by adopting the WBIPs standards, which offer a more suitable RPC-style interface for modern web applications. The simplified protocol will allow integration without heavy dependencies (like Auth) and provider a more extendable interface for wallets. Additionally, this SIP is motivated by the increased traffic of Ordinal inscriptions on Bitcoin and the Stacks ecosystem growing closers to Bitcoin. The community has recognized the need for a more unified approach to wallet connectivity. Recently, diverging viewpoints and disagreements on methodologies have hindered progress. -By adopting the WebBTC request standard, we aim to align the community towards a common and modern protocol for wallet interaction in web applications. +By adopting the new standard, we aim to align the community towards a common and modern protocol for wallet interaction in web applications. Importantly, the decision to use an existing standard (rather than designing a new one or reworking Auth) is intentional — to avoid further division or split ownership within the community. # Specification @@ -50,9 +47,7 @@ Importantly, the decision to use an existing standard (rather than designing a n The proposed changes are listed as follows: Specify JSON-RPC 2.0 compatible methods and payloads for wallet interaction. -These can be used via the WebBTC request standard (i.e., via the `window.webbtc.request` method) or similar interfaces like WalletConnect. - -Adopt the WebBTC request standard as the default interface between web-application and wallets — replacing components of the current Auth system in Connect. +These can be used via a browser object (i.e., via the `window.btc.request` method) or similar interfaces like WalletConnect. # Backwards Compatibility @@ -65,7 +60,7 @@ The Connect library should go live with the new standard, once most major wallet ## Notes on Serialization -The WebBTC request standard is inspired by JSON-RPC 2.0 for serialization. +These methods are based on JSON-RPC 2.0 for serialization. To adhere to a generic serializability, the following notes are given. Enums are serialized as human-readable strings. BigInts are serialized as numbers, strings, or anything that can be parsed by the JavaScript BigInt constructor. @@ -81,7 +76,7 @@ Parameters should be considered recommendations for the wallet. The user/wallet may choose to ignore/override them. Optional params are marked with a `?`. -Methods can be namespaced under `stx_` if used in settings like WebBTC (see WBIP-002) and other more Ethereum inspired domains. +Methods can be namespaced under `stx_` if used in more generic settings (see WBIP-002) and other more Ethereum inspired domains. In other cases (e.g. WalletConnect), the namespace may already be given by meta-data (e.g. a `chainId` field) and can be omitted. On the predominant `StacksProvider` global object, the methods can be used without a namespace, but wallets may add namespaced aliases for convenience. @@ -495,6 +490,6 @@ Discussions References - [WebBTC Request Standard](https://balls.dev/webbtc/extendability/extending/) -- [WBIPs](https://webbtc.netlify.app/wbips) +- [WBIPs](https://wbips.netlify.app/wbips) - [Xverse WalletConnect JSON API](https://docs.xverse.app/wallet-connect/reference/api_reference) - [Schema.org Person](https://schema.org/Person) From 22bfbcc8af3e371437a8291a82c9f5be1714437d Mon Sep 17 00:00:00 2001 From: janniks Date: Tue, 26 Mar 2024 22:41:41 +0100 Subject: [PATCH 14/46] docs: update sip --- sips/sip-02X/sip-02X-wallet-interface.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 64864345..1d54d946 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -18,8 +18,7 @@ License: BSD 2-Clause -- [ ] Should post-condition `type` be called `condition` or something (future overlap with clarity value?) or something else. Suffix `-condition`? -- [ ] Should clarit value representations use `.value` everywhere, or different properties (e.g. `.list`, `.buffer`)? +- [ ] Should a global single `window.` object be used, or should provider discovery be handled complely differently? # Abstract @@ -394,7 +393,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: 'stx', + type: 'stx-postcondition', address: string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix condition: 'eq' | 'gt' | 'gte' | 'lt' | 'lte', amount: string // `bigint` compatible, amount in mirco-STX @@ -405,7 +404,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: 'ft', + type: 'ft-postcondition', address: string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix condition: 'eq' | 'gt' | 'gte' | 'lt' | 'lte', asset: `${string}.${string}::${string}` // Stacks c32-encoded address, with contract name suffix, with asset suffix @@ -417,7 +416,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { - type: 'nft', + type: 'nft-postcondition', address: string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix condition: 'sent' | 'not-sent', asset: `${string}.${string}::${string}` // address with contract name suffix with asset suffix, Stacks c32-encoded @@ -452,7 +451,7 @@ Listed below are some examples of the potentially unclear representations: - "sends more than 10000 uSTX" = ``` { - type: "stx", + type: "stx-postcondition", address: "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6", amount: "10000", condition: "gt" @@ -461,7 +460,7 @@ Listed below are some examples of the potentially unclear representations: - "does not send the `12` TKN non-fungible token" = ``` { - type: "ntf", + type: "ntf-postcondition", address: "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.vault" asset: "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.tokencoin::tkn", assetId: { type: "uint", value: "12" } From 46bc2494c3a2dcf60d244ff6573c9fb950afa928 Mon Sep 17 00:00:00 2001 From: janniks Date: Tue, 26 Mar 2024 23:04:47 +0100 Subject: [PATCH 15/46] chore: add comment --- sips/sip-02X/sip-02X-wallet-interface.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 1d54d946..51d1557a 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -22,7 +22,7 @@ License: BSD 2-Clause # Abstract -This SIP proposes the integration of the standard into the Stacks blockchain's Connect and "auth" system. +This SIP proposes the integration of the standard into the Stacks blockchain's "Connect" and "Auth" system. The goal is to replace the current Connect interface, primarily used by web applications to connect with browser extensions and mobile apps, with a more straightforward protocol. The proposal consists mainly of standardizing JSON compatible interfaces for use with wallet interfaces. @@ -41,6 +41,9 @@ Recently, diverging viewpoints and disagreements on methodologies have hindered By adopting the new standard, we aim to align the community towards a common and modern protocol for wallet interaction in web applications. Importantly, the decision to use an existing standard (rather than designing a new one or reworking Auth) is intentional — to avoid further division or split ownership within the community. +There was an attempt to re-use existing standards/protocols from other ecosystems via the WBIPs working group — but no consensus was found that was a perfect fit or had enough traction for the larger layer-2 ecosystem. +So this SIP aims to capture the important features for the Stacks ecosystem, with a focus on extensibility. + # Specification The proposed changes are listed as follows: @@ -243,6 +246,10 @@ The following definitions can be used in multiple methods (mainly for transfer a - `profile`: `object` updated Schema.org Person object +## Listeners + +In addition to the request interface + ## JSON Representations While discussing this SIP, it has become clear that the current Stacks.js representation is confusing to developers. From e90bd195ef608f330fcea543a93518ba59753786 Mon Sep 17 00:00:00 2001 From: janniks Date: Tue, 26 Mar 2024 23:08:37 +0100 Subject: [PATCH 16/46] chore: address pr comments --- sips/sip-02X/sip-02X-wallet-interface.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 51d1557a..e984ab7d 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -36,8 +36,7 @@ This SIP aims to address these issues by adopting the WBIPs standards, which off The simplified protocol will allow integration without heavy dependencies (like Auth) and provider a more extendable interface for wallets. Additionally, this SIP is motivated by the increased traffic of Ordinal inscriptions on Bitcoin and the Stacks ecosystem growing closers to Bitcoin. -The community has recognized the need for a more unified approach to wallet connectivity. -Recently, diverging viewpoints and disagreements on methodologies have hindered progress. +The community has recognized the need for a more unified approach to wallet connectivity (e.g. Bitcoin and PSBTs for previously Stacks-only wallets). By adopting the new standard, we aim to align the community towards a common and modern protocol for wallet interaction in web applications. Importantly, the decision to use an existing standard (rather than designing a new one or reworking Auth) is intentional — to avoid further division or split ownership within the community. @@ -78,7 +77,7 @@ Parameters should be considered recommendations for the wallet. The user/wallet may choose to ignore/override them. Optional params are marked with a `?`. -Methods can be namespaced under `stx_` if used in more generic settings (see WBIP-002) and other more Ethereum inspired domains. +Methods can be namespaced under `stx_` if used in more generic settings and other more Ethereum inspired domains. In other cases (e.g. WalletConnect), the namespace may already be given by meta-data (e.g. a `chainId` field) and can be omitted. On the predominant `StacksProvider` global object, the methods can be used without a namespace, but wallets may add namespaced aliases for convenience. From c15ed40ab253bcd9a03077a5b8324a4d07fa17af Mon Sep 17 00:00:00 2001 From: janniks Date: Tue, 26 Mar 2024 23:10:30 +0100 Subject: [PATCH 17/46] chore: update authors --- sips/sip-02X/sip-02X-wallet-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index e984ab7d..2509671d 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -4,7 +4,7 @@ SIP Number: `To be assigned` Title: Integration of a Modern Stacks Wallet Interface Standard -Authors: [janniks](https://github.com/janniks), `todo` +Authors: [janniks](https://github.com/janniks), [kyranjamie](https://github.com/kyranjamie), [aryzing](https://github.com/aryzing), [m-aboelenein](https://github.com/m-aboelenein) Type: Standard From 09f5503012db57e01a1fb62830ddd949a8994f35 Mon Sep 17 00:00:00 2001 From: janniks Date: Tue, 26 Mar 2024 23:38:46 +0100 Subject: [PATCH 18/46] chore: update --- sips/sip-02X/sip-02X-wallet-interface.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 2509671d..3ba46a12 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -19,6 +19,7 @@ License: BSD 2-Clause - [ ] Should a global single `window.` object be used, or should provider discovery be handled complely differently? +- [ ] Should listeners have params? (e.g. txid for tx mined event) # Abstract @@ -229,7 +230,7 @@ The following definitions can be used in multiple methods (mainly for transfer a `result` -- `addresses`: `{}[]` +- `accounts`: `{}[]` - `address`: `string` address, Stacks c32-encoded - `publicKey`: `string` hex-encoded - `gaiaHubUrl`: `string` URL @@ -247,7 +248,24 @@ The following definitions can be used in multiple methods (mainly for transfer a ## Listeners -In addition to the request interface +In addition to the request interface, event listeners may be provided via the `.listen` method. +Wallets may provide a `.unlisten` method to remove listeners. + +- `provider.listen(event: string, listener: (...args: any[]) => void): void` +- `provider.unlisten(event: string, listener: (...args: any[]) => void): void` + +### Event `accountsChanged` + +`listener: (accounts: {}[]) => void` + +> `accounts` as defined above in `stx_getAccounts`. +> The first account is considered the default account (and may be the only "active" account in a wallet). + +## Error Codes + +Errors thrown by request methods should match existing JSON-RPC 2.0 error codes. +This way, the user or an intermediary library can handle them in a standardized way. +Otherwise, no additional error codes are defined in this SIP. ## JSON Representations From f8f841a33e2271e1a278621a1b2c701c4e90155f Mon Sep 17 00:00:00 2001 From: janniks Date: Wed, 3 Apr 2024 18:13:21 +0700 Subject: [PATCH 19/46] chore: add wbip links --- sips/sip-02X/sip-02X-wallet-interface.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 3ba46a12..b4eb08a2 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -502,6 +502,14 @@ This SIP is considered ratified after at least two major wallets in the Stacks e # Links +WBIPs + +> Documents worked out in the working group with Leather, Xverse, and others. + +- [WBIP-001: Wallet API JSON RPC](https://wbips.netlify.app/wbips/WBIP001) +- [WBIP-002: Namespaces](https://wbips.netlify.app/wbips/WBIP002) +- [WBIP-002: Batching](https://wbips.netlify.app/wbips/WBIP007) + Discussions - [Wallet JSON RPC API, Request Accounts #2378](https://github.com/leather-wallet/extension/pull/2378) From 1b79cac63b5c9386c83de228783b604b0c289f40 Mon Sep 17 00:00:00 2001 From: janniks Date: Wed, 3 Apr 2024 20:24:20 +0700 Subject: [PATCH 20/46] chore: add open question --- sips/sip-02X/sip-02X-wallet-interface.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index b4eb08a2..5e4501dd 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -19,6 +19,7 @@ License: BSD 2-Clause - [ ] Should a global single `window.` object be used, or should provider discovery be handled complely differently? +- [ ] Rename `stx_transferFt` to include SIP010 somewhere? - [ ] Should listeners have params? (e.g. txid for tx mined event) # Abstract @@ -420,7 +421,7 @@ Proposed below is an updated interface representation for Clarity primitives for type: 'stx-postcondition', address: string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix condition: 'eq' | 'gt' | 'gte' | 'lt' | 'lte', - amount: string // `bigint` compatible, amount in mirco-STX + amount: string // `bigint` compatible, amount in micro-STX } ``` From 33701fb112b5004a8f641be4199c151706a1884c Mon Sep 17 00:00:00 2001 From: janniks Date: Wed, 24 Apr 2024 19:47:24 +0700 Subject: [PATCH 21/46] fix: pr comment changes --- sips/sip-02X/sip-02X-wallet-interface.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 5e4501dd..899d30de 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -83,9 +83,9 @@ Methods can be namespaced under `stx_` if used in more generic settings and othe In other cases (e.g. WalletConnect), the namespace may already be given by meta-data (e.g. a `chainId` field) and can be omitted. On the predominant `StacksProvider` global object, the methods can be used without a namespace, but wallets may add namespaced aliases for convenience. -#### Common definitions +#### Transaction method general params -The following definitions can be used in multiple methods (mainly for transfer and transaction methods). +The following definitions can be used in the transaction methods. `params` @@ -94,7 +94,6 @@ The following definitions can be used in multiple methods (mainly for transfer a - `fee?`: `number | string` BigInt constructor compatible value - `nonce?`: `number | string` BigInt constructor compatible value - `attachment?`: `string` hex-encoded -- `anchorMode?`: `'on-chain' | 'off-chain' | 'any'` - `postConditions?`: `PostCondition[]`, defaults to `[]` - `postConditionMode?`: `'allow' | 'deny'` - `sponsored?`: `boolean`, defaults to `false` @@ -123,7 +122,7 @@ The following definitions can be used in multiple methods (mainly for transfer a - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded raw transaction -### Method `stx_transferFt` +### Method `stx_transferSip10Ft` `params` @@ -136,7 +135,7 @@ The following definitions can be used in multiple methods (mainly for transfer a - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded raw transaction -### Method `stx_transferNft` +### Method `stx_transferSip10Nft` `params` @@ -250,12 +249,14 @@ The following definitions can be used in multiple methods (mainly for transfer a ## Listeners In addition to the request interface, event listeners may be provided via the `.listen` method. -Wallets may provide a `.unlisten` method to remove listeners. -- `provider.listen(event: string, listener: (...args: any[]) => void): void` -- `provider.unlisten(event: string, listener: (...args: any[]) => void): void` +- `provider.listen(event: string, listener: (...args: any[]) => void): Function` -### Event `accountsChanged` +> `provider.listen` should return a "unlisten" function, which can be called to remove the listener. + +The event name should be closer to nouns than verbs and doesn't use the `on` prefix from DOM naming conventions. + +### Event `accountChange` `listener: (accounts: {}[]) => void` @@ -505,7 +506,7 @@ This SIP is considered ratified after at least two major wallets in the Stacks e WBIPs -> Documents worked out in the working group with Leather, Xverse, and others. +> Documents partially worked on in the working group with Leather, Xverse, and others. - [WBIP-001: Wallet API JSON RPC](https://wbips.netlify.app/wbips/WBIP001) - [WBIP-002: Namespaces](https://wbips.netlify.app/wbips/WBIP002) From 78d21f47ed8ba6888a2dceb90145cdd6bc9f5390 Mon Sep 17 00:00:00 2001 From: janniks Date: Tue, 30 Jul 2024 13:28:54 +0200 Subject: [PATCH 22/46] fix: add origin post conditions --- sips/sip-02X/sip-02X-wallet-interface.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-02X/sip-02X-wallet-interface.md index 899d30de..61a4eb55 100644 --- a/sips/sip-02X/sip-02X-wallet-interface.md +++ b/sips/sip-02X/sip-02X-wallet-interface.md @@ -420,7 +420,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { type: 'stx-postcondition', - address: string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix + address: 'origin' | string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix condition: 'eq' | 'gt' | 'gte' | 'lt' | 'lte', amount: string // `bigint` compatible, amount in micro-STX } @@ -431,7 +431,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { type: 'ft-postcondition', - address: string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix + address: 'origin' | string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix condition: 'eq' | 'gt' | 'gte' | 'lt' | 'lte', asset: `${string}.${string}::${string}` // Stacks c32-encoded address, with contract name suffix, with asset suffix amount: string // `bigint` compatible, amount in lowest integer denomination of fungible token @@ -443,7 +443,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { type: 'nft-postcondition', - address: string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix + address: 'origin' | string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix condition: 'sent' | 'not-sent', asset: `${string}.${string}::${string}` // address with contract name suffix with asset suffix, Stacks c32-encoded assetId: object, // Clarity value From cb1045541ee74fa73fc19eae4b237c7f33830737 Mon Sep 17 00:00:00 2001 From: janniks Date: Wed, 23 Oct 2024 21:34:30 +0200 Subject: [PATCH 23/46] chore: rename to 30 --- .../sip-030-wallet-interface.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename sips/{sip-02X/sip-02X-wallet-interface.md => sip-030/sip-030-wallet-interface.md} (100%) diff --git a/sips/sip-02X/sip-02X-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md similarity index 100% rename from sips/sip-02X/sip-02X-wallet-interface.md rename to sips/sip-030/sip-030-wallet-interface.md From d5de1922d1b6689b9c9d04f70473deef861b3d0c Mon Sep 17 00:00:00 2001 From: janniks <6362150+janniks@users.noreply.github.com> Date: Tue, 5 Nov 2024 19:50:52 +0100 Subject: [PATCH 24/46] chore: update from pr review --- sips/sip-030/sip-030-wallet-interface.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 61a4eb55..3f14fbd2 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -4,7 +4,7 @@ SIP Number: `To be assigned` Title: Integration of a Modern Stacks Wallet Interface Standard -Authors: [janniks](https://github.com/janniks), [kyranjamie](https://github.com/kyranjamie), [aryzing](https://github.com/aryzing), [m-aboelenein](https://github.com/m-aboelenein) +Authors: [aryzing](https://github.com/aryzing), [janniks](https://github.com/janniks), [kyranjamie](https://github.com/kyranjamie), [m-aboelenein](https://github.com/m-aboelenein) Type: Standard @@ -24,9 +24,9 @@ License: BSD 2-Clause # Abstract -This SIP proposes the integration of the standard into the Stacks blockchain's "Connect" and "Auth" system. -The goal is to replace the current Connect interface, primarily used by web applications to connect with browser extensions and mobile apps, with a more straightforward protocol. -The proposal consists mainly of standardizing JSON compatible interfaces for use with wallet interfaces. +This SIP proposes common RPC methods to use for the Stacks blockchain's "Connect" and "Auth" systems. +The goal is to replace the current Connect interface, primarily used by web applications to connect with browser extensions and mobile apps with a more straightforward protocol. +This proposal's goal is to standardize JSON compatible interfaces for use with wallet interfaces. # Motivation From 537d9a17e06a193f313c3e81a340f8d613d012c6 Mon Sep 17 00:00:00 2001 From: janniks <6362150+janniks@users.noreply.github.com> Date: Tue, 5 Nov 2024 20:13:09 +0100 Subject: [PATCH 25/46] chore: add pr feedback --- sips/sip-030/sip-030-wallet-interface.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 3f14fbd2..1ce869c9 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -30,14 +30,14 @@ This proposal's goal is to standardize JSON compatible interfaces for use with w # Motivation -The current Connect system, which has evolved since the Blockstack era, is primarily utilized by web applications for interfacing with wallets. -However, many aspects of the existing "Connect" and "Auth" libraries are no longer required, leading to unnecessary complexity and brittleness in wallet connectivity. +The current Connect system, which has existed for several years, is primarily utilized by web applications for interfacing with wallets. +However, many aspects of the existing "Connect" and "Auth" libraries are no longer required, leading to unnecessary complexity (e.g., wrapping RPC payloads in jsontokens) and brittleness (e.g., undefined serialization for non-JSON compatible data structures) in wallet connectivity. -Recent attempts to standardize the interface have sparked valuable discussions but have not culminated in a ratified standard, largely due to the stable state of the existing system. +Recent attempts to standardize the interface (https://github.com/stacksgov/sips/pull/59, https://github.com/stacksgov/sips/issues/117) have sparked valuable discussions but have not culminated in a ratified standard, largely due to the stable state of the existing system. This SIP aims to address these issues by adopting the WBIPs standards, which offer a more suitable RPC-style interface for modern web applications. The simplified protocol will allow integration without heavy dependencies (like Auth) and provider a more extendable interface for wallets. -Additionally, this SIP is motivated by the increased traffic of Ordinal inscriptions on Bitcoin and the Stacks ecosystem growing closers to Bitcoin. +Additionally, this SIP is motivated by the increased traffic of Ordinal inscriptions on Bitcoin and the Stacks ecosystem growing closer to Bitcoin. The community has recognized the need for a more unified approach to wallet connectivity (e.g. Bitcoin and PSBTs for previously Stacks-only wallets). By adopting the new standard, we aim to align the community towards a common and modern protocol for wallet interaction in web applications. Importantly, the decision to use an existing standard (rather than designing a new one or reworking Auth) is intentional — to avoid further division or split ownership within the community. From b1e9b01f6b81fbd7085722bd1c8e4678ccf348f4 Mon Sep 17 00:00:00 2001 From: janniks <6362150+janniks@users.noreply.github.com> Date: Tue, 5 Nov 2024 21:55:48 +0100 Subject: [PATCH 26/46] chore: add pr feedback --- sips/sip-030/sip-030-wallet-interface.md | 31 ++++++++++++------------ 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 1ce869c9..2add161e 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -1,6 +1,6 @@ # Preamble -SIP Number: `To be assigned` +SIP Number: `030` Title: Integration of a Modern Stacks Wallet Interface Standard @@ -49,38 +49,37 @@ So this SIP aims to capture the important features for the Stacks ecosystem, wit The proposed changes are listed as follows: -Specify JSON-RPC 2.0 compatible methods and payloads for wallet interaction. +Specify [JSON-RPC 2.0](https://www.jsonrpc.org/specification) compatible methods and payloads for wallet interaction. These can be used via a browser object (i.e., via the `window.btc.request` method) or similar interfaces like WalletConnect. # Backwards Compatibility The implementation of this proposal is not necessarily backward compatible. -However, wallets implementing the new standard are advised to maintain the previous system to support legacy applications during a transition period. +Wallets implementing the new standard may maintain the previous system to support legacy applications during a transition period or indefinitely. Existing applications using the current Auth system should continue to operate, but immediate changes are recommended once this SIP is ratified. -The Connect library should go live with the new standard, once most major wallets have adopted the new standard. # Implementation ## Notes on Serialization -These methods are based on JSON-RPC 2.0 for serialization. -To adhere to a generic serializability, the following notes are given. -Enums are serialized as human-readable strings. -BigInts are serialized as numbers, strings, or anything that can be parsed by the JavaScript BigInt constructor. -Bytes are serialized as hex-encoded strings (without a 0x prefix). -Predefined formats from previous SIPs are used where applicable. -Addresses are serialized as Stacks c32-encoded strings. -Clarity values, post-conditions, and transactions are serialized to bytes (defined by SIP-005) and used as hex-encoded strings. +To adhere to a generic serializability, the following notes are given: + +- Enums are serialized as human-readable strings. +- BigInts are serialized as numbers, strings, or anything that can be parsed by the JavaScript BigInt constructor. +- Bytes are serialized as hex-encoded strings (without a 0x prefix). +- Predefined formats from previous SIPs are used where applicable. +- Addresses are serialized as Stacks c32-encoded strings. +- Clarity values, post-conditions, and transactions are serialized to bytes (defined by SIP-005) and used as hex-encoded strings. ## Methods This section defines the available methods, their parameters, and result structure. -Parameters should be considered recommendations for the wallet. -The user/wallet may choose to ignore/override them. -Optional params are marked with a `?`. +Parameters should be considered only as recommendations for the wallet, and the user/wallet may choose to ignore or override them. + +> Note: Optional params are marked with a `?`. Methods can be namespaced under `stx_` if used in more generic settings and other more Ethereum inspired domains. -In other cases (e.g. WalletConnect), the namespace may already be given by meta-data (e.g. a `chainId` field) and can be omitted. +In other cases (e.g. `WalletConnect`), the namespace may already be given by metadata (e.g. a `chainId` field) and can be omitted. On the predominant `StacksProvider` global object, the methods can be used without a namespace, but wallets may add namespaced aliases for convenience. #### Transaction method general params From c02be3fd00ac66fa22d25a59315ae0d61e87190f Mon Sep 17 00:00:00 2001 From: janniks <6362150+janniks@users.noreply.github.com> Date: Thu, 21 Nov 2024 00:12:51 +0100 Subject: [PATCH 27/46] chore: update sip Co-authored-by: kyranjamie --- sips/sip-030/sip-030-wallet-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 2add161e..e3266398 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -62,7 +62,7 @@ Existing applications using the current Auth system should continue to operate, ## Notes on Serialization -To adhere to a generic serializability, the following notes are given: +To ensure serializability, consider these notes: - Enums are serialized as human-readable strings. - BigInts are serialized as numbers, strings, or anything that can be parsed by the JavaScript BigInt constructor. From cd86682e1774ac7c3cb6697b26a126641115286f Mon Sep 17 00:00:00 2001 From: janniks <6362150+janniks@users.noreply.github.com> Date: Thu, 21 Nov 2024 00:13:19 +0100 Subject: [PATCH 28/46] chore: update sip Co-authored-by: kyranjamie --- sips/sip-030/sip-030-wallet-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index e3266398..37e501b1 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -50,7 +50,7 @@ So this SIP aims to capture the important features for the Stacks ecosystem, wit The proposed changes are listed as follows: Specify [JSON-RPC 2.0](https://www.jsonrpc.org/specification) compatible methods and payloads for wallet interaction. -These can be used via a browser object (i.e., via the `window.btc.request` method) or similar interfaces like WalletConnect. +These can be used via a browser object (i.e., via the `window.WalletProvider.request` method) or similar interfaces like WalletConnect. # Backwards Compatibility From 8f1c99d0103aea50e0c6531f108aef5160edbe8d Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 21 Nov 2024 13:21:33 +0100 Subject: [PATCH 29/46] chore: pr feedback --- sips/sip-030/sip-030-wallet-interface.md | 150 +++++++++++------------ 1 file changed, 72 insertions(+), 78 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 37e501b1..ef8ca976 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -1,10 +1,10 @@ -# Preamble +## Preamble SIP Number: `030` Title: Integration of a Modern Stacks Wallet Interface Standard -Authors: [aryzing](https://github.com/aryzing), [janniks](https://github.com/janniks), [kyranjamie](https://github.com/kyranjamie), [m-aboelenein](https://github.com/m-aboelenein) +Authors: [aryzing](https://github.com/aryzing), [janniks](https://github.com/janniks), [kyranjamie](https://github.com/kyranjamie), [m-aboelenein](https://github.com/m-aboelenein) Type: Standard @@ -14,24 +14,23 @@ Created: 10 October 2023 License: BSD 2-Clause -# OPEN QUESTIONS +## OPEN QUESTIONS - [ ] Should a global single `window.` object be used, or should provider discovery be handled complely differently? -- [ ] Rename `stx_transferFt` to include SIP010 somewhere? - [ ] Should listeners have params? (e.g. txid for tx mined event) -# Abstract +## Abstract This SIP proposes common RPC methods to use for the Stacks blockchain's "Connect" and "Auth" systems. The goal is to replace the current Connect interface, primarily used by web applications to connect with browser extensions and mobile apps with a more straightforward protocol. This proposal's goal is to standardize JSON compatible interfaces for use with wallet interfaces. -# Motivation +## Motivation The current Connect system, which has existed for several years, is primarily utilized by web applications for interfacing with wallets. -However, many aspects of the existing "Connect" and "Auth" libraries are no longer required, leading to unnecessary complexity (e.g., wrapping RPC payloads in jsontokens) and brittleness (e.g., undefined serialization for non-JSON compatible data structures) in wallet connectivity. +However, many aspects of the existing "Connect" and "Auth" libraries are no longer required, leading to unnecessary complexity (e.g., wrapping RPC payloads in jsontokens) and lack of clear definitions (e.g., undefined serialization for non-JSON compatible data structures) in wallet connectivity. Recent attempts to standardize the interface (https://github.com/stacksgov/sips/pull/59, https://github.com/stacksgov/sips/issues/117) have sparked valuable discussions but have not culminated in a ratified standard, largely due to the stable state of the existing system. This SIP aims to address these issues by adopting the WBIPs standards, which offer a more suitable RPC-style interface for modern web applications. @@ -45,22 +44,22 @@ Importantly, the decision to use an existing standard (rather than designing a n There was an attempt to re-use existing standards/protocols from other ecosystems via the WBIPs working group — but no consensus was found that was a perfect fit or had enough traction for the larger layer-2 ecosystem. So this SIP aims to capture the important features for the Stacks ecosystem, with a focus on extensibility. -# Specification +## Specification The proposed changes are listed as follows: Specify [JSON-RPC 2.0](https://www.jsonrpc.org/specification) compatible methods and payloads for wallet interaction. These can be used via a browser object (i.e., via the `window.WalletProvider.request` method) or similar interfaces like WalletConnect. -# Backwards Compatibility +## Backwards Compatibility The implementation of this proposal is not necessarily backward compatible. Wallets implementing the new standard may maintain the previous system to support legacy applications during a transition period or indefinitely. Existing applications using the current Auth system should continue to operate, but immediate changes are recommended once this SIP is ratified. -# Implementation +## Implementation -## Notes on Serialization +### Notes on Serialization To ensure serializability, consider these notes: @@ -71,7 +70,7 @@ To ensure serializability, consider these notes: - Addresses are serialized as Stacks c32-encoded strings. - Clarity values, post-conditions, and transactions are serialized to bytes (defined by SIP-005) and used as hex-encoded strings. -## Methods +### Methods This section defines the available methods, their parameters, and result structure. Parameters should be considered only as recommendations for the wallet, and the user/wallet may choose to ignore or override them. @@ -82,61 +81,58 @@ Methods can be namespaced under `stx_` if used in more generic settings and othe In other cases (e.g. `WalletConnect`), the namespace may already be given by metadata (e.g. a `chainId` field) and can be omitted. On the predominant `StacksProvider` global object, the methods can be used without a namespace, but wallets may add namespaced aliases for convenience. -#### Transaction method general params +##### Transaction method general params The following definitions can be used in the transaction methods. -`params` +Parameter properties - `address?`: `string` address, Stacks c32-encoded, defaults to wallets current address - `network?`: `'mainnet' | 'testnet' | 'regtest' | 'mocknet'` - `fee?`: `number | string` BigInt constructor compatible value - `nonce?`: `number | string` BigInt constructor compatible value -- `attachment?`: `string` hex-encoded - `postConditions?`: `PostCondition[]`, defaults to `[]` + - where `PostCondition` is `string | object` hex-encoded or JSON representation - `postConditionMode?`: `'allow' | 'deny'` - `sponsored?`: `boolean`, defaults to `false` +- ~~`attachment?`~~ _removed_ - ~~`appDetails`~~ _removed_ - ~~`onFinish`~~ _removed_ - ~~`onCancel`~~ _removed_ -`where` - -- `PostCondition`: `string | object` hex-encoded or JSON representation - --- -### Method `stx_transferStx` +#### Method `stx_transferStx` > **Comment**: This method doesn't take post-conditions. -`params` +Parameter properties - `recipient`: `string` address, Stacks c32-encoded - `amount`: `number | string` BigInt constructor compatible value - `memo?`: `string`, defaults to `''` -`result` +Result properties - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded raw transaction -### Method `stx_transferSip10Ft` +#### Method `stx_transferSip10Ft` -`params` +Parameter properties - `recipient`: `string` address, Stacks c32-encoded - `asset`: `string` address, Stacks c32-encoded, with contract name suffix - `amount`: `number | string` BigInt constructor compatible value -`result` +Result properties - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded raw transaction -### Method `stx_transferSip10Nft` +#### Method `stx_transferSip10Nft` -`params` +Parameter properties - `recipient`: `string` address, Stacks c32-encoded - `asset`: `string` address, Stacks c32-encoded, with contract name suffix @@ -146,88 +142,85 @@ The following definitions can be used in the transaction methods. - `ClarityValue`: `string | object` hex-encoded or JSON representation -`result` +Result properties - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded raw transaction -### Method `stx_callContract` +#### Method `stx_callContract` -`params` +Parameter properties - `contract`: `string.string` address with contract name suffix, Stacks c32-encoded - `functionName`: `string` - `functionArgs`: `ClarityValue[]`, defaults to `[]` + - where `ClarityValue` is `string | object` hex-encoded or JSON representation -`where` - -- `ClarityValue`: `string | object` hex-encoded or JSON representation - -`result` +Result properties - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded raw transaction -### Method `stx_deployContract` +#### Method `stx_deployContract` -`params` +Parameter properties - `name`: `string` - `clarityCode`: `string` Clarity contract code - `clarityVersion?`: `number` -`result` +Result properties - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded raw transaction -### Method `stx_signTransaction` +#### Method `stx_signTransaction` -`params` +Parameter properties - `transaction`: `string` hex-encoded raw transaction -`result` +Result properties - `transaction`: `string` hex-encoded raw transaction (signed) -### Method `stx_signMessage` +#### Method `stx_signMessage` -`params` +Parameter properties - `message`: `string` -`result` +Result properties - `signature`: `string` hex-encoded - `publicKey`: `string` hex-encoded -### Method `stx_signStructuredMessage` +#### Method `stx_signStructuredMessage` -`params` +Parameter properties - `message`: `string` Clarity value, hex-encoded - `domain`: `string` hex-encoded (defined by SIP-018) -`result` +Result properties - `signature`: `string` hex-encoded - `publicKey`: `string` hex-encoded -### Method `stx_getAddresses` +#### Method `stx_getAddresses` -`result` +Result properties - `addresses`: `{}[]` - `address`: `string` address, Stacks c32-encoded - `publicKey`: `string` hex-encoded -### Method `stx_getAccounts` +#### Method `stx_getAccounts` > **Comment**: This method is similar to `stx_getAddresses`. > It was added to provide better backwards compatibility for applications using Gaia. -`result` +Result properties - `accounts`: `{}[]` - `address`: `string` address, Stacks c32-encoded @@ -235,17 +228,17 @@ The following definitions can be used in the transaction methods. - `gaiaHubUrl`: `string` URL - `gaiaAppKey`: `string` hex-encoded -### Method `stx_updateProfile` +#### Method `stx_updateProfile` -`params` +Parameter properties -- `profile`: `object` Schema.org Person object +- `profile`: `object` Schema.org Person object[^13] -`result` +Result properties -- `profile`: `object` updated Schema.org Person object +- `profile`: `object` updated Schema.org Person object[^12] -## Listeners +### Listeners In addition to the request interface, event listeners may be provided via the `.listen` method. @@ -255,26 +248,26 @@ In addition to the request interface, event listeners may be provided via the `. The event name should be closer to nouns than verbs and doesn't use the `on` prefix from DOM naming conventions. -### Event `accountChange` +#### Event `accountChange` `listener: (accounts: {}[]) => void` > `accounts` as defined above in `stx_getAccounts`. > The first account is considered the default account (and may be the only "active" account in a wallet). -## Error Codes +### Error Codes Errors thrown by request methods should match existing JSON-RPC 2.0 error codes. This way, the user or an intermediary library can handle them in a standardized way. Otherwise, no additional error codes are defined in this SIP. -## JSON Representations +### JSON Representations While discussing this SIP, it has become clear that the current Stacks.js representation is confusing to developers. Rather, a better solution would be human-readable — for example, rely on string literal enumeration, rather than magic values, which need additional lookups. Relying on soley a hex-encoded also poses difficulties when building Stacks enabled web applications. -### Clarity values +#### Clarity values Proposed below is an updated interface representation for Clarity primitives for use in Stacks.js and JSON compatible environments. @@ -412,7 +405,7 @@ Proposed below is an updated interface representation for Clarity primitives for } ``` -### Post-conditions +#### Post-conditions `0x00` STX @@ -449,7 +442,7 @@ Proposed below is an updated interface representation for Clarity primitives for } ``` -### Test vectors +#### Test vectors Listed below are some examples of the potentially unclear representations: @@ -493,35 +486,36 @@ Listed below are some examples of the potentially unclear representations: } ``` -## Provider registration +### Provider registration Wallets can register their aliased provider objects according to WBIP-004. -# Ratification +## Ratification This SIP is considered ratified after at least two major wallets in the Stacks ecosystem have implemented and launched the new standard. -# Links +## Appendix WBIPs > Documents partially worked on in the working group with Leather, Xverse, and others. -- [WBIP-001: Wallet API JSON RPC](https://wbips.netlify.app/wbips/WBIP001) -- [WBIP-002: Namespaces](https://wbips.netlify.app/wbips/WBIP002) -- [WBIP-002: Batching](https://wbips.netlify.app/wbips/WBIP007) +[^1]: [WBIP-001: Wallet API JSON RPC](https://wbips.netlify.app/wbips/WBIP001) +[^2]: [WBIP-002: Namespaces](https://wbips.netlify.app/wbips/WBIP002) +[^3]: [WBIP-004: Registration](https://wbips.netlify.app/wbips/WBIP004) +[^4]: [WBIP-007: Batching](https://wbips.netlify.app/wbips/WBIP007) Discussions -- [Wallet JSON RPC API, Request Accounts #2378](https://github.com/leather-wallet/extension/pull/2378) -- [Sign-in with stacks #70](https://github.com/stacksgov/sips/pull/70) -- [Add API to request addresses #2371](https://github.com/leather-wallet/extension/issues/2371) -- [SIP for Wallet Protocol #59](https://github.com/stacksgov/sips/pull/59) -- [SIP for Authentication Protocol #50](https://github.com/stacksgov/sips/pull/50) +[^5]: [Wallet JSON RPC API, Request Accounts #2378](https://github.com/leather-wallet/extension/pull/2378) +[^6]: [Sign-in with stacks #70](https://github.com/stacksgov/sips/pull/70) +[^7]: [Add API to request addresses #2371](https://github.com/leather-wallet/extension/issues/2371) +[^8]: [SIP for Wallet Protocol #59](https://github.com/stacksgov/sips/pull/59) +[^9]: [SIP for Authentication Protocol #50](https://github.com/stacksgov/sips/pull/50) References -- [WebBTC Request Standard](https://balls.dev/webbtc/extendability/extending/) -- [WBIPs](https://wbips.netlify.app/wbips) -- [Xverse WalletConnect JSON API](https://docs.xverse.app/wallet-connect/reference/api_reference) -- [Schema.org Person](https://schema.org/Person) +[^10]: [WebBTC Request Standard](https://balls.dev/webbtc/extendability/extending/) +[^11]: [WBIPs](https://wbips.netlify.app/wbips) +[^12]: [Xverse WalletConnect JSON API](https://docs.xverse.app/wallet-connect/reference/api_reference) +[^13]: [Schema.org Person](https://schema.org/Person) From ecb0e7cdaf1ec5df55fe318617b289b8748f761d Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 21 Nov 2024 13:37:52 +0100 Subject: [PATCH 30/46] chore: add more references --- sips/sip-030/sip-030-wallet-interface.md | 25 +++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index ef8ca976..e1daef5e 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -32,8 +32,8 @@ This proposal's goal is to standardize JSON compatible interfaces for use with w The current Connect system, which has existed for several years, is primarily utilized by web applications for interfacing with wallets. However, many aspects of the existing "Connect" and "Auth" libraries are no longer required, leading to unnecessary complexity (e.g., wrapping RPC payloads in jsontokens) and lack of clear definitions (e.g., undefined serialization for non-JSON compatible data structures) in wallet connectivity. -Recent attempts to standardize the interface (https://github.com/stacksgov/sips/pull/59, https://github.com/stacksgov/sips/issues/117) have sparked valuable discussions but have not culminated in a ratified standard, largely due to the stable state of the existing system. -This SIP aims to address these issues by adopting the WBIPs standards, which offer a more suitable RPC-style interface for modern web applications. +Recent attempts[^21][^22][^23][^24][^25][^26] to standardize the interface have sparked valuable discussions but have not culminated in a ratified standard, largely due to the stable state of the existing system. +This SIP aims to address these issues by adopting the WBIPs standards[^11], which offer a more suitable RPC-style interface for modern web applications. The simplified protocol will allow integration without heavy dependencies (like Auth) and provider a more extendable interface for wallets. Additionally, this SIP is motivated by the increased traffic of Ordinal inscriptions on Bitcoin and the Stacks ecosystem growing closer to Bitcoin. @@ -236,7 +236,7 @@ Parameter properties Result properties -- `profile`: `object` updated Schema.org Person object[^12] +- `profile`: `object` updated Schema.org Person object[^13] ### Listeners @@ -488,11 +488,12 @@ Listed below are some examples of the potentially unclear representations: ### Provider registration -Wallets can register their aliased provider objects according to WBIP-004. +Wallets can register their aliased provider objects according to WBIP-004[^3] or. ## Ratification -This SIP is considered ratified after at least two major wallets in the Stacks ecosystem have implemented and launched the new standard. +This SIP is considered ratified after Xverse and Leather (currently the largest wallets in the Stacks ecosystem) have implemented and launched the new standard. +Once wallets have implemented the new standard, tooling (e.g. Stacks Connect) can be updated to support the new standard as well. ## Appendix @@ -507,15 +508,17 @@ WBIPs Discussions -[^5]: [Wallet JSON RPC API, Request Accounts #2378](https://github.com/leather-wallet/extension/pull/2378) -[^6]: [Sign-in with stacks #70](https://github.com/stacksgov/sips/pull/70) -[^7]: [Add API to request addresses #2371](https://github.com/leather-wallet/extension/issues/2371) -[^8]: [SIP for Wallet Protocol #59](https://github.com/stacksgov/sips/pull/59) -[^9]: [SIP for Authentication Protocol #50](https://github.com/stacksgov/sips/pull/50) +[^21]: [Wallet JSON RPC API, Request Accounts #2378](https://github.com/leather-wallet/extension/pull/2378) +[^22]: [Sign-in with stacks #70](https://github.com/stacksgov/sips/pull/70) +[^23]: [Add API to request addresses #2371](https://github.com/leather-wallet/extension/issues/2371) +[^24]: [SIP for Wallet Protocol #59](https://github.com/stacksgov/sips/pull/59) +[^25]: [SIP for Authentication Protocol #50](https://github.com/stacksgov/sips/pull/50) +[^26]: [Wallet client API](https://github.com/stacksgov/sips/issues/117) References [^10]: [WebBTC Request Standard](https://balls.dev/webbtc/extendability/extending/) -[^11]: [WBIPs](https://wbips.netlify.app/wbips) +[^11]: [WBIPs](https://wbips.netlify.app) [^12]: [Xverse WalletConnect JSON API](https://docs.xverse.app/wallet-connect/reference/api_reference) [^13]: [Schema.org Person](https://schema.org/Person) +[^14]: [Wallet Standard](https://github.com/wallet-standard/wallet-standard) From 6ed5cd7c59527ee5ae1922d844cc892bc5077b82 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 21 Nov 2024 13:38:59 +0100 Subject: [PATCH 31/46] chore: add wallet standard --- sips/sip-030/sip-030-wallet-interface.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index e1daef5e..cbea2e5c 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -488,7 +488,8 @@ Listed below are some examples of the potentially unclear representations: ### Provider registration -Wallets can register their aliased provider objects according to WBIP-004[^3] or. +Wallets can register their aliased provider objects however they see fit. +For example, using the WBIP-004[^3] standard or [Wallet Standard](https://github.com/wallet-standard/wallet-standard)[^14]. ## Ratification From fb6ce0971a44e9190b2c926fd1d190f7dc9b2b79 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 21 Nov 2024 13:50:49 +0100 Subject: [PATCH 32/46] chore: pr feedback --- sips/sip-030/sip-030-wallet-interface.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index cbea2e5c..428760c9 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -41,7 +41,7 @@ The community has recognized the need for a more unified approach to wallet conn By adopting the new standard, we aim to align the community towards a common and modern protocol for wallet interaction in web applications. Importantly, the decision to use an existing standard (rather than designing a new one or reworking Auth) is intentional — to avoid further division or split ownership within the community. -There was an attempt to re-use existing standards/protocols from other ecosystems via the WBIPs working group — but no consensus was found that was a perfect fit or had enough traction for the larger layer-2 ecosystem. +There was an attempt to re-use existing standards/protocols from other ecosystems via the WBIPs working group[^11][^26] — but no consensus was found that was a perfect fit or had enough traction for the larger layer-2 ecosystem. So this SIP aims to capture the important features for the Stacks ecosystem, with a focus on extensibility. ## Specification @@ -263,8 +263,9 @@ Otherwise, no additional error codes are defined in this SIP. ### JSON Representations -While discussing this SIP, it has become clear that the current Stacks.js representation is confusing to developers. -Rather, a better solution would be human-readable — for example, rely on string literal enumeration, rather than magic values, which need additional lookups. +For historical reasons, a Stacks.js internal representation, based on the Stacks core code, has been used in serialized payloads to wallets. +These representations are not human-readable and thus make debugging difficult. +A better solution would be to rely on string literal enumeration, rather than magic values, which need additional lookups. Relying on soley a hex-encoded also poses difficulties when building Stacks enabled web applications. #### Clarity values From 51c3eb7bb7e18b6c2e53cd629e2a146aa7e74de4 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 21 Nov 2024 14:01:43 +0100 Subject: [PATCH 33/46] chore: pr feedback --- sips/sip-030/sip-030-wallet-interface.md | 25 +++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 428760c9..9976ffc8 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -6,6 +6,8 @@ Title: Integration of a Modern Stacks Wallet Interface Standard Authors: [aryzing](https://github.com/aryzing), [janniks](https://github.com/janniks), [kyranjamie](https://github.com/kyranjamie), [m-aboelenein](https://github.com/m-aboelenein) +Consideration: Technical + Type: Standard Status: Draft @@ -14,13 +16,6 @@ Created: 10 October 2023 License: BSD 2-Clause -## OPEN QUESTIONS - - - -- [ ] Should a global single `window.` object be used, or should provider discovery be handled complely differently? -- [ ] Should listeners have params? (e.g. txid for tx mined event) - ## Abstract This SIP proposes common RPC methods to use for the Stacks blockchain's "Connect" and "Auth" systems. @@ -34,7 +29,7 @@ However, many aspects of the existing "Connect" and "Auth" libraries are no long Recent attempts[^21][^22][^23][^24][^25][^26] to standardize the interface have sparked valuable discussions but have not culminated in a ratified standard, largely due to the stable state of the existing system. This SIP aims to address these issues by adopting the WBIPs standards[^11], which offer a more suitable RPC-style interface for modern web applications. -The simplified protocol will allow integration without heavy dependencies (like Auth) and provider a more extendable interface for wallets. +The simplified protocol will allow integration without heavy dependencies (like Auth) and provide a more extendable interface for wallets. Additionally, this SIP is motivated by the increased traffic of Ordinal inscriptions on Bitcoin and the Stacks ecosystem growing closer to Bitcoin. The community has recognized the need for a more unified approach to wallet connectivity (e.g. Bitcoin and PSBTs for previously Stacks-only wallets). @@ -57,7 +52,7 @@ The implementation of this proposal is not necessarily backward compatible. Wallets implementing the new standard may maintain the previous system to support legacy applications during a transition period or indefinitely. Existing applications using the current Auth system should continue to operate, but immediate changes are recommended once this SIP is ratified. -## Implementation +## Reference Implementations ### Notes on Serialization @@ -266,7 +261,7 @@ Otherwise, no additional error codes are defined in this SIP. For historical reasons, a Stacks.js internal representation, based on the Stacks core code, has been used in serialized payloads to wallets. These representations are not human-readable and thus make debugging difficult. A better solution would be to rely on string literal enumeration, rather than magic values, which need additional lookups. -Relying on soley a hex-encoded also poses difficulties when building Stacks enabled web applications. +Relying on solely on hex-encoding also poses difficulties when building Stacks enabled web applications. #### Clarity values @@ -492,10 +487,18 @@ Listed below are some examples of the potentially unclear representations: Wallets can register their aliased provider objects however they see fit. For example, using the WBIP-004[^3] standard or [Wallet Standard](https://github.com/wallet-standard/wallet-standard)[^14]. -## Ratification +## Activation This SIP is considered ratified after Xverse and Leather (currently the largest wallets in the Stacks ecosystem) have implemented and launched the new standard. Once wallets have implemented the new standard, tooling (e.g. Stacks Connect) can be updated to support the new standard as well. +This SIP is not consensus breaking, thus the timeline for activation is not tied to Stacks releases. + +## Related Work + +This SIP is designed as a replacement for the existing Connect system, due to the issues mentioned above. + +The standard builds on top of the following work: the webbtc `.request` standard[^10], Wallet Standard[^14], and WBIPs[^11]. +This SIP is meant to be compatible with various use cases and is meant as a formal specification to unify and drive forward the wallet RPC ecosystem. ## Appendix From b9421a2a8d2c9acd8885d4601efc08f13b90abc7 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 21 Nov 2024 14:06:06 +0100 Subject: [PATCH 34/46] chore: pr feedback --- sips/sip-030/sip-030-wallet-interface.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 9976ffc8..fd559788 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -22,7 +22,7 @@ This SIP proposes common RPC methods to use for the Stacks blockchain's "Connect The goal is to replace the current Connect interface, primarily used by web applications to connect with browser extensions and mobile apps with a more straightforward protocol. This proposal's goal is to standardize JSON compatible interfaces for use with wallet interfaces. -## Motivation +## Introduction The current Connect system, which has existed for several years, is primarily utilized by web applications for interfacing with wallets. However, many aspects of the existing "Connect" and "Auth" libraries are no longer required, leading to unnecessary complexity (e.g., wrapping RPC payloads in jsontokens) and lack of clear definitions (e.g., undefined serialization for non-JSON compatible data structures) in wallet connectivity. @@ -76,14 +76,14 @@ Methods can be namespaced under `stx_` if used in more generic settings and othe In other cases (e.g. `WalletConnect`), the namespace may already be given by metadata (e.g. a `chainId` field) and can be omitted. On the predominant `StacksProvider` global object, the methods can be used without a namespace, but wallets may add namespaced aliases for convenience. -##### Transaction method general params +##### General parameters (for transaction methods) The following definitions can be used in the transaction methods. Parameter properties - `address?`: `string` address, Stacks c32-encoded, defaults to wallets current address -- `network?`: `'mainnet' | 'testnet' | 'regtest' | 'mocknet'` +- `network?`: `'mainnet' | 'testnet' | 'regtest' | 'devnet' | 'mocknet'` - `fee?`: `number | string` BigInt constructor compatible value - `nonce?`: `number | string` BigInt constructor compatible value - `postConditions?`: `PostCondition[]`, defaults to `[]` @@ -489,7 +489,8 @@ For example, using the WBIP-004[^3] standard or [Wallet Standard](https://github ## Activation -This SIP is considered ratified after Xverse and Leather (currently the largest wallets in the Stacks ecosystem) have implemented and launched the new standard. +This SIP is considered _Ratified_ after Xverse and Leather (currently the largest wallets in the Stacks ecosystem) have implemented and launched the new standard. + Once wallets have implemented the new standard, tooling (e.g. Stacks Connect) can be updated to support the new standard as well. This SIP is not consensus breaking, thus the timeline for activation is not tied to Stacks releases. From 93eee63307545359d826f3224835527c2a148e9f Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 21 Nov 2024 14:08:26 +0100 Subject: [PATCH 35/46] chore: pr feedback --- sips/sip-030/sip-030-wallet-interface.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index fd559788..4ed35026 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -83,7 +83,8 @@ The following definitions can be used in the transaction methods. Parameter properties - `address?`: `string` address, Stacks c32-encoded, defaults to wallets current address -- `network?`: `'mainnet' | 'testnet' | 'regtest' | 'devnet' | 'mocknet'` +- `network?`: `'mainnet' | 'testnet' | 'regtest' | 'devnet' | 'mocknet' | NetworkId` + - where `NetworkId extends string` and can be a network identifier, which already exists in the wallet (e.g. a URL or network name) - `fee?`: `number | string` BigInt constructor compatible value - `nonce?`: `number | string` BigInt constructor compatible value - `postConditions?`: `PostCondition[]`, defaults to `[]` From f026526e44fb395ad5f22da1473480c8c9f0adf5 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 21 Nov 2024 14:09:57 +0100 Subject: [PATCH 36/46] chore: pr feedback --- sips/sip-030/sip-030-wallet-interface.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 4ed35026..9ebd33c1 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -504,16 +504,16 @@ This SIP is meant to be compatible with various use cases and is meant as a form ## Appendix -WBIPs + -> Documents partially worked on in the working group with Leather, Xverse, and others. +> WBIPs documents partially worked on in the working group with Leather, Xverse, and others. [^1]: [WBIP-001: Wallet API JSON RPC](https://wbips.netlify.app/wbips/WBIP001) [^2]: [WBIP-002: Namespaces](https://wbips.netlify.app/wbips/WBIP002) [^3]: [WBIP-004: Registration](https://wbips.netlify.app/wbips/WBIP004) [^4]: [WBIP-007: Batching](https://wbips.netlify.app/wbips/WBIP007) -Discussions + [^21]: [Wallet JSON RPC API, Request Accounts #2378](https://github.com/leather-wallet/extension/pull/2378) [^22]: [Sign-in with stacks #70](https://github.com/stacksgov/sips/pull/70) @@ -522,7 +522,7 @@ Discussions [^25]: [SIP for Authentication Protocol #50](https://github.com/stacksgov/sips/pull/50) [^26]: [Wallet client API](https://github.com/stacksgov/sips/issues/117) -References + [^10]: [WebBTC Request Standard](https://balls.dev/webbtc/extendability/extending/) [^11]: [WBIPs](https://wbips.netlify.app) From 8f5d316ffc4e0d01d0e238b8bc1f6d3cb19043eb Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 21 Nov 2024 14:11:37 +0100 Subject: [PATCH 37/46] chore: pr feedback --- sips/sip-030/sip-030-wallet-interface.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 9ebd33c1..442d316b 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -24,7 +24,7 @@ This proposal's goal is to standardize JSON compatible interfaces for use with w ## Introduction -The current Connect system, which has existed for several years, is primarily utilized by web applications for interfacing with wallets. +The current Connect system[^15], which has existed for several years, is primarily utilized by web applications for interfacing with wallets. However, many aspects of the existing "Connect" and "Auth" libraries are no longer required, leading to unnecessary complexity (e.g., wrapping RPC payloads in jsontokens) and lack of clear definitions (e.g., undefined serialization for non-JSON compatible data structures) in wallet connectivity. Recent attempts[^21][^22][^23][^24][^25][^26] to standardize the interface have sparked valuable discussions but have not culminated in a ratified standard, largely due to the stable state of the existing system. @@ -492,12 +492,12 @@ For example, using the WBIP-004[^3] standard or [Wallet Standard](https://github This SIP is considered _Ratified_ after Xverse and Leather (currently the largest wallets in the Stacks ecosystem) have implemented and launched the new standard. -Once wallets have implemented the new standard, tooling (e.g. Stacks Connect) can be updated to support the new standard as well. +Once wallets have implemented the new standard, tooling (e.g. Stacks Connect[^15]) can be updated to support the new standard as well. This SIP is not consensus breaking, thus the timeline for activation is not tied to Stacks releases. ## Related Work -This SIP is designed as a replacement for the existing Connect system, due to the issues mentioned above. +This SIP is designed as a replacement for the existing Connect system[^15], due to the issues mentioned above. The standard builds on top of the following work: the webbtc `.request` standard[^10], Wallet Standard[^14], and WBIPs[^11]. This SIP is meant to be compatible with various use cases and is meant as a formal specification to unify and drive forward the wallet RPC ecosystem. @@ -529,3 +529,4 @@ This SIP is meant to be compatible with various use cases and is meant as a form [^12]: [Xverse WalletConnect JSON API](https://docs.xverse.app/wallet-connect/reference/api_reference) [^13]: [Schema.org Person](https://schema.org/Person) [^14]: [Wallet Standard](https://github.com/wallet-standard/wallet-standard) +[^15]: [Stacks Connect](https://github.com/hirosystems/connect) From 6d1c101287e89bb1eefafa4a36c48724a71f83c2 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 21 Nov 2024 14:11:59 +0100 Subject: [PATCH 38/46] chore: pr feedback --- sips/sip-030/sip-030-wallet-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 442d316b..8c998d99 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -486,7 +486,7 @@ Listed below are some examples of the potentially unclear representations: ### Provider registration Wallets can register their aliased provider objects however they see fit. -For example, using the WBIP-004[^3] standard or [Wallet Standard](https://github.com/wallet-standard/wallet-standard)[^14]. +For example, using the WBIP-004[^3] standard or Wallet Standard[^14]. ## Activation From df7d3028901893533574822368e03855866be207 Mon Sep 17 00:00:00 2001 From: janniks Date: Tue, 14 Jan 2025 17:15:17 +0100 Subject: [PATCH 39/46] fix: update sip properties --- sips/sip-030/sip-030-wallet-interface.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 8c998d99..9327a232 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -195,8 +195,10 @@ Result properties Parameter properties -- `message`: `string` Clarity value, hex-encoded -- `domain`: `string` hex-encoded (defined by SIP-018) +- `message`: `ClarityValue` + - where `ClarityValue` is `string | object` hex-encoded or JSON representation +- `domain`: `ClarityTupleValue` + - where `ClarityTupleValue` (defined by SIP-018) is a Clarity "tuple" as `string | object` hex-encoded or JSON representation Result properties @@ -205,6 +207,8 @@ Result properties #### Method `stx_getAddresses` +> **Note**: This method can be used similarly to legacy "connect" methods, where the first account selection also acts as an approval of the site/domain. + Result properties - `addresses`: `{}[]` @@ -216,6 +220,8 @@ Result properties > **Comment**: This method is similar to `stx_getAddresses`. > It was added to provide better backwards compatibility for applications using Gaia. +> **Note**: This method can be used similarly to legacy "connect" methods, where the first account selection also acts as an approval of the site/domain. + Result properties - `accounts`: `{}[]` From 9121864dd392196f429223d3af468b6228c5dd94 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 16 Jan 2025 17:59:32 +0100 Subject: [PATCH 40/46] fix: fix sip number reference --- sips/sip-030/sip-030-wallet-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 9327a232..f7994bb3 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -126,7 +126,7 @@ Result properties - `txid`: `string` hex-encoded - `transaction`: `string` hex-encoded raw transaction -#### Method `stx_transferSip10Nft` +#### Method `stx_transferSip9Nft` Parameter properties From 5b54749a62db6c6a1bad74a458fbd7010bde0b16 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 16 Jan 2025 19:30:37 +0100 Subject: [PATCH 41/46] chore: add more details on the scope of the specification --- sips/sip-030/sip-030-wallet-interface.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index f7994bb3..fe948743 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -43,12 +43,17 @@ So this SIP aims to capture the important features for the Stacks ecosystem, wit The proposed changes are listed as follows: -Specify [JSON-RPC 2.0](https://www.jsonrpc.org/specification) compatible methods and payloads for wallet interaction. -These can be used via a browser object (i.e., via the `window.WalletProvider.request` method) or similar interfaces like WalletConnect. +- Use [JSON-RPC 2.0](https://www.jsonrpc.org/specification) as the underlying protocol for wallet interaction. +- Specify compatible RPC methods and payloads for wallet interaction. +- Define a recommended provider object and its discovery mechanism. + +> **Note**: The methods can be used via the mentioned browser object (i.e., via the `window.WalletProvider.request` method), but also through similar interfaces like WalletConnect. ## Backwards Compatibility The implementation of this proposal is not necessarily backward compatible. +Notably, app-specific private keys for domains have been removed from the connect protocol, but can still be accessed via the `gaiaAppKey` field in `stx_getAccounts`. + Wallets implementing the new standard may maintain the previous system to support legacy applications during a transition period or indefinitely. Existing applications using the current Auth system should continue to operate, but immediate changes are recommended once this SIP is ratified. From 61f5cda5e643a79b4f1dfe3214e874101bf0a811 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 16 Jan 2025 19:31:27 +0100 Subject: [PATCH 42/46] chore: update network functions --- sips/sip-030/sip-030-wallet-interface.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index fe948743..c5eb3194 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -235,6 +235,16 @@ Result properties - `gaiaHubUrl`: `string` URL - `gaiaAppKey`: `string` hex-encoded +#### Method `stx_getNetworks` + +Result properties + +- `active`: `string` network identifier +- `networks`: `{}[]` + - `id`: `string` + - `chainId`: `number` + - `transactionVersion`: `number` + #### Method `stx_updateProfile` Parameter properties @@ -255,13 +265,20 @@ In addition to the request interface, event listeners may be provided via the `. The event name should be closer to nouns than verbs and doesn't use the `on` prefix from DOM naming conventions. -#### Event `accountChange` +#### Event `stx_accountChange` -`listener: (accounts: {}[]) => void` +- `listener: (accounts: {}[]) => void` > `accounts` as defined above in `stx_getAccounts`. > The first account is considered the default account (and may be the only "active" account in a wallet). +#### Event `stx_networkChange` + +- `listener: (data: GetNetworksResult) => void` + - where `GetNetworksResult` matches the `stx_getNetworks` result type + +> This event may be emitted when the active network changes and on first load of the wallet/site. + ### Error Codes Errors thrown by request methods should match existing JSON-RPC 2.0 error codes. From 7b375feba6fdb52928168c7808114305d11eae18 Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 16 Jan 2025 19:37:13 +0100 Subject: [PATCH 43/46] chore: mention clarity value type --- sips/sip-030/sip-030-wallet-interface.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index c5eb3194..e7cde84c 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -294,9 +294,11 @@ Relying on solely on hex-encoding also poses difficulties when building Stacks e #### Clarity values -Proposed below is an updated interface representation for Clarity primitives for use in Stacks.js and JSON compatible environments. +Clarity values should be represented in the following format for use in Stacks.js and JSON compatible environments: -> **Comment**: For encoding larger than JS `Number` big integers, `string` is used. +> **Comment**: For encoding larger than JS `Number` big integers, `string` is used with `bigint` any compatible values. + +> `ClarityValue` is `string | object` hex-encoded or JSON representation of any of the below Clarity values. `0x00` `int` @@ -364,7 +366,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { type: 'ok', - value: object // Clarity value + value: ClarityValue // Clarity value } ``` @@ -373,7 +375,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { type: 'err', - value: object // Clarity value + value: ClarityValue // Clarity value } ``` @@ -390,7 +392,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { type: 'some', - value: object // Clarity value + value: ClarityValue // Clarity value } ``` @@ -399,7 +401,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { type: 'list', - value: object[] // Array of Clarity values + value: ClarityValue[] // Array of Clarity values } ``` @@ -408,7 +410,7 @@ Proposed below is an updated interface representation for Clarity primitives for ```ts { type: 'tuple', - value: Record // Record of Clarity values + value: Record // Record of Clarity values } ``` @@ -463,7 +465,7 @@ Proposed below is an updated interface representation for Clarity primitives for address: 'origin' | string | `${string}.${string}`, // Stacks c32-encoded, with optional contract name suffix condition: 'sent' | 'not-sent', asset: `${string}.${string}::${string}` // address with contract name suffix with asset suffix, Stacks c32-encoded - assetId: object, // Clarity value + assetId: ClarityValue, // Clarity value } ``` @@ -479,8 +481,8 @@ Listed below are some examples of the potentially unclear representations: { type: "list", value: [ - { type: "int", value: "4"}, - { type: "int", value: "8"}, + { type: "int", value: "4" }, + { type: "int", value: "8" }, ] } ``` @@ -488,7 +490,7 @@ Listed below are some examples of the potentially unclear representations: ``` { type: "err", - value: { type: "uint", value: "4"}, + value: { type: "uint", value: "4" }, } ``` - "sends more than 10000 uSTX" = From 87afbb2458b817dc675cba4e5bae6d75fdb71e5a Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 16 Jan 2025 19:56:46 +0100 Subject: [PATCH 44/46] chore: add auth to related work --- sips/sip-030/sip-030-wallet-interface.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index e7cde84c..aae3e220 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -532,6 +532,15 @@ This SIP is designed as a replacement for the existing Connect system[^15], due The standard builds on top of the following work: the webbtc `.request` standard[^10], Wallet Standard[^14], and WBIPs[^11]. This SIP is meant to be compatible with various use cases and is meant as a formal specification to unify and drive forward the wallet RPC ecosystem. +### Auth + +One of the core libraries referenced in this proposal is often called "Auth", which is packaged within the existing Stacks "Connect" libraries[^15], as well as separately as `@stacks/auth` on npm. +This Auth system is a legacy Blockstack library, which was never specified in a SIP. +It relies on wrapping RPC payloads in jsontokens. + +While Auth served as an essential building block for the legacy Blockstack system, its assumptions are no longer strictly necessary. +By using a simpler JSON-RPC 2.0–based approach for wallet connectivity, this SIP removes the need for Auth. + ## Appendix From e963f950ece3b96a2e0c1bf59d5553f4e1a36e9d Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 16 Jan 2025 19:57:58 +0100 Subject: [PATCH 45/46] chore: udpate activation phrasing --- sips/sip-030/sip-030-wallet-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index aae3e220..7f42cb85 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -520,7 +520,7 @@ For example, using the WBIP-004[^3] standard or Wallet Standard[^14]. ## Activation -This SIP is considered _Ratified_ after Xverse and Leather (currently the largest wallets in the Stacks ecosystem) have implemented and launched the new standard. +This SIP is considered _Ratified_ after at least two wallet providers with significant user adoption (> 10,000 monthly active users) have implemented and launched the new standard. Once wallets have implemented the new standard, tooling (e.g. Stacks Connect[^15]) can be updated to support the new standard as well. This SIP is not consensus breaking, thus the timeline for activation is not tied to Stacks releases. From 47096d8b0b567a2ca326468cc6df73f5c504346e Mon Sep 17 00:00:00 2001 From: janniks Date: Thu, 16 Jan 2025 19:59:22 +0100 Subject: [PATCH 46/46] chore: mention sbtc --- sips/sip-030/sip-030-wallet-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-030/sip-030-wallet-interface.md b/sips/sip-030/sip-030-wallet-interface.md index 7f42cb85..5bd87b59 100644 --- a/sips/sip-030/sip-030-wallet-interface.md +++ b/sips/sip-030/sip-030-wallet-interface.md @@ -31,7 +31,7 @@ Recent attempts[^21][^22][^23][^24][^25][^26] to standardize the interface have This SIP aims to address these issues by adopting the WBIPs standards[^11], which offer a more suitable RPC-style interface for modern web applications. The simplified protocol will allow integration without heavy dependencies (like Auth) and provide a more extendable interface for wallets. -Additionally, this SIP is motivated by the increased traffic of Ordinal inscriptions on Bitcoin and the Stacks ecosystem growing closer to Bitcoin. +Additionally, this SIP is motivated by the increased traffic of Ordinal inscriptions on Bitcoin and upcoming integrations like sBTC that require standardized Stacks and Bitcoin transaction signing capabilities in wallets. The community has recognized the need for a more unified approach to wallet connectivity (e.g. Bitcoin and PSBTs for previously Stacks-only wallets). By adopting the new standard, we aim to align the community towards a common and modern protocol for wallet interaction in web applications. Importantly, the decision to use an existing standard (rather than designing a new one or reworking Auth) is intentional — to avoid further division or split ownership within the community.