From 20e90eba35ed17875e0dcb14c9cac2c33b4599ce Mon Sep 17 00:00:00 2001 From: Weiwu Zhang Date: Wed, 25 May 2022 20:10:11 +1000 Subject: [PATCH 1/7] rename so every file look the same --- ERCs/{ERC5XX2.md => ERC5XX2 draft.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename ERCs/{ERC5XX2.md => ERC5XX2 draft.md} (100%) diff --git a/ERCs/ERC5XX2.md b/ERCs/ERC5XX2 draft.md similarity index 100% rename from ERCs/ERC5XX2.md rename to ERCs/ERC5XX2 draft.md From 40759992404e8f3596a83890cdc17ede19873991 Mon Sep 17 00:00:00 2001 From: Weiwu Zhang Date: Wed, 25 May 2022 20:37:47 +1000 Subject: [PATCH 2/7] wording update, mostly --- ERCs/ERC5XX0 draft.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/ERCs/ERC5XX0 draft.md b/ERCs/ERC5XX0 draft.md index 4421e4c6..6fc0a811 100644 --- a/ERCs/ERC5XX0 draft.md +++ b/ERCs/ERC5XX0 draft.md @@ -35,11 +35,11 @@ While the simplest solutions to facilitate specific script usage associated with 2. Updates require smart contract interaction. Simply posting a new transaction on Ethereum is not cheap! When this transaction also includes smart contract logic, the price can quickly become significant. If frequent updates are needed, then smart contract calls can in itself becomes a hurdle. 3. Storage fee. If the script is large, contains special graphics or other large elements, then updates to the script can quickly costs thousands of dollars. -For these reasons it makes sense to store volatile data, such as token enhancing functionality, on an external resource. Such an external resource can be either centralized, such as a cloud provider or private server, or decentralized such as the interplanetary filesystem. +For these reasons it makes sense to store volatile data, such as token enhancing functionality, on an external resource. Such an external resource can be either central hosted, such as a cloud provider or privately hosted with a private server, or decentralized such as the interplanetary filesystem. -Since using centralized storage for a decentralized functionality goes against the ethos of web3, this ERC handle this this by allowing the token provider to store multiple URIs to the script on-chain. The URIs might point to either multiple centralized storage providers or fully decentralized ones, e.g. the IPFS, another blockchain or even on Ethereum itself. It could also be a mix of centralized and decentralized locations. +While centralized storage for a decentralized functionality goes against the ethos of web3, fully decentralized solutions may come with speed or availability penalties. This ERC handle this this by allowing the token provider to store multiple URIs. It could also be a mix of centralized, individually hosted and decentralized locations. -While this ERC does not dictate the format of the stored script, it should be noted that the script itself could contain pointers to multiple other scripts and data sources. Hence this allows for advanced and rich expansion of tokens. +While this ERC does not dictate the format of the stored script, it should be noted that the script itself could contain pointers to multiple other scripts and data sources, allowing for advanced ways to expand token scripts, such as lazy loading. The handling of integrity of such secondary data sources is left dependent on the format of the script. For example, HTML format uses [the `integrity` property](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity), while [signed XML format has ``](https://www.w3.org/TR/xmldsig-core2/#sec-Manifest). #### Authenticity @@ -52,20 +52,23 @@ For validation of authenticity we consider two different cases: #### Script updates -Besides issues of script location, another issue is how the script can be updated in a manner where the caller can be sure it is authentic. -We solve this issue by allowing the issuer to update the `scriptURI` on-chain, when the URI points to an immutable location or the URI itself contains info for script validation. +Besides issues of script location, another issue is how the script can be updated in a manner where the caller can be sure it is authentic. + +We address this issue by allowing the issuer to update the `scriptURI` on-chain, when the URI points to an immutable location or the URI itself contains info for script validation. + This ensures that the script can be changed, even in cases where the URI points to a location based on the hash digest of the script (which is the case if it is stored on the IPFS). + If instead the `scriptURI` points to a mutable location, it can be updated without on-chain interaction, as described in ERC 5XX1. #### Overview With the discussion above in mind we outline the solution proposed by this ERC. For this purpose we consider the following variables: -- `SCPrivKey`: The private signing key controlling a smart contract implementing this ERC, which is associated with the tokens issued. +- `SCPrivKey`: The private signing key to administrate a smart contract implementing this ERC, which is associated with the tokens issued. - `script`: The script supplying additional functionality to the tokens. With these variables in mind we can describe the life cycle of the `scriptURI` functionality: - Issuance -1. The token issuer issues the tokens and a smart contract implementing this ERC, with the controlling signing key for the smart contract being `SCPrivKey`. +1. The token issuer issues the tokens and a smart contract implementing this ERC, with the admin signing key for the smart contract being `SCPrivKey`. 2. The token issuer calls `setScriptURI` with the `scriptURI`. - Update `scriptURI` From 99dc909527751b623fc3702a15ca3c385307ddf8 Mon Sep 17 00:00:00 2001 From: Weiwu Zhang Date: Wed, 25 May 2022 20:46:17 +1000 Subject: [PATCH 3/7] Refine language --- ERCs/ERC5XX1 draft.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/ERCs/ERC5XX1 draft.md b/ERCs/ERC5XX1 draft.md index 4a31836a..b1944b7d 100644 --- a/ERCs/ERC5XX1 draft.md +++ b/ERCs/ERC5XX1 draft.md @@ -26,17 +26,20 @@ This ERC describes how to assert the authenticity of the script related to some Often NFT authors want to provide some user functionality to their tokens through client scripts. This should be done safely, without opening the user to potential scams. Refer to ERC xxxx examples of such scripts. -Although ERC xxxx specified a way to obtain a set of client scripts through URI, in many cases, it is: +Although ERC xxxx specified a way to obtain a set of client scripts through URI, it is inapplicable for token contracts that was issued before the creation of ERC xxxx. Furthermore, it lack the finess to address situations such as -- insufficient: For example, a smart contract might have a script for different environments or use-cases. Take a subway token as an example. It might invoke a minimal script to drive the purchase and use of subway tokens in order to send them through NFC (Internet might be slow or inaccessible underground). +- a smart contract might have different scripts for different environments or use-cases. Take a subway token as an example. It might invoke a minimal script at the POS to be sent through NFC (Internet might be slow or inaccessible underground), while advanced functions for user retention, such as rewarding user mascot NFT for continued use, or carbon credit for buying carbon-neutral airfare. +- in a specific use case, a token's script is often localized, and it doesn't make sense to download and load all language translations. +- a specific use-case might be compatible with only a specific version of the token's script. -- inapplicable: For example for token contracts that was issued before the creation of ERC xxxx. +ERC xxxx returns an all-purpose, one-version of script for use on the client side ignoring the nuances. This ERC offers a way to assert authenticity of such client scripts disregarding how it is obtained, and can work with smart contracts *prior* to the publication of this ERC. ### Overview Although the *token/smart contract author* and the *client script author* can be the same person/team, we will assume they are different people in this ERC, and the case that they are the same person/team can be implied. + The steps needed to ensure script authenticity can be summarized as follows: 1. The *script author* creates a *script signing key*, which has an associates *verification key address*. From f90e11920070053db847b30dc8c657be35f18f4e Mon Sep 17 00:00:00 2001 From: Tore Kasper Frederiksen Date: Wed, 25 May 2022 12:56:53 +0200 Subject: [PATCH 4/7] Changed from struct to string[] --- ERCs/ERC5XX0 draft.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/ERCs/ERC5XX0 draft.md b/ERCs/ERC5XX0 draft.md index 6fc0a811..ab3933e2 100644 --- a/ERCs/ERC5XX0 draft.md +++ b/ERCs/ERC5XX0 draft.md @@ -79,28 +79,21 @@ With these variables in mind we can describe the life cycle of the `scriptURI` f ### Specification The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY” and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. -We define a scriptURI element using the following structs: - -``` -struct scriptURI { - string[] URIOfScript; -} -``` - -Based on these elements we define the smart contract interface below: +We define a scriptURI element using the `string[]`. +Based on this we define the smart contract interface below: ``` interface IERC5XX0 { /// @dev This event emits when the scriptURI is updated, /// so wallets implementing this interface can update a cached script - event ScriptUpdate(scriptURI memory newScriptURI); + event ScriptUpdate(string[] memory newScriptURI); /// @notice Get the scriptURI for the contract /// @return The scriptURI - function scriptURI() external view returns(scriptURI memory); + function scriptURI() external view returns(string[] memory); /// @notice Update the scriptURI /// emits event ScriptUpdate(scriptURI memory newScriptURI); - function setScriptURI(scriptURI memory newScriptURI, bytes memory newSigScriptURI) external; + function setScriptURI(string[] memory newScriptURI, bytes memory newSigScriptURI) external; } ``` The interface MUST be implemented under the following constraints: From f87bebcb89c3b1ddb40ebb092c1e9eec8e9f87ae Mon Sep 17 00:00:00 2001 From: Tore Kasper Frederiksen Date: Wed, 25 May 2022 13:44:14 +0200 Subject: [PATCH 5/7] Added suggestion of self administration of array of scripturi --- ERCs/ERC5XX0 draft.md | 1 + 1 file changed, 1 insertion(+) diff --git a/ERCs/ERC5XX0 draft.md b/ERCs/ERC5XX0 draft.md index 743dcc33..a7f6b4db 100644 --- a/ERCs/ERC5XX0 draft.md +++ b/ERCs/ERC5XX0 draft.md @@ -114,6 +114,7 @@ The interface MUST be implemented under the following constraints: - Any user of the script learned from `scriptURI` MUST validate the script is either at an immutable location, its URI contains its hash digest, or that it implements ERC 5XX1. +We note that while the interface specify batch updates of the `scriptURI`, developers can of course enhance the interface with other methods, adding more flexibility in how the `scriptURI` state is managed on-chain. ### Rationale Using this method avoids the need for building secure and certified centralised hosting and allow scripts to be hosted anywhere: IPFS, GitHub or cloud storage. From cc8dd27567443c92c18d4df3bcf4b802873041df Mon Sep 17 00:00:00 2001 From: James Brown Date: Mon, 30 May 2022 15:49:46 +0800 Subject: [PATCH 6/7] Add sample implementations --- ERCs/ERC5XX1 draft.md | 35 +++++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/ERCs/ERC5XX1 draft.md b/ERCs/ERC5XX1 draft.md index b1944b7d..8fec6e8a 100644 --- a/ERCs/ERC5XX1 draft.md +++ b/ERCs/ERC5XX1 draft.md @@ -52,21 +52,48 @@ This process is a deliberate copy of the TLS certification, based on X.509, whic The authenticity of the client script may be obtained through the `scriptURI()` function call, as in ERC5XX0, or supplied separately by the use-cases. However, this ERC is applicable to any code or data that is signed, and a client must validate the signature in the way specified in this ERC. In real life use-cases, the client scripts can be either supplied by aforementioned `scriptURI()` or offered to the client (wallet) in anyway the wallet can work with, even through NFC connections or QR code. +### Implementation + +Some possible methods of implementation: Note: we cannot deliver a completely off-line solution unless a hosting app can pre-verify the *smart contract deployment key* address. + +1. Simplest (assuming internet connection and written *after* publication of this ERC): + +- JWS object outlined below (containing: The script itself, URI to certificate, signature of the script signed by *script signing key*) is linked to via scriptURI() in the contract. +- 1: determine *smart contract deployment key*. Contract should preferrably implement standard 'Ownable' interface or at least the 'owner()' function. +- 2: fetch the JWS object by querying the scriptURI() in the contract. +- 3: fetch the certificate linked to from the JWS in the `x5u` header. +- 4: validate that certificate is signed by the *smart contract deployment key*. +- 5: obtain the address of the *script signing key* from the `SubjectPublicKeyInfo` field of the certificate. +- 6: obtain the script itself; in our example it will be bundled in the JWS object itself, along with the signature attached to the script, in the tag. +- 7: verify that the signature from the tag is the correct signature of the keccak'd script by the *script signing key*. +- 8: current time is within `notBefore` and `notAfter`. +- 9: if the *script signing key* is still valid according to the certificate *and* the script has been signed correctly by the same key, allow user to interact with the token contract(s) defined in the script via the script interface. + +2. Example script applied to contract published before this ERC: + +- User scans NFC beacon on their mobile. +- Obtains payload with an app intent (eg ticketing app) containing a URL to a JWS object. +- JWS Object is fetched along with the script pointed to from the JWS object. +- Determine origin contract from script. +- Obtain the owner of the script query `owner()` or JWS object provides contract creation transaction the hosting app can validate and obtain *smart contract deployment key* address. +- Continue from `3:` above, skipping `6:` as we already have the script. +- If the *script signing key* is still valid according to the certificate *and* the script has been signed correctly by the same key, allow user to interact with the token contract(s) defined in the script via the script interface. + ### Specification The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY” and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). #### Format of the certificate and signature The certificate for the *script signing key* MUST be in the X.509 format, in accordance with [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280). -Furthermore, the certificate MUST by signed by the *smart contract author* as the issuer, using the *smart contract deployment key*. +Furthermore, the certificate MUST by signed by the *smart contract author* as the issuer, using the *smart contract deployment key*. We furthermore make the following requirements of the content of this certificate: - The `issuer` field MUST be populated with a Common Name, which MUST be the address of the verification key associated with the *smart contract deployment key*. E.g. `CN=0x12345678901234567890`. -- The `SubjectPublicKeyInfo` field MUST contain the public part of the *script signing key*. +- The `SubjectPublicKeyInfo` field MUST contain the public part of the *script signing key*. -- The `extensions` field SHOULD be set to include `KeyUsage` (see RFC 5280 sec. 4.2.1.3) with bit 0 set, to indicate that the *script signing key* is used for signing only. Furthermore the *Extended Key Usage* extensions SHOULD also be included, with only the *id-kp-codeSigning* identifier set (See RFC 52080 sec. 4.2.1.12). +- The `extensions` field SHOULD be set to include `KeyUsage` (see RFC 5280 sec. 4.2.1.3) with bit 0 set, to indicate that the *script signing key* is used for signing only. Furthermore the *Extended Key Usage* extensions SHOULD also be included, with only the *id-kp-codeSigning* identifier set (See RFC 52080 sec. 4.2.1.12). - If [revocation option 1](#Revocation) is used, then `extensions` MUST also include `cRLDistributionPoints` (see RFC 5280 4.2.1.13) which MUST contain at least one `distributionPoint` element, containing a `fullName` element. The `fullName` MUST be a single `IA5String` for a `uniformResourceIdentifier` which is an URI pointing to a Certificate Revocation List. @@ -86,7 +113,7 @@ We require the signature to be done as a JWS according to [RFC 7515](https://dat This ERC does not specify how a wallet client obtains the signature as this can be realized in multiple ways. The simplest of which is to embed the client script in the `payload` of the JWS, as discussed above. This ensure that only a single URI is needed in order to locate both the client script, its signature and the signing key certificate. -If the client script is stored in a directory (e.g. on a webserver), i.e. with a file-name instead of with a hash digest identifier, then the JWS can simply be stored using the same URI as the client script, with ".jws" or ".sig" appended. +If the client script is stored in a directory (e.g. on a webserver), i.e. with a file-name instead of with a hash digest identifier, then the JWS can simply be stored using the same URI as the client script, with ".jws" or ".sig" appended. #### Revocation From f2c490181432974132dd0942f63d0ce01aca69c5 Mon Sep 17 00:00:00 2001 From: Weiwu Zhang Date: Tue, 7 Jun 2022 16:39:46 +1000 Subject: [PATCH 7/7] trivial text change. --- ERCs/ERC5XX0 draft.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ERCs/ERC5XX0 draft.md b/ERCs/ERC5XX0 draft.md index a7f6b4db..3743dcc1 100644 --- a/ERCs/ERC5XX0 draft.md +++ b/ERCs/ERC5XX0 draft.md @@ -16,9 +16,9 @@ Often Smart Contract authors want to provide some user functionality to their to This ERC proposes adding a `scriptURI` which is a structure containing an array of URIs to external resources, such as in IPFS, GitHub, a cloud provider, etc., which will store the actual script. -Each `scriptURI` semantically contains access information to access a *single* signed script, stored in one or more off-chain locations. +Each `scriptURI` semantically contains access information to access a *single* script, stored in one or more off-chain locations. -Concretely each element in the array contains a URI to the script itself. +Concretely each element in the array contains a URI to the same script. The script provides a client-side executable to the hosting token. Examples of such a script could be: