NEP-452 Linkdrop Standard

neps/nep-0452.md

@@ -0,0 +1,213 @@
+---
+NEP: 452
+Title: Linkdrop Standard
+Author: Ben Kurrek <ben.kurrek@near.org>, Ken Miyachi <ken.miyachi@near.foundation>
+DiscussionsTo: https://gov.near.org/t/official-linkdrop-standard/32463/1
+Status: Draft
+Type: Standards Track
+Category: Contract
+Version: 1.0.0
+Created: 24-Jan-2023
+Updated: 24-Jan-2023
+---
+
+## Summary
+
+A standard interface for linkdrops that support $NEAR, fungible tokens, non-fungible tokens, and is extensible for linkdrops of any type.
+
+## Motivation
+
+Linkdrops are an extremely powerful tool that enable seamless onboarding and instant crypto experiences with the click of a link. The original [near-linkdrop](https://github.com/near/near-linkdrop) contract provides a minimal interface allowing users to embed $NEAR within an access key and create a simple Web2 style link that can then be used as a means of onboarding. This simple $NEAR linkdrop is not enough as many artists, developers, event coordinators, and applications want to drop more digital assets such as NFTs, FTs, tickets etc.
+
+As linkdrop implementations start to push the boundaries of what’s possible, new data structures, methods, and interfaces are being developed. There needs to be a standard data model and interface put into place to ensure assets can be claimed independent of the contract they came from. If not, integrating any application with linkdrops will require customized solutions, which would become cumbersome for the developer and deteriorate the user onboarding experience. The linkdrop standard addresses these issues by providing a simple and extensible standard data model and interface.
+
+The initial discussion can be found [here](https://gov.near.org/t/official-linkdrop-standard/32463/1).
+
+## Rationale and Alternatives
+
+* Why is this design the best in the space of possible designs?
+
+This design allows for flexibility and extensibility of the standard while providing a set of criteria that cover the majority of current linkdrop use cases. The design was heavily inspired by current, functional NEPs such as the Fungible Token and Non-Fungible Token standards.
+
+* What other designs have been considered and what is the rationale for not choosing them?
+
+A generic data struct that all drop types needed to inherit from. This struct contained a name and some metadata in the form of stringified JSON. This made it easily extensible for any new types down the road. The rationale for not choosing this design was both simplicity and flexibility. Having one data struct required keys to be of one type only when in reality, they can be many at once. In addition, having a generic, open-ended metadata field could lead to many interpretations and different designs. We chose to use a KeyInfo struct that can be easily extensible and can cover all use-cases by having optional vectors of different data types. The proposed standard is simple, supports drops with multiple assets, and is backwards compatible with all previous linkdrops, and can be extended very easily.
+
+A standard linkdrop creation interface. A standardized linkdrop creation interface would provide data models and functions to ensure linkdrops were created and stored in a specific format. The rationale for not choosing this design was that is was too restrictive. Standardizing linkdrop creation adds complexity and reduces flexibility by restricting linkdrop creators in the process in which linkdrops are created, and potentially limiting linkdrop functionality. The functionality of the linkdrop creation, such as refunding of assets, access keys, and batch creation, should be chosen by the linkdrop creator and live within the linkdrop creator platform. Further, linkdrop creation is often not displayed to end users and there is not an inherent value proposition for a standardized linkdrop creation interface from a client perspective. 
+
+* What is the impact of not doing this?
+
+The impact of not doing this is creating a fragmented ecosystem of linkdrops, increasing the friction for user onboarding. Linkdrop claim pages (e.g. wallet providers) would have to implement custom integrations for every linkdrop provider platform. Inherently this would lead to a bad user experience when new users are onboarding and interacting with linkdrops in general.
+
+## Specification
+
+```ts
+/// Information about a specific public key.
+type KeyInfo = {
+   /// How much Gas should be attached when the key is used to call `claim` or `create_account_and_claim`.
+   /// If not provided, a default value of 100 TGas will be attached to the transaction.
+   required_gas: string | null
+   /// yoctoNEAR$ amount that will be sent to the claiming account (either new or existing)
+   /// when the key is successfully used.
+   balance: string,
+
+   /// If using the NFT standard extension, a set of NFTData can be linked to the public key      
+   /// indicating that all those assets will be sent to the claiming account (either new or   
+   /// existing) when the key is successfully used.
+   nft_data: NFTData[] | null,
+
+   /// If using the FT standard extension, a set of FTData can be linked to the public key      
+   /// indicating that all those assets will be sent to the claiming account (either new or   
+   /// existing) when the key is successfully used.
+   ft_data: FTData[] | null,
+
+   /// ... other types can be introduced and the standard is easily extendable.
+}
+
+
+/// Data outlining a specific Non-Fungible Token that should be sent to the claiming account /// (either new or existing) when a key is successfully used.
+type NFTData = {
+   /// the id of the token to transfer
+   token_id: string,
+   /// The valid NEAR account indicating the Non-Fungible Token contract.
+   contract_id: string
+}
+
+
+/// Data outlining Fungible Tokens that should be sent to the claiming account 
+/// (either new or existing) when a key is successfully used.
+type FTData = {
+   /// The number of tokens to transfer, wrapped in quotes and treated
+   /// like a string, although the number will be stored as an unsigned integer
+   /// with 128 bits.
+   amount: string,
+   /// The valid NEAR account indicating the Fungible Token contract.
+   contract_id: string
+}
+
+
+
+
+/****************/
+/* VIEW METHODS */
+/****************/
+
+/// Deprecated - use `get_key_information` instead. This method provides backwards compatibility with previous implementations.
+/// Returns the $yoctoNEAR amount associated with a given public key 
+/// Panics if the key does not exist. 
+/// The Public key must be in a binary format with base58 string serialization with human-readable curve. The key types currently supported are secp256k1 and ed25519. Ed25519 public keys accepted are 32 bytes and secp256k1 keys are the uncompressed 64 format.
+function get_key_balance(key: string) -> string
+
+/// Returns the KeyInfo associated with a given public key
+/// Panics if the key does not exist
+/// The Public key must be in a binary format with base58 string serialization with human-readable curve. The key types currently supported are secp256k1 and ed25519. Ed25519 public keys accepted are 32 bytes and secp256k1 keys are the uncompressed 64 format.
+function get_key_information(key: string) -> KeyInfo
+
+/******************/
+/* CHANGE METHODS */
+/******************/
+
+/// Transfer all assets linked to the signer’s public key to an *existing* NEAR account. 
+/// If the transfer fails for whatever reason, it is up to the smart contract developer to 
+/// choose what should happen. For example, the contract can choose to keep the assets 
+/// or send them back to the original linkdrop creator.
+/// 
+/// Requirements:
+/// * The predecessor account *MUST* be the current contract ID.
+/// * The assets being sent *MUST* be associated with the signer’s public key.
+/// * The assets *MUST* be sent to the `account_id` passed in.
+///
+/// Arguments:
+/// * `account_id` the account that should receive the linkdrop assets.
+function claim(account_id: string) -> Promise
+
+
+
+/// Creates a new NEAR account and transfers all assets linked to the signer’s public key to 
+/// the *newly created account*. If the transfer fails for whatever reason, it is up to the 
+/// smart contract developer to choose what should happen. For example, the contract can    
+/// choose to keep the assets or return them to the original linkdrop creator. 
+///
+/// Requirements 
+/// * The predecessor account *MUST* be the current contract ID.
+/// * The assets being sent *MUST* be associated with the signer’s public key.
+/// * The assets *MUST* be sent to the `new_account_id` passed in.
+/// * The newly created account *MUST* have a new access key added to its account (either       
+///   full or limited access) in the same receipt that the account was created in. 
+/// 
+/// Arguments
+/// * `new_account_id`: the valid NEAR account which is being created and should 
+///   receive the linkdrop assets
+/// * `new_public_key`: the valid public key that should be used for the access key added to         
+/// The Public key must be in a binary format with base58 string serialization with human-readable curve. The key types currently supported are secp256k1 and ed25519. Ed25519 public keys accepted are 32 bytes and secp256k1 keys are the uncompressed 64 format.
+///   the newly created account.
+function create_account_and_claim(new_account_id: string, new_public_key: string) -> Promise
+```
+
+## Example Scenarios
+
+*Pre-requisite Steps*: Linkdrop creation:
+The linkdrop creator that has an account and some $NEAR:
+
+- creates a keypair locally (`pubKey1`, `privKey1`). (The keypair is not written to chain at this time)
+- calls send on the contract and passes in the pubKey1 as an argument as well as the desired balance for the linkdrop.
+- The contract will map the `pubKey1` to the desired balance for the linkdrop.
+- The contract will then add the `pubKey1` as a function call access key with the ability to call claim and create_account_and_claim. This means that anyone with the `privKey1` that was created locally, can claim this linkdrop.
+- Linkdrop creator will then create a link to send to someone that contains this privKey1. The link may follow the format: wallet.testnet.near.org/linkdrop/{fundingContractAccountId}/{linkdropKeyPairSecretKey}?redirectUrl={redirectUrl}
+`fundingContractAccountId`: The contract accountId that was used to send the funds.
+`linkdropKeyPairSecretKey`: The corresponding secret key to the public key sent to the contract.
+`redirectUrl`: The url that wallet will redirect to after funds are successfully claimed to an existing account. The URL is sent the accountId used to claim the funds as a query param.
+
+### Claiming a linkdrop without a NEAR Account
+
+The receiver of the link that is claiming the linkdrop:
+
+- Receives the link which redirects them to a linkdrop claiming page (such as NEAR wallet).
+- The linkdrop claim page calls `get_key_information` to display information associated with the linkdrop
+- The linkdrop claiming page creates a new keypair (`pubKey2`, `privKey2`) locally. (The keypair is not written to chain at this time)
+- Receiver will then choose an account ID such as alice.near.
+- Wallet will then use the privKey1 which has access to call `claim` and `create_account_and_claim` in order to call `create_account_and_claim` on the contract.
+- It will pass in `pubKey2` which will be used to create a full access key for the new account.
+- The contract will create the new account and transfer the funds to it alongside any NFT or fungible tokens included in the linkdrop.
+
+### Claiming a linkdrop with a NEAR Account
+The receiver of the link that is claiming the linkdrop:
+
+- Receives the link which redirects them to a linkdrop claiming page (such as NEAR wallet).
+- The linkdrop claim page calls `get_key_information` to display information associated with the linkdrop
+- The linkdrop claiming page connects to an existing NEAR Account.
+- Wallet will then use the `privKey1` which has access to call `claim` and `create_account_and_claim` in order to call `claim` on the contract.
+- The contract will transfer the funds to the existing account alongside any NFT or fungible tokens included in the linkdrop.
+
+
+## Reference Implementation
+
+Below are some references for linkdrop contracts. A specific implementation of this standard can be seen in [this pull request](https://github.com/near/near-linkdrop/pull/24).◊
+
+- [Link Drop Contract](https://github.com/near/near-linkdrop)
+
+- [Keypom Contract](https://github.com/keypom/keypom)
+
+
+## Security Implications
+
+1. Linkdrop Creation
+Linkdrop creation involves creating keypairs associated with mapping to assets such as $NEAR, FTs, NFTs and access keys. There are security implications with the access keys associated with the keypairs. These access keys should be function call access keys and be limited to specific functionality. For example, keypairs can be generated with function call access keys which have permission to only call `claim` and `create_account_and_claim`. Another important security implication of linkdrop creation is to ensure that only one key is mapped to a set of assets at any given time. Linkdrop creation can happen in real-time or prior to being received. The mass creation of linkdrops involves creating multiple keypairs associated with mapping to assets and access keys. The security implications mentioned above are increased with the mass creation of linkdrops.
+
+2. Linkdrop Key Management  
+Key management is a critical saftey component of linkdrops. The linkdrop creator should implement a key management strategy for linkdrop keys upon the receiver claiming the linkdrops assets. For example, one strategy may be to delete the linkdrop keypair in the same block the receiver claims the linkdrop assets, so a single linkdrop cannot be used multiple times. In another example, a linkdrop creator may allow for a linkdrop to be used X number of times, where they could track the number of calls to `claim` or `create_account_and_claim` and delete the keypair after X uses of the linkdrop. It is very important to implement your key management strategy in `claim` and `create_account_and_claim` as opposed to a callback function to ensure the linkdrop keys are not improperly used. Implementing key management in a callback has a security implication of such as 'double-spending' a linkdrop.
+
+## Future possibilities
+
+- Function call data types
+
+- Optional configurations added to KeyInfo which can include multi-usekeys, time-based claiming etc…
+
+- Standard process for how links connect to claim pages (i.e a standardized URL such as an app’s baseUrl/contractId=        [LINKDROP_CONTRACT]&secretKey=[SECRET_KEY]
+
+- Standard for deleting keys and refunding assets.
+
+## Copyright
+[copyright]: #copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).