NEP-452 Linkdrop Standard

neps/nep-0452.md

@@ -0,0 +1,221 @@
+---
+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.
+///
+/// Returns `true` if the claim was successful meaing all assets were sent to the `account_id`.
+function claim(account_id: string) -> Promise<boolean>
+
+
+
+/// 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.
+///
+/// Returns `true` if the claim was successful meaning the `new_account_id` was created and all assets were sent to it.
+function create_account_and_claim(new_account_id: string, new_public_key: string) -> Promise<boolean>
+```
+
+## 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 a method, passing the `pubKey1` and desired $NEAR amount as arguments, to a contract that implements the linkdrop standard.
+- 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` (see above), can sign a transaction on behalf of this contract (signer id set to contract id) with a function call to call one of the mentioned functions to claim the assets.
+
+### Claiming a linkdrop without a NEAR Account
+
+A user with *no* wallet that is claiming the assets associated with the public key:
+
+- generates a new keypair (`pubKey2`, `privKey2`) locally. (The keypair is not written to chain at this time)
+- chooses a new account ID such as benji.near.
+- signs a transaction on behalf of the linkdrop contract (contract is set to signer_id) using `privKey1`. The method will be `create_account_and_claim`.
+- the args of this function call will contain both `pubKey2` (which will be used to create a full access key for the new account) and the account ID itself.
+- the linkdrop contract will delete the access key associated with `pubKey1` so that it cannot be used again.
+- the linkdrop contract will create the new account and transfer the funds to it alongside any other assets.
+- the user will be able to sign transactions on behalf of the new account using `privKey2`.
+
+### Claiming a linkdrop with a NEAR Account
+
+A user with an *existing* wallet that is claiming the assets associated with the public key:
+
+- signs a transaction on behalf of the linkdrop contract (contract is set to signer_id) using `privKey1`. The method will be `claim`.
+- the args of this function call will simply contain the user's existing account ID.
+- the linkdrop contract will delete the access key associated with `pubKey1` so that it cannot be used again.
+- the linkdrop contract will transfer the funds to that account alongside any other assets.
+
+
+## Reference Implementation
+
+Below are some references for linkdrop contracts.
+
+- [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 safety 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.
+
+3. Asset Refunds & Failed Claims
+Given that linkdrops could contain multiple different assets such as NFTs, or fungible tokens, sending assets might happen across multiple blocks. If the claim was unsuccessful (such as passing in an invalid account ID), it is important to ensure that all state is properly managed and assets are optionally refunded depending on the linkdrop contract's implementation.
+
+## Future possibilities
+
+- Linkdrop creation interface
+
+- Bulk linkdrop management (create, update, claim)
+
+- 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/).