Signing a TokenScript
TokenScript files are signed by the token issuer, usually.
The TokenScript files are signed for two distinct reasons.
First, to associate the TokenScript to the identity of the issuer.
Second, to link to the smart contracts it interacts with.
- Associate the signature with an identity
- Associate the signature with an identity, such as a domain name - e.g. "aave.com" - by attaching a certificate to the signature. Domain cerifiicate is the most convenient type to obtain, but any identity that can be ceritified through a trusted X.509 certificate authority should do.
- Link TokenScript with smart contracts
- Used for transaction security. If a smart contract trusts TokenScript, the transaction generated from that TokenScript is displayed with a trust badge. This is similar to how a website might be displayed with a trust badge if it properly uses https.
The former is done during signing of the TokenScript; the second is done separately, outside of TokenScript signing.
TokenScript can't be deployed for production use if it is unsigned. But you can debug an unsigned TokenScript (they will be displayed as untrusted by TokenScript Engine).
Sometimes, parts of TokenScript have to be signed twice
We recommend a TokenScript signature always be associated with an identity through an certificate.
However, the Smart Contract might be from a different team than the TokenScript author, where wholesale trust to the identity is not possible.
For example, AAVE team might create a token action for DAI token that is called "Enable Deposit to AAVE". This effectively authorises Uniswap's smart contract to act on-behalf of AAVE token holder. Since such an action transacts to the DAI token contract, that token contract need to express trust to that action's code.
AAVE team reaches out to the DAI team, and ask DAI token contract to express trust by identity, in this case, "aave.com". DAI token contract team reasonably rejected the proposal, since they don't know what TokenScript AAVE team will sign - in the worst case, it could be a "Try me" action which simply steals user's AAVE tokens from the contract.
In this case, DAI contract will only express trust towards a key associated with the identity "makerdao.com". And AAVE team has to send their TokenScript - at least the relevant action part - to the DAI team to be signed by that key.
This would result in a TokenScript that is signed 2 times.
A TokenScript Engine would identify the two signatures as such: one that expresses authorship, the other was trusted by the smart contract through associated identity.
In such a scenario, the identity of the authorship is always displayed to the user, while if the user is to perform the action, the express of trust is evaluated and the result is displayed together with the identity involved (in this case, "makerdao.com").
It's possible to express trust to a key, instead of an identifier
Can a smart contract expresses trust to a signing key instead of an identifier such as domain name?
Such a need is discussed in the TokenScript weekly committee meeting however we don't know how practically they are needed, so this section is only available for implementers as reference material. In that case, each key has a name.
- Reputation Key
- let's user accept the TokenScript based on the reputation of the website or organisation. In the simplest case, a website SSL certificate with the corresponding key will do. A EV certificate would be better.
- Trust Key
- is either returned as part of the metadata of a Smart Contract, or, if the Smart Contract doesn't support returning such meta-data, through an express-of-trust transaction from the Smart Contract's deployment key
Does the signer need to be the smart contract author?
It's not required, even though it's often the case.
TokenScript can be maintained by a member of your team who isn't the smart contract developer or administrator. In this case, the smart contract needs to express trust to the key or the identifier of the key.
But it can also be done by another party, which gained trust from the token issuer. In this case, it's better if the TokenScript, or the relative portion, be signed twice. Once by the author of the TokenScript - aw.app, AlphaWallet, made some TokenScript on behalf of the Token Issuer - and once by the Token Issuer themselves.
Signing referred resources
Any data reference - icons, images and language packs - used by the
TokenScript must be referred to in the
<SignedInfo> section of
the XML signature using the
<Reference> element. If they don’t,
they will not be available for the user agent. Each reference is downloaded and its
digest verified as part of the TokenScript signature verification process. If any of
the references fails to download or the digest doesn't match, the entire XML
signature is considered invalid.