diff --git a/config-typedoc-core.js b/config-typedoc-core.js index cb4fa420..aec1f77c 100644 --- a/config-typedoc-core.js +++ b/config-typedoc-core.js @@ -74,22 +74,22 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); }, items: [ { - to: "docs/next/Concepts/welcome", + to: "docs/2.0/Concepts/welcome", label: "๐Ÿ“– Concepts", position: "left", }, { - to: "docs/next/Tutorials/welcome", + to: "docs/2.0/Tutorials/welcome", label: "๐Ÿ“š Tutorials", position: "left", }, { - to: "docs/next/KeypomV2/welcome", + to: "docs/2.0/KeypomV2/welcome", label: "๐Ÿค– Keypom V2", position: "left", }, { - to: "docs/next/keypom-sdk/welcome", + to: "docs/2.0/keypom-sdk/welcome", label: "๐Ÿ’ป SDK TypeDocs", position: "left", }, @@ -120,15 +120,15 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); items: [ { label: '๐Ÿ“–Concepts', - to: 'docs/next/Concepts/welcome', + to: 'docs/2.0/Concepts/welcome', }, { label: '๐Ÿ“šTutorials', - to: 'docs/next/Tutorials/welcome', + to: 'docs/2.0/Tutorials/welcome', }, { label: "๐Ÿค–Keypom V2", - to: "docs/next/KeypomV2/welcome", + to: "docs/2.0/KeypomV2/welcome", }, ], }, diff --git a/config-typedoc-selector.js b/config-typedoc-selector.js index f9d0e9f9..b9ad909d 100644 --- a/config-typedoc-selector.js +++ b/config-typedoc-selector.js @@ -74,22 +74,22 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); }, items: [ { - to: "docs/next/Concepts/welcome", + to: "docs/2.0/Concepts/welcome", label: "๐Ÿ“– Concepts", position: "left", }, { - to: "docs/next/Tutorials/welcome", + to: "docs/2.0/Tutorials/welcome", label: "๐Ÿ“š Tutorials", position: "left", }, { - to: "docs/next/KeypomV2/welcome", + to: "docs/2.0/KeypomV2/welcome", label: "๐Ÿค– Keypom V2", position: "left", }, { - to: "docs/next/keypom-sdk/welcome", + to: "docs/2.0/keypom-sdk/welcome", label: "๐Ÿ’ป SDK TypeDocs", position: "left", }, @@ -120,15 +120,15 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); items: [ { label: '๐Ÿ“–Concepts', - to: 'docs/next/Concepts/welcome', + to: 'docs/2.0/Concepts/welcome', }, { label: '๐Ÿ“šTutorials', - to: 'docs/next/Tutorials/welcome', + to: 'docs/2.0/Tutorials/welcome', }, { label: "๐Ÿค–Keypom V2", - to: "docs/next/KeypomV2/welcome", + to: "docs/2.0/KeypomV2/welcome", }, ], }, diff --git a/docs/Concepts/KeypomProtocol/Assets/asset-types.md b/docs/Concepts/KeypomProtocol/Assets/asset-types.md new file mode 100644 index 00000000..3e134a31 --- /dev/null +++ b/docs/Concepts/KeypomProtocol/Assets/asset-types.md @@ -0,0 +1,72 @@ +--- +sidebar_label: 'Asset Types' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; + +# Asset Types +## Basics + + +In the Keypom Protocol, an asset is something that is attached to every key in your drop. When someone obtains and uses a key, they will receive the assets - either to a new or existing account. + + +Assets are meant to create new experience and bring value to your users. There can be any number of mixed and matched assets for each key use. Assets can take on the following types: + +* **NEAR** +* **Fungible Tokens** +* **Non-Fungible Tokens** +* **Function Calls** + +Each key in a drop holds the same assets, meaning a user can receive any key from the drop and be guarenteed the same set of assets. + +Access Keys can have multiple uses and their assets are defined **per use**. These can be mix-and-matched to craft any experience you want. An example can be seen below: + + + + +| **Key Use** | **Assets** | +|-------------|-----------------------------------| +| 1 | NEAR, FunctionCall, Fungible Token| +| 2 | Non-Fungible Token | +| 3 | Fungible Token, NEAR | + + +This means when the user claims their key for the first time, they will receive some FTs, some NEAR and call a set of functions. On the second claim, they will receive an NFT while on the third and final claim, they will receive some NEAR and FTs. + +New with Keypom V3, you can mix-and-match and add multiple different types of assets per use, for as many key uses/claims as you want! + +
+
+
+ +
+
+

NEAR, NFT, & FT Assets

+

Add value to your drop using tokens!

+
+
+ +
+
+ +
+
+

Function Call Assets

+

Call any NEAR smart contract

+
+
+ +
+
+
+ +___ + +## Defining vs Funding Assets +An important distinction to be made is the difference between defining and funding assets. Defining an asset is similar to creating a blueprint for your drop while funding is the process of building it. + +:::caution +If assets are not properly funded, your drop may not perform as expected. Proper funding is formally defined in [next section](basic-assets.md). +::: \ No newline at end of file diff --git a/docs/Concepts/KeypomProtocol/Assets/basic-assets.md b/docs/Concepts/KeypomProtocol/Assets/basic-assets.md new file mode 100644 index 00000000..d76a182d --- /dev/null +++ b/docs/Concepts/KeypomProtocol/Assets/basic-assets.md @@ -0,0 +1,150 @@ +--- +sidebar_label: 'NEAR, NFT, & FT Assets' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; + +# NEAR, NFT, & FT Assets + +For every use on a Key, the different types of assets can be mixed to create an infinite number of experiences! + + +## Defining vs Funding Assets +An important distinction to be made is the difference between defining and funding assets. Defining an asset is similar to creating a blueprint for your drop while funding is the process of building it. + +* ***Defining an Asset***: The process of creating a drop and outlining the behaviour expected for your keys. At this point, you've created a blueprint of your drop's expected assets but have not built it out. + +* ***Funding an Asset***: Transferring ownership of defined assets to Keypom so that they can be redeemed by users claiming your keys. + +Once a drop's assets have been defined and funded, keys can be used properly. + +:::caution +If assets are not properly funded, users of your drop will not receive the assets promised to them. +::: +___ + +## NEAR Asset +> A NEAR Asset attaches some NEAR that will be deposited in the user's account when claiming + +Whenever a NEAR asset is present in a key use, the user will receive some NEAR for that particular key use. For example, if a key has 2 uses, and a NEAR asset is defined in the first use but not the second, then the user will only receive NEAR the first time they claim their key. + +### Structure +The structure of a NEAR asset is relatively simple. All that needs to be defined is the amount. Note that if multiple NEAR assets are defined in the same use, the claiming user will receive the sum of `yoctonear` contained in all the NEAR assets. + + + +```rust reference +https://github.com/keypom/keypom/blob/8f9f8df397cb8cabbda30d1ddffdcddc4a733274/contract/src/models/external/models.rs#L30-L33 +``` + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/e8c43f4219a79afb3c367296cc90b8d5de977945/src/lib/types/fc.ts#L68-L74 +``` + + + + +### Funding +In the case of NEAR assets, defining and funding are synonomous. This is because the drop creation will fail if insufficient NEAR is provided. This NEAR can come from: + +* Your [Keypom Balance](../balances.md). +* An [attached deposit](https://docs.near.org/develop/contracts/environment/#environment-variables) when creating the drop. + +___ + +## NFT Asset +> A properly funded NFT Asset will allow a user to receive a Non-fungible Token when claiming + +Whenever an NFT asset is present and properly funded in a key use, the user will receive an NFT for that particular key use. For example, if a key has 2 uses, and an NFT asset is defined in the first use but not the second, then the user will only receive an NFT the first time they claim their key. + +Note that multiple different tokens can be sent at once by defining additional NFT Assets following the structure below. +### Structure +When defining an NFT Asset, only one item needs to be specified: +* `nft_contract_id`: the contract that the NFT lives on. + + + + +```rust reference +https://github.com/keypom/keypom/blob/8f9f8df397cb8cabbda30d1ddffdcddc4a733274/contract/src/models/external/models.rs#L50-L53 +``` + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/e8c43f4219a79afb3c367296cc90b8d5de977945/src/lib/types/fc.ts#L68-L74 +``` + + + + +### Funding +:::caution +An improperly loaded NFT Asset will result in **no NFT being sent to the user** +::: + +In order to fund an NFT asset, you must transfer it to the Keypom contract: `v3.keypom.near` or `v3.keypom.testnet`. By doing this, you give the Keypom contract the ability to transfer it to the end user when they claim. + +It is important that when transferring, you are transferring from the contract that you defined above. It is also important to include the `dropId` as a `msg`. This tells Keypom to associate the incoming NFT with your drop. +```js reference +https://github.com/keypom/keypom/blob/b5ee9ddde16cc604fea2da83c6368e2ea3461b81/__tests__/creation/nft-creation.ava.ts#L189-L199 +``` +In the case where you have multiple NFT Assets, you will need to transfer the appropriate number of NFTs. For example, if you have 5 keys with 2 NFT Assets each, you will need to transfer 10 NFTs to Keypom. + +When claiming, the user will receive the lastest NFT that was transferred to Keypom. + +:::note +Only a drop's creator can fund its NFT Assets +::: +___ + +## FT Asset +> A properly funded FT Asset will send the claiming user a predetermined amount of Fungible Tokens + +Whenever an FT asset is present and properly funded in a key use, the user will receive a set amount of FTs for that particular key use. For example, if a key has 2 uses, and an FT asset is defined in the first use but not the second, then the user will only receive an the predefined amount of FTs the first time they claim their key. + +Note that multiple different tokens can be sent at once by defining additional NFT Assets following the structure below. +### Structure +When defining an FT Asset, a few things need to be defined: +* *ft_contract_id*: The Fungible Token contract. +* *ft_amount*: The amout of Fungible Tokens to be sent. Defined in the smallest divisible unit. For more, see the token's definition of the [decimal value](https://docs.openzeppelin.com/contracts/3.x/erc20#a-note-on-decimals). +* *registration_cost*: Specific to each FT contract, this is the cost to register the user on the FT contract. + + + + +```rust reference +https://github.com/keypom/keypom/blob/8a4009be98f263e93d718779983efcdac1b1a9f8/contract/src/models/external/models.rs#L38-L45 +``` + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/e8c43f4219a79afb3c367296cc90b8d5de977945/src/lib/types/fc.ts#L68-L74 +``` + + + + + +### Funding +:::caution +An improperly loaded FT Asset will result in **no FTs being sent to the user** +::: + +In order to fund a Fungible Token asset, you must transfer it to the Keypom contract: `v3.keypom.near` or `v3.keypom.testnet`. By doing this, you give the Keypom contract the FT balance necessary to transfer it to the end user when they claim. + +It is important that when transferring, you are transferring from the contract that you defined above. It is also important to include the `dropId` as a `msg`. This tells Keypom to associate the incoming NFT with your drop. +```js reference +https://github.com/keypom/keypom/blob/b5ee9ddde16cc604fea2da83c6368e2ea3461b81/__tests__/utils/ft-utils.ts#L17-L28 +``` +:::note +Anybody can fund a drop's FT Assets +::: +___ \ No newline at end of file diff --git a/docs/Concepts/KeypomProtocol/Assets/function-call.md b/docs/Concepts/KeypomProtocol/Assets/function-call.md new file mode 100644 index 00000000..e74917ba --- /dev/null +++ b/docs/Concepts/KeypomProtocol/Assets/function-call.md @@ -0,0 +1,208 @@ +--- +sidebar_label: 'Function Call Asset' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; + +# Function Call Asset + + +For every use on a Key, the different types of assets can be mixed to create an infinite number of experiences! + + +The Function Call asset allows almost **any** method on **any** contract to be executed when claiming. + +These Function Calls can be used for utility, such as NFT ticketing and auto-regtration into DAOs or can carry value such as lazy minting NFTs. Combined with the ability to define function call arguments dynamically based on user input, the FC asset becomes the most versatile and expansive Keypom asset type. + + +## How does it work? + +When an a key use containing a Function Call asset is claimed, Keypom will make the predetermined function call. This call works as any normal function call and has a preset receiver, method, and attached deposit. Beyond these predefined aspects, Function Call assets can also include dynamically defined arguments such as user inputs, and immutable Keypom basis-of-truth arguments. + + +## Structure + +A Function Call Asset is defined by a **vector of function calls** with each call being represented by a `MethodData` object. Since a Function Call asset is defined with a vector of `MethodData`, multiple function calls can be made in a single key use. + +The `MethodData` object outlines the following: + +* `receiver_id`: The contract on the receiving end of the function call. +* `method_name`: The desired method to be called. +* `args`: Arguments to be included in the function call, JSON stringified. +* `attached_deposit`: Amount of yoctoNEAR to attach to the function call. +* `attached_gas`: Amount of gas for this method +* `keypom_args`: Immutable Keypom populated basis-of-truth arguments, you specify the location and Keypom will inject certain values into these JSON locations within `args`. These cannot be spoofed, for more info see [below](#keypom-arguments) +* `receiver_to_claimer`: Boolean that allows the claimer to become the receiver +* `user_args_rule`: Rules outlining the behaviour of user inputs and predefined `args` when claiming. + + + + + +```rust reference +https://github.com/keypom/keypom/blob/8f9f8df397cb8cabbda30d1ddffdcddc4a733274/contract/src/assets/function_call/models.rs#L6-L26 +``` + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/e8c43f4219a79afb3c367296cc90b8d5de977945/src/lib/types/fc.ts#L68-L74 +``` + + + + +## Execution + +For **every Function Call Asset**, you can specify a *vector* of `MethodData` which allows you to execute multiple function calls for each asset. These calls are scheduled 1 by 1 using a simple for loop. This means that most of the time, the function calls will be executed in the order specified in the vector but it is not *guaranteed*. + +## Injecting Keypom Arguments +> Automatically injected immutable arguments acting as sources of truth + +Injected Keypom Arguments are arguments that are automatically populated into a function call's outgoing arguments. These arguments are immutable and cannot be spoofed, meaning they allow receiving contracts to use them as a source of truth for certain pieces of information. The following arguments can be injected automatically by Keypom: + +* **Claiming Account ID**: This is the account ID that is claiming that particular key use. +* **Drop ID**: This is a unique identifier for each drop. +* **Drop Funder Account ID**: The account ID of the account that created the drop, this can be useful for ensuring only trusted users can trigger certain behaviours in your receiving contract +* **Key ID**: Each key in a drop is identified with an integer key ID. This is **unique in to that specific drop** but not accross multiple different drops. + +Prior to function execution, the Keypom contract will **automatically** modify the outgoing arguments according to the defined `keypom_args`. The desired location for these arguments to be injected can be specified using the following data structure. +:::note +Keypom Arguments target locations must be specified at drop creation and cannot be changed. +::: + +```rust reference +https://github.com/keypom/keypom/blob/8f9f8df397cb8cabbda30d1ddffdcddc4a733274/contract/src/assets/function_call/models.rs#L32-L45 +``` + +For example, if the `account_id_field` is set to `"claiming_account"`, then Keypom will inject the claiming account's IDs into the `claiming_account` field in the args. + +Arguments can be injected into nested fields by using object dot notation; `funder_id_field: "creator.account_id"` will inject the drop funder's account ID into the `creator` object under the field `account_id`. If specified fields do not exist, Keypom will create them. Attempting to nest into a non-object will cause the drop creation to fail. + +### Protect your Receiving Contracts with Keypom Args +Take the perspective of the receiver contract form the previous examples. If you expect a certain funder account ID under the `creator` field, how do you know that this value has actually been injected by Keypom and not maliciously hardcoded? That is, how can you know that somebody else didn't create a malicious drop and hardcode the `creator` field to the expected value? + +Here, `keypom_args` comes in handy. When a key is used and a function is called, a seperate data structure is **automatically** attached to the arguments, known as the `keypom_args`. This object contains informs the receiver contract of the arguments that have been automatically injected and the location in which they were injected. This is information that the drop creator specified in the `MethodData.keypom_args` during drop creation. + +This additional data structure allows receiving contracts to protect themselves from malicious calls by ensuring that critical pieces of information are correct. For example, if a contract + +* Knows that the field `claiming_account_id` should contain information automatically injected by Keypom +* Only wants to work with drops from a particular funder `moon.near` + +They can leverage the `keypom_args` in the following manner. + +To ensure that `claiming_account_id` is being injected by Keypom rather than hardcoded, the receiving contract can check that `keypom_args.account_id_field` is set to `claiming_account_id`. Since Keypom injected arguments cannot be overriden, you know with 100% certainty that whatever value you read in the `claiming_account_id` has been injected by Keypom. + +To make sure that all claims come from a drop funded by `moon.near`, a similar strategy can be employed but this time while also checking the value. The drop can first inject the funder's account ID using `keypom_args` into any arbitrary field such as `creator`. The receiver contract can then check the value `creator` is `moon.near`, **and** check that `keypom_args.funder_id_field` is set to `creator`. If both checks pass, you know with 100% certainty that Keypom populated the `creator` field and that the drop funder was `moon.near` + +:::info +The receiver contract's validation of injected arguments per the examples given above looks like this + +```rust +#[payable] +pub fn myFunction(&mut self, mint_id: String, claiming_account_id: String, drop_funder: data, keypomArgs: keypom_args) -> Promise { + // If the function call is coming from Keypom, validate arguments + if(env::predecessor_account_id() == "v3.keypom.near"){ + //Ensure claiming_account_id was not hardcoded + assert!(keypomArgs.account_id_field == "claiming_account_id", "Call must come from valid Keypom drop"); + + // Ensure drop_funder is moon.near AND is not hardcoded + assert!(drop_funder == "moon.near" && keypomArgs.funder_id_field == "drop_funder", "Call must come from valid Keypom drop"); + } + ... +} +``` +::: + + +## Prohibited Methods + +Since all function calls will be signed by the Keypom contract, there are a few restrictions in place to avoid malicious behaviors. +To avoid users from stealing registered assets from other assets, the following methods cannot be called via FC assets: + +```rust reference +https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/lib.rs#L926-L934 +``` + +In addition, the Keypom contract cannot be the receiver of any function call. This is to avoid people +from calling private methods through FC assets. + +## Use Cases + +Function call assets are the bread and butter of the Keypom contract. They are the most powerful and complex assets that can currently be created. +With this complexity, there are an almost infinite number of use-cases that arise. + +### Proof of Attendance Protocols [โžœ](../../../Cookbook/drops/fc.md#attaching-nfts-to-your-fc-drop) + +A very common use case in the space is what's known as Proof of Attendance. Often times when people go to events, they want a way to prove +that they were there. Some traditional approaches would be to submit your wallet address and you would be sent an NFT or some other form of +proof at a later date. The problem with this is that it has a very high barrier to entry. Not everyone has a wallet. + +With Keypom, you can create a function call drop that allows people to onboard onto NEAR if they don't have a wallet or if they do, they can +simply use that. As part of the onboarding / claiming process, they would receive some sort of proof of attendance such as an NFT. This can +be lazy minted on-demand such that storage isn't paid up-front for all the tokens. + +At this point, the event organizers or the funder can distribute links to people that attend the event in-person. These links would then be +claimed by users and they would receive the proof of attendance. + +### Auto Registration into DAOs [โžœ](../../../Tutorials/Advanced/daos/introduction.md) + +DAOs are a raging topic in crypto. The problem with DAOs, however, is there is a barrier to entry for users that aren't familiar with the +specific chain they're built on top of. Users might not have wallets or understand how to interact with contracts. On the contrary, they +might be very well versed or immersed in the DAO's topics. They shouldn't be required to create a wallet and learn the onboarding process. + +With Keypom, you can create a function call drop with the main purpose of registering users into a DAO. For people that have a wallet, +this will act as an easy way of registering them with the click of a link. For users that don't have a wallet and are unfamiliar with +NEAR, they can be onboarded and registered into the DAO with the same click of a link. + +### Multisig Contracts + +Another amazing use-case for Keypom is allowing multisig contracts to have ZERO barrier to entry. Often times when using a multisig contract, +you will entrust a key to a trusted party. This party might have no idea what NEAR is or how to interact with your contract. With Keypom, +you can create a drop that will allow them to sign their transaction with a click of a link. No NEAR wallet is needed and no knowledge of the +chain is required. + +At the end of the day, from the users perspective, they are given a link and when they click it, their portion of the multisig transaction is +signed. The action is only performed on the multisig contract once all links have been clicked. This is an extremely powerful way of doing +accomplishing multisig transactions with zero barrier to entry. + +The users don't even need to create a new account. They can simply call `claim` when the link is clicked which will fire the cross-contract call +to the multisig contract and pass in the keypom arguments that will be cross-checked by that contract. + +### NFT Ticketing [โžœ](../../../Tutorials/Advanced/ticketing/introduction.md) + +The problem with current NFT ticketing systems is that they require users to have a wallet. This is a huge barrier to entry for people that +are attending events but don't have wallets. In addition, there is often no proof of attendance for the event as the NFT is burned in order +to get into the event which requires an internet connection. + +Keypom aims to solve these problems by having a ticketing system that has the following features. +* Users are not required to have a wallet to enter the event. +* Each ticket is unique and can only be used by one person. +* Attendees are not required to have wifi to gain entry to the event. +* Attendees that did not have a NEAR wallet can get one for free. +* Attendees can choose to receive an NFT proving their attendance at the event. This is commonly known as a [POAP](https://academy.binance.com/en/glossary/proof-of-attendance-protocol-poap). + +In addition, some way to provide analytics to event organizers that contains information such as links that were: +- Given out but not clicked at all. +- Clicked but not attended. +- Partially claimed indicating the number of people that attended but did not onboard or receive a POAP. +- Fully claimed indicating the number of people that attended and received a POAP. + +In order to accomplish this, you can create a drop that has 3 uses per key. These uses would be: +1. Array(`null`) +2. Array(`null`) +3. Array(function call to POAP contract to lazy mint an NFT) + +The event organizer would create the links and distribute them to people however they see fit. When a user receives the link, the first +claim is automatically fired. This is a `null` case so nothing happens except for the fact that the key uses are decremented. At this point, +the organizer knows that the user has clicked the link since the uses have been decremented. + +The next claim happens **only** when the user is at the door. Keypom would expose a QR code that can only be scanned by the host's phone. +This QR code would appear once the first link is clicked and contains the private key for the link. At the event, they wouldn't need any wifi +to get in as they only need to show the host the QR code. Once the host scans it, the site would ensure that they have exactly 2 out of +the 3 uses left. If they don't, they're not let in. At that point, a use is decremented from the key and the next time they visit the +ticket page (when they have internet), they would be able to claim the final use and be onboarded / receive a POAP. + +

ticketing

\ No newline at end of file diff --git a/docs/Concepts/KeypomProtocol/Assets/key-use-configurations.md b/docs/Concepts/KeypomProtocol/Assets/key-use-configurations.md new file mode 100644 index 00000000..afa3cdc2 --- /dev/null +++ b/docs/Concepts/KeypomProtocol/Assets/key-use-configurations.md @@ -0,0 +1,79 @@ +--- +sidebar_label: 'Key Use Configurations' +--- +import Admonition from '@theme/Admonition'; + +# Key Use Configurations + +> For each set of key uses in your drop, different behaviours can be defined to create unique experiences! + +:::info +These configurations apply to a set of key uses, for global configurations see [drop configurations](../drop-configurations.md) +::: + +# What are Key Use Configurations? +Key use configuration defines the expected behaviour for a particular key use in the following aspects: + +* [**Time Configuration**](#time-configuration): Umbrella configuration for all things related to timing, such as claim periods and intervals +* [**Claiming Permissions**](#claiming-permissions): Can/must a new account be created when claiming? +* [**Root Account ID**](#root-account-id): Should accounts created be subaccounts of a particular account? +* [**Account Creation Arguments**](#account-creation-arguments): Upon account creation, what information should Keypom send to the root account? + +The specification for key use configurations can be seen below: + +```rust reference +https://github.com/keypom/keypom/blob/8f9f8df397cb8cabbda30d1ddffdcddc4a733274/contract/src/models/config.rs#L16-L31 +``` +___ + +## Root Account ID +*Default: `near` or `testnet`* + +The `root_account_id` parameter determines which account the newly-created claiming account will be a sub-account of. For example, the default is `near` so all accounts would end in `.near` such as `benji.near`. Changing the `root_account_id` parameter will change the root of all the accounts that users create through `create_account_and_claim` when using your drop. + +### Use cases +Let's say you have an organization called Moonpom (secretly run by our beloved Pomeranian, Moon) and you want your users want to proudly represent Moonpom! + +You set `root_account_id = "moonpom.near"` and now any account created using your linkdrops will take on the form `${YOUR_USERNAME}.moonpom.near` + +:::caution Important +the `root_account_id` **must** have a contract deployed to it that exposes a method `create_account` to create the sub-account. A sample contract can be found [here](https://github.com/near/near-linkdrop/blob/49279e529c254fa7736465b4a39d05cb8f1e5443/src/lib.rs#L130) +::: + +___ + + +## Claiming Permissions +*Default: `claim` AND `create_account_and_claim`* + +The `permissions` parameter assigns which claim methods the user can call with the key you give them. They can either call both, or just one. + +### Use case +Pretend you are hosting a talk about your NEAR dApp: `Kramerly`. Your only goal is to onboard as many *new* users from the audience as possible. If the user already has a NEAR wallet, they shouldn't be able to claim assets and onboard. This is similar to free-trials in Web2 whereby only new users are able to participate. + +To do this, you can set the `permissions` parameter to `create_account_and_claim`. + +___ + +## Account Creation Arguments +*Default: `null`* + +`account_creation_keypom_args` specifies where certain Keypom arguments should be automatically injected by Keypom upon calling `create_account_and_claim`. This should be used when specifying a custom `root_account_id`, where you have control over the exposed `create_account` method. + +Similar to function call [`keypom_args`](function-call.md#injecting-keypom-arguments), these arguments are immutable and can only be inserted by Keypom. This means that they can be used to validate incoming `create_account_and_claim` calls and prevent malicious attacks against your `root_account` contract. +### Use Case +At NEARCON 2023, attendees used their Keypom keys as their tickets, and create4d accounts with a starting Fungible Token balance ($NCON) to participate in the on-the-ground economy. To do this, their keys called the NEARCON contract's exposed `create_account` method that instantiates a new account with a given starting $NCON balance. + +Say a malicious actor, EvilMoon, wishes to collect $NCON to buy delicious treats. His plan is to create a drop to fraudulently create accounts using the NEARCON contract's exposed `create_account` method without a NEARCON ticket and then sending all the $NCON to himself. + +In order to differentiate the official NEARCON tickets from EvilMoon's malicious drop, the NEARCON contract can leverage `account_creation_keypom_args` to receive the `dropId`, and compare it to the expected `dropId` of the official NEARCON tickets. + +```rust reference +https://github.com/keypom/nearcon-account-factory/blob/d4b0db55b02c37d574f194d91ddd4c5f2bb26576/contract/src/factory.rs#L28-L29 +``` + +--- + +## Time Configuration +### What is it? +Time configurations dictate when and how frequently a key can be claimed. A deep dive on these configurations can be found in the [Time Configurations section](./time-customization.md). diff --git a/docs/Concepts/KeypomProtocol/Assets/time-customization.md b/docs/Concepts/KeypomProtocol/Assets/time-customization.md new file mode 100644 index 00000000..64f238f3 --- /dev/null +++ b/docs/Concepts/KeypomProtocol/Assets/time-customization.md @@ -0,0 +1,110 @@ +--- +sidebar_label: 'Time Configurations' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Time Configurations +Time configurations are particularly useful in defining limits on ***when*** a key may be used. This can have a wide range of applications from [Subscriptions](../../../Tutorials/Advanced/subscriptions/introduction.md) to [Ticketing](../../../Tutorials/Advanced/ticketing/introduction.md). + + + + +```rust reference +https://github.com/keypom/keypom/blob/8f9f8df397cb8cabbda30d1ddffdcddc4a733274/contract/src/models/config.rs#L35-L54 +``` + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/29c10f949f02f673d4a3cecc21b0f74bca600075/src/lib/types/drops.ts#L87-L112 +``` + + + + +:::tip +All these time parameters are measured in non-leap-nanoseconds and can be tricky to work with. An example struct has been provided [below](#example-time-configuration). +::: + + +--- + +## Start +*Default: none, Keys can be used anytime* + +`Start` time is useful for any drops where you intend to restrict access until a certain time. Setting a `start` time effectively sets an activation time; a time where the keys become usable afterwards. Before a `start` time is reached, if a user tries to `claim` the key or use `create_account_and_claim`, it will not work. + +### Use case +Let's say you are running a concert, and you want to give fans exclusive access using preferred and general admission tickets. Those with preferred admission tickets can enter anytime, even when the band is setting up. General admission, on the other hand, may only enter once the band is set up. + +In this case, you would hand out general admission tickets with a start time in the time configurations and another set of preferred admission tickets with an earlier start time in the time configurations. + +To do this, you would need to create two drops, one for preferred admission and another for general admission. This is because, as covered in the [Drop Configurations Introduction](../GithubReadme/TypesOfDrops/customization-homepage.md), one set of configurations will apply to **all** keys in that drop. + +--- + +## End +*Default: none, Keys can be used anytime* + +The end parameter acts as a deactivation time. This means that once the end time is reached, all the keys in the drop will be deactivated and can no longer be used. + +### Use case +Let's pretend that you are at NEARCON representing an NFT marketplace looking to onboard users onto your platform. Your strategy is to offer an exclusive NFT to users that sign up during NEARCON. + +To do this, you hand out QR codes with an NFT drop embedded in the QR code during the event. To ensure that the users sign up *during* NEARCON, you set the drop configuration's `end` parameter to be the end of NEARCON. + +--- + +## Throttle +*Default: none, Keys can be used anytime* + +The `throttle` parameter controls how much time must pass between key uses. This works great if you want to control how frequently somebody is able to claim their assets. + +### Use case +Pretend you are running an NFT raffle for your latest creation, the MoonNFT. For this raffle, the 20th person claiming their key will be the winner and will receive their own personalized MoonNFT. + +To protect again spam and ensure a fair playing field, you can configure the drop to have a 5 minute cooldown using the `throttle` parameter. This way, a contestant cannot spam claim the key to increase their odds of winning. + +--- + +## Interval +*Default: none, Keys can be used anytime* + +The `interval` parameter is similar to the `throttle` parameter but uses the `start` time as a constant reference. This means if `interval` is every week, the key will become useable on the same day every week, regardless of when the last key use was. + +### Use case +Pretend you have a subscription to Moon's **weekly** dog biscuit delivery service that charges you every Monday. Due to all the horror stories of data breaches and identity theft, you now no longer give out your credit card information. For this reason, you wish to pay with $NEAR but the current linkdrop standard does not allow for a subscription model. + +With Keypom, you can give Moon a multi-use simple drop with a `throttle` parameter set to 2 weeks. This way, Moon will only be able to claim every week, making it a subscription. This is also beneficial in giving a sense of security to Moon, as they can claim later than Monday and know that they will be able to claim again next Monday. + +If, for one week, Moon forgets to claim, he would be able to claim twice the next week. + + +The massive benefit here is that you can have a subscription service in the NEAR ecosystem and never need to expose any of your private information. + + +--- + +## Example Time Configuration + +```ts +const ONE_SECOND_NS = 1e9; + +time: { + // Start time is 30 seconds from now + start: (Date.now() * 1000000) + ONE_SECOND_NS * 30, + + // End time is 5 minutes from start time + end: (Date.now() * 1000000) + ONE_SECOND_NS * 330, + + // Time between use is 15 seconds + throttle: ONE_SECOND_NS * 15, + + // Time after start for first use is 15 seconds + interval: ONE_SECOND_NS * 15, +} +``` + + diff --git a/docs/Concepts/KeypomProtocol/drop-configurations.md b/docs/Concepts/KeypomProtocol/drop-configurations.md new file mode 100644 index 00000000..a62b5f37 --- /dev/null +++ b/docs/Concepts/KeypomProtocol/drop-configurations.md @@ -0,0 +1,146 @@ +--- +sidebar_label: Drop Configurations +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; + +# Drop Configurations + +> Drop configurations are ways you can customize your drops **globally**. This means they apply to the entire drop, for all keys and key uses + +:::info +These configurations apply to your entire drop. For more granular configurations see [key use configurations](./Assets/key-use-configurations) +::: + +# What are Drop Configurations? +Drop configuration define the expected behaviour for an entire drop in the following aspects: + +* [**Add Key Allowlist**](#add-key-allowlist): Allow others to add keys to your drop, useful for selling tickets. +* [**NFT Key Configuration**](#nft-key-configuration): Customize NFTs associated with your access keys. +* [**Delete Empty Drop**](#delete-empty-drop): What happens when all the keys in your drop are used? +* [**Drop Metadata**](#drop-metadata): Drop specific information +* [**Extra Key Allowance**](#extra-key-allowance): The amount of extra key allowance to be added to dynamically calculated allowance. + +Below is the structure of the drop configuration struct, `DropConfig`: + +```rust reference +https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/models/config.rs#L59-L78 +``` + +___ + +## Add Key Allowlist +> *Default: null* + +`add_key_allowlist` is a vector of account IDs that controls which accounts have permissions to add keys to drop using the [`add_keys`](https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/drop_creation/add_keys.rs#L6) method. + +:::caution +Note that this ***must*** be defined at the time of *drop creation* and cannot be modified once the drop has been created. +::: + +### Use Case +Whilst linking NFTs with Access Keys has helped open up a secondary market for Access Keys, `add_key_allowlist` enables you to create a primary market. This was the technique leveraged to sell NEARCON 2023 tickets! + +

+ ticketing +

+ + +To do this, you can allow a primary market, in this case [Veriken](https://nearcon2023.veriken.app/), to add keys to your NEARCON drop using `add_key_allowlist`. Then, once Veriken handles and confirms the customer's payment, they simply call `add_keys` for each ticket purchased and then distribute the ticket to the customer. +___ + +## NFT Key Configuration +> *Default: [Keypom NFT](https://www.mintbase.xyz/meta/ncon23.keypom.near%3A46d3371766753c9d1a29e2b486438c7c) with metadata defined [here](https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/nft_keys/metadata.rs#L73-L81) and null royalties* + +Every access key in your drop is linked with an NFT, opening up the possibility of buying, selling and trading access keys using [NFT standards](https://nomicon.io/Standards/Tokens/NonFungibleToken) methods such as `nft_transfer` and `nft_approve`. This NFT contains metadata and royalties defined in the `NFTKeyConfigurations` object at time of drop creation. + +```rust reference +https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/nft_keys/metadata.rs#L45-L51 +``` + +:::caution +NFT Key Configurations can only be specified at drop creation, and cannot be changed after that. +::: + +This NFT metadata follows the definition specified in the NFT Metadata standard ([NEP-177](https://nomicon.io/Standards/Tokens/NonFungibleToken/Metadata)). + +```rust reference +https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/nft_keys/metadata.rs#L15-L22 +``` + +### Use Case +Suppose Benji is hosting his own conference known as BenjiCON. He wishes to create a seamless ticketing experience for his guests and chooses Keypom accordingly. When listing tickets on trusted secondary marketplaces such as Mintbase, he wants them to be represented by NFTs depicting him holding Moon. He also wishes to send 30% of all proceeds from secondary ticket sales to his beloved pomeranian Moon. + +To do this, he initializes a drop, whith the following `NFTKeyConfigurations`. + +```javascript +myNFTKeyConfig = { + token_metadata: { + title: "BenjiCON 2024", + description: 'Welcome to BenjiCON!', + media: '${IPFS link of image of Benjis face}', + media_hash: undefined, + . + . + reference_hash: undefined + }, + royalties: { + moon: 3000 + originalOwner: 7000 + } +} +``` + +:::note +Royalties are expressed as integers out of 10,000 +::: + +___ + +## Delete Empty Drop +> *Default: True, empty drops will automatically be deleted* + +This configuration specifies whether or not drops that have depleted all their keys should be deleted or not. By default, they will be deleted. + +### Use Case +Moon is running his annual MoonCON conference and chooses to use Keypom access keys linked with NFTs to represent tickets. Tickets can be bought at the door and only have 1 key use that is used to enter the conference. + +In this scenario, since Moon does not know how many people will attend the event, he chooses to set `delete_empty_drop` to false. This way, if he has 5 tickets and they end up being used right away, a 6th person buying a ticket at the event can still do so using the same drop. + +:::note +Drops can only be deleted by calling `delete_keys` and deleting all the keys. That is, creating a drop with 0 keys will **not** result in the drop being deleted right away. To delete an empty drop, simply call `delete_keys` with the empty drop's `drop_id` +::: + +___ + +## Extra Key Allowance +> *Default: 0* + +An extra amount of NEAR to be added to an access key's allowance. This will give the key extra gas for all of its claims, as well as other function calls such as `nft_transfer`, and `nft_approve`. + +### Use Case +Moon recognizes that his annual MoonCON conference is very popular, and that there is the potential for a hot resale market. In order to allow plenty of activity on the secondary markets such as Mintbase, Moon adds some extra allowance to each key. This allows the key to call `nft_approve` and `nft_transfer` multiple times without running out of NEAR of gas when it comes time to use the ticket and claim the assets. +```rust +// 30TGas extra +extra_allowance_per_key: 30000000000000 +``` + +___ + +## Drop Metadata +> *Default: null* + +`drop_metadata` is a string that allows you to store any other information you wish to associate with the drop, such as the drop's purpose. For the sake of clarity and interoperability with frontends, this is typically a stringified JSON. + +### Use case +Benji is going on a Lunch 'n' Learn tour with Moon, with ticket sales planned for every city. To facilitate a seamless experience for attendees, Benji creates a frontend hosted on BOS to sell tickets to each one of cities. In order to keep track of tickets for each city, Benji creates a number of drops, each with their own unique metadata describing the Lunch 'n Learn location and time. On the frontend, Benji can simply call `get_drop_information`, parse the returned metadata for each drop, and then render each city's ticket page according to the metadata. +```javascript +drop_metadata: JSON.stringify({ + city: "Toronto", + data: "June 13th 2024", + time: "1pm EST" +}) +``` +___ + diff --git a/docs/Concepts/KeypomProtocol/drop.md b/docs/Concepts/KeypomProtocol/drop.md new file mode 100644 index 00000000..35b6367d --- /dev/null +++ b/docs/Concepts/KeypomProtocol/drop.md @@ -0,0 +1,86 @@ +--- +sidebar_label: 'The Keypom Drop' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; + +# The Keypom Drop +> A Keypom Drop is a collection of access keys that all share the same traits - such as assets and configurations. . + +* ***Access Key***: A NEAR keypair, this is what each user receives to start their Keypom experience. + * Can have assets, such an NFT, FTs, NEAR or FunctionCalls, associated with them. + * When a user receives a key and claims it, they will receive those assets. +* ***Drop***: A collection of access keys that all share the same traits - such as assets and configurations. + * As a funder, you create the drop and fund all the assets + * You can add as many keys as you want to the drop, even after its creation. + +An easy way to think about it is that you *create a drop* but you *distrubute keys*. + +___ + +## What are Assets? +> In the Keypom Protocol, an asset it something you attach to every key in your drop. When someone obtains and uses a key, they will receive the assets - either to a new or existing account. + +Assets can be NEAR, Fungible Tokens, Non-Fungible Tokens, or FunctionCalls. Each key in a drop holds the same assets, meaning a user can receive any key from the drop and be guarenteed the same set of assets. + +Access Keys can have multiple uses and their assets are defined **per use**. These can be mix-and-matched to craft any experience you want. An example can be seen below: + + +| **Key Use** | **Assets** | +|-------------|-----------------------------------| +| 1 | NEAR, FunctionCall, Fungible Token| +| 2 | Non-Fungible Token | +| 3 | Fungible Token, NEAR | + + +This means when the user claims their key for the first time, they will receive a FT, some NEAR and call a set of functions. On the second claim, they will receive an NFT while on the third and final claim, they will receive some NEAR and FTs. + +This behaviour is the same accross all the keys in the drop. As the drop funder, you would need to ensure your drop has all the necessary assets to fund all of the keys. For example, if each FT asset represents 1 Go-Team Token and you have 10 keys, you would need to fund your drop with 20 Go-Team Tokens. For more on how to use each asset, see the pages below. + +
+
+
+ +
+
+

Asset Types

+

Keypom building blocks.

+
+
+ +
+
+ +
+
+

Simple Assets

+

NEAR, NFTs and FTs

+
+
+ +
+
+
+
+ +
+
+

Function Call Assets

+

Supercharge your drop

+
+
+ +
+
+ +
+
+

Asset Configuration

+

Change claim behaviour

+
+
+ +
+
+
diff --git a/docs/Concepts/KeypomProtocol/intro-to-keypom.md b/docs/Concepts/KeypomProtocol/intro-to-keypom.md new file mode 100644 index 00000000..ebfb8cdb --- /dev/null +++ b/docs/Concepts/KeypomProtocol/intro-to-keypom.md @@ -0,0 +1,76 @@ +--- +sidebar_label: 'Introduction to Keypom' +--- + +# Introduction to Keypom +> To view our debut talk at NEARCON 2022, click [here](https://www.youtube.com/watch?v=J-BOnfhHV50). + +PUT MORE EMPHASIS ON WHAT IT IS, ECO PROJECTS ETC. + +Keypom is an access key factory created as a result of 3 common problems that arose in the ecosystem. + +1. People want a *cheap, customizable, and unique* onboarding experience for users. +2. Companies don't want to expose **full access keys** in their backend servers. +3. dApps want a *smooth UX* with zero barrier to entry onboarding. + +The contract was initially created as a way to handle the 1 $NEAR minimum deposit required for creating linkdrops using the [regular linkdrop contract](https://github.com/near/near-linkdrop/blob/f24f2608e1558db773f2408a28849d330abb3881/src/lib.rs#L18). + +If users wanted to create linkdrops, they needed to attach a **minimum** of 1 $NEAR. This made it costly and unscalable for projects that wanted to mass onboard onto NEAR. Keypom, on the other hand, has been highly optimized to allow for the lowest possible costs. + +## Problem + +Blockchain technology comes with many benefits such as sovereign ownership, digital rights, privacy, freedom, +peer to peer coordination and much more. The problem with this technology, however, is that there is an extremely +high barrier to entry for an everyday individual. None of it matters if nobody can onboard. + +Itโ€™s confusing to create and fund a crypto wallet. People are unfamiliar with the process, technical jargon, +and the general flow. NEARโ€™s account model is powerful, but extremely underutilized because itโ€™s complex for +developers to take full advantage of. Keypom wraps this up in a single API call. + +With NEARโ€™s goal of onboarding 1 billion users to Web3, there needs to be a solution to this high barrier to +entry for developers building on NEAR and users onboarding to their apps and the NEAR ecosystem. + +Below is a table outlining the minimum costs to onboard a new user onto NEAR with a named account. + +| | 1 Account | 1,000 Accounts | 1,000,000 Accounts | +|----------------------|-----------------|-----------------|--------------------| +| Traditional Linkdrop | ~1 NEAR | ~1,003 NEAR | ~1,002,840 NEAR | +| Keypom | ~0.0035 NEAR | ~3.5 NEAR | ~3,500 NEAR | +| | ~99.65% Cheaper | ~99.65% Cheaper | ~99.65% Cheaper | + +Keypom allows anyone to create highly customizable onboarding experiences for their users. These experiences +can be both for new, or existing users. If someone already has a wallet, they can still use a Keypom link to +experience an app, and then transfer the assets later. + +## Comparable Solutions + +| | **Keypom** | **NEAR Drop** | **Satori** | +|----------------------------------------------|------------|---------------|------------| +| NEAR Drop | โœ… | โœ… | โŒ | +| FT Drop | โœ… | โŒ | โŒ | +| NFT Drop | โœ… | โŒ | โœ… | +| Function Call Drop | โœ… | โŒ | โŒ | +| Embeddable in Dapps | โœ… | โŒ | โŒ | +| Wallet Selector Integration | โœ… | โŒ | โŒ | +| No Fee | โœ… | Maybe? | โŒ | +| No Backend / 3rd Party | โœ… | โœ… | โŒ | +| Campaigns | โœ… | โœ… | โœ… | +| Multi-Step e.g. Tickets click > scan > claim | โœ… | โŒ | โŒ | +| Password Protected Drops | โœ… | โŒ | โŒ | +| Timed Drops e.g. recurring payments | โœ… | โŒ | โŒ | +| Custom Names e.g. user.myapp.near | โœ… | โŒ | โŒ | + +# Our Solution + +Keypom allows for the creation of highly customizable access keys. These keys can be thought of as having their +own *smart contracts*. Each access key derives from what's known as a *drop*. These drops outline the different +functionalities and behaviors the key will have. A drop can be thought of as a bucket that access keys belong to. +You can create many different buckets and fill them each with their own keys. Each key will act in accordance to the +drop, or bucket, it belongs to. + +A drop can be one of four different types: + +1. Simple drop. +2. Non Fungible Token drop. +3. Fungible Token drop. +4. Function Call drop. \ No newline at end of file diff --git a/docs/Concepts/KeypomProtocol/nft-keys.md b/docs/Concepts/KeypomProtocol/nft-keys.md new file mode 100644 index 00000000..d1e586ab --- /dev/null +++ b/docs/Concepts/KeypomProtocol/nft-keys.md @@ -0,0 +1,285 @@ +--- +sidebar_label: 'Tradeable Access Keys' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; + +# Tradeable Access Keys +## What is a Tradeable Access Key? + +Every Keypom access key is linked with an NFT on the contract, giving your access keys NFT buy-sell functionality! + + +A tradeable access key allows you to sell, transfer and buy access keys, all securely on-chain. This creates an entirely new possibility of a secondary market and economy of access keys. This is particularly relevent to the field of event ticketing, where access keys as tickets hold high intrinsic value. + +In addition, since the access keys are associated with NFTs and leveraging technology defined by the [NFT standards](https://nomicon.io/Standards/Tokens/NonFungibleToken), they can work interoperably with any popular NFT marketplaces such as [Mintbase](https://www.mintbase.xyz/). + +:::info +In order to put an access key up for sale or transfer it, you must be one of the following: +* In possesion of the keypair and use it to sign transactions +* The key's owner, similar to the owner of an NFT +* An approved account, as per the NFT approval standard ([NEP-178](https://nomicon.io/Standards/Tokens/NonFungibleToken/ApprovalManagement)) +::: + +___ + +## Customizing NFTs associated with your Keys +Since your access keys are now linked with NFTs, you can now change the NFT metadata such as media, title, description and more in accordance to the NFT standard ([NEP-177](https://nomicon.io/Standards/Tokens/NonFungibleToken/Metadata)). This will change the way your access keys appear on NFT marketplaces. + +This customization applies to **all** access keys in your drop. Details on this can be found in the NFT Key Configuration section of the [drop configurations](drop-configurations.md#nft-key-configuration) page. + +___ + +## Owned versus Ownerless Keys +Access Key ownership is similar to NFT ownership in that it allows you transact it directly using the owner's account. This ownership can be transferred between accounts and be forfeitted. + +An ownerless access key is one that does not belong to any particular account, and thus cannot be transacted by any particular account. Rather, they can be transacted if the `nft_transfer` or `nft_approve` methods calls are signed by the access key itself. + +:::tip +Owned and Ownerless keys have the same functionality! +::: + +:::danger +PUT PROPER SCRIPTS BELOW INSTEAD OF TEST SCRIPTS +::: + +### Initializing Owner +When creating a drop with keys or adding keys to a drop, a vector of *key data* is added. + +```rust reference +https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/drop_creation/add_keys.rs#L6-L12 +``` + +This vector represents each access key and any additional data associated with it. The key data object includes a field `key_owner` for specifying an owner account ID. + +```rust reference +https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/models/external/models.rs#L81-L92 +``` + +### Adding Owner +If you added keys to the drop without an owner and wish to retroactively add owners to them, you can do so by using `nft_transfer` and sending it to the new owner. This transaction will need to be signed with the keypair that you wish to give to the new owner. + +Below is a modified example from our contract tests. In this example, the keyair being transferred is used to sign the `nft_transfer` transaction. + +```typescript +// **************** USE KEY ***************** +await keypomV3.setKey(keyPairs.keys[0]); + +// **************** TRANSFER **************** +let newKeyPair = await generateKeyPairs(1); +await functionCall({ + signer: keypomV3, + receiver: keypomV3, + methodName: "nft_transfer", + args: { + token_id: found_key_info.token_id, + receiver_id: bob.accountId, + memo: newKeyPair.publicKeys[0] + } +}) +``` +:::note +The `nft_transfer` function details will be covered [below](#transferring-an-access-key) +::: + +___ + +## Transferring an Access Key +Whether you just sold your access key or are sending it to a friend, transferring ownership of it on-chain is crucial to ensuring that the receiver is secure in knowing that the access key is ***truly*** theirs. If instead, you simply gave someone the keypair, they would have no confirmation that they actually own the key, and that you won't use it to claim the assets or experiences linked with the key. + +For that reason, transferring ownership of an access key is not as simple as just handing over the keypair, and rather involves leveraging `nft_transfer` to transfer on-chain ownership. + +```rust reference +https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/nft_keys/nft_core.rs#L11-L17 +``` + +In order to ensure that you, the previous owner, can no longer transact using the keypair, the access key **must** be swapped with a new keypair, provided as a `publicKey` in the `memo` field. Upon completion of the transfer, the new keypair now holds all the assets and the old keypair is no longer useable. + +### Transfer to Receiver with Account +The simplest case is the one where the receiver already has a NEAR wallet. Here, the transfer is just a normal `nft_transfer` where you include the receiver's account ID. + +:::note +Both owned and ownerless keys can use this method - either with the owner account ID or using the key itself to sign the `nft_transfer` transaction. The `token_id` can be found by calling the method [`get_key_information`](https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/views/keys.rs#L31). +::: + +Shown below is when the owner, Ali, invokes the method and transfer it to Bob. Bob then receives the keypair associated with the `publicKey` specified in the `memo` The ownerless case can be found in the exapndable section below it. + +```typescript +// ************ GENERATE NEW KEY ************ +let newKeyPair = await generateKeyPairs(1); + +// **************** TRANSFER **************** +await functionCall({ + signer: ali, + receiver: keypomV3, + methodName: "nft_transfer", + args: { + token_id: found_key_info.token_id, + receiver_id: bob.accountId, + memo: newKeyPair.publicKeys[0] + } +}) +``` + +
+ Owner invoked access key transfer +
+

+ +
+Transfer to Account using Key +

+ +The key itself can be used to sign the `nft_transfer` method. + +```typescript +// **************** USE KEY ***************** +await keypomV3.setKey(keyPairs.keys[0]); + +// ************ GENERATE NEW KEY ************ +let newKeyPair = await generateKeyPairs(1); + +// **************** TRANSFER **************** +await functionCall({ + signer: keypomV3, + receiver: keypomV3, + methodName: "nft_transfer", + args: { + token_id: found_key_info.token_id, + receiver_id: bob.accountId, + memo: newKeyPair.publicKeys[0] + } +}) +``` + +

+
+ +After this transfer, the receiver Bob can use this access key or trade/sell it using the same method, signing the `nft_transfer` method with his account ID. Giving Bob the new access key keypair is not necessary as he can sign with his own account but is highly recommended. + +### Transfer to Receiver without Account +In this scenario, the transfer works the same way as a receiver with an account, but with one **major** difference. The new keypair defined by the `memo`'s `publicKey` ***must*** be kept track of. This is because the receiver can only transact this access key with this keypair. + +:::caution +If the receiver does not receive the new keypair, they cannot continue to trade or sell the access key. +::: + +The rest of the process is exactly the same as the previous case transfering to a receiver with an account, except no `receiverId` is specified + +:::note +Both owned and ownerless keys can use this method - either with the owner account ID or using the key itself to sign the `nft_transfer` transaction. The `token_id` can be found by calling the method [`get_key_information`](https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/views/keys.rs#L31). +::: + +Shown below is when the owner, Ali, invokes the method and transfer it to no receiver account ID. The receiver should receive the keypair associated with the `publicKey` specified in the `memo` The ownerless case can be found in the exapndable section below it. + +```typescript +// ************ GENERATE NEW KEY ************ +let newKeyPair = await generateKeyPairs(1); + +// **************** TRANSFER **************** +await functionCall({ + signer: ali, + receiver: keypomV3, + methodName: "nft_transfer", + args: { + token_id: found_key_info.token_id, + memo: newKeyPair.publicKeys[0] + } +}) +``` + +
+ Owner invoked access key transfer +
+

+ +
+Transfer to Account using Key +

+ +The key itself can be used to sign the `nft_transfer` method. + +```typescript +// **************** USE KEY ***************** +await keypomV3.setKey(keyPairs.keys[0]); + +// ************ GENERATE NEW KEY ************ +let newKeyPair = await generateKeyPairs(1); + +// **************** TRANSFER **************** +await functionCall({ + signer: keypomV3, + receiver: keypomV3, + methodName: "nft_transfer", + args: { + token_id: found_key_info.token_id, + memo: newKeyPair.publicKeys[0] + } +}) +``` + +

+
+ +After this transfer, the receiver Bob can use this access key or trade/sell it using the same method, signing the `nft_transfer` method with his account ID. Giving Bob the new access key keypair is not necessary as he can sign with his own account but is highly recommended. + + +## Approving Marketplaces to Transact your Access Key +In order for your access key to be listed on a marketplace, such that the marketplace can sell and transfer your key for you, you must approve them, according to the NFT approval standard, [NEP-178](https://nomicon.io/Standards/Tokens/NonFungibleToken/ApprovalManagement). + +You can generate new approvals for different accounts/marketplaces by using the `nft_approve` method shown below. + +```rust reference +https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/nft_keys/approval.rs#L7C5-L7C105 +``` + +:::note +Both owned and ownerless keys can use this method - either with the owner account ID or using the key itself to sign the `nft_approve` transaction. The `token_id` can be found by calling the method [`get_key_information`](https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/views/keys.rs#L31). +::: + +Shown below is when the owner invokes the method. The ownerless case can be found in the exapndable section below it. + +```typescript +// **************** APPROVE **************** +await functionCall({ + signer: ali, + receiver: keypomV3, + methodName: "nft_approve", + args: { + token_id: token_id, + account_id: mintbase.accountId, + } +}) +``` + +
+ Owner invoked access key approval +
+

+ + +
+Approval using the Key +

+ +The key itself can be used to sign the `nft_approve` method. + +```typescript +// **************** USE KEY ***************** +await keypomV3.setKey(keyPairs.keys[0]); + +// **************** APPROVE **************** +await functionCall({ + signer: keypomV3, + receiver: keypomV3, + methodName: "nft_approve", + args: { + token_id: token_id, + account_id: mintbase.accountId, + } +}) +``` + +

+
diff --git a/docs/Concepts/KeypomProtocol/password-protect.md b/docs/Concepts/KeypomProtocol/password-protect.md new file mode 100644 index 00000000..54be9f24 --- /dev/null +++ b/docs/Concepts/KeypomProtocol/password-protect.md @@ -0,0 +1,301 @@ +--- +sidebar_label: 'Password Protected Keys' +sidebar_position: 3 +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Password Protected Keys + +Password protecting key uses is an extremely powerful feature that can unlock many use-cases. Keypom has baked flexibility and customization +into the contract such that almost all use-cases involving password protection can be accomplished. Whenever a key is added to a drop, it can +have a unique password for each individual use, a set of uses or the same password for all uses. + +___ + +## How Does It Work? + +The Keypom implementation has been carefully designed so that users can't look at the NEAR Explorer to view what was passed into the contract +either when the drop was created or when a key was used to try and copy those passwords. We also want passwords to be unique across keys so that +if you know the password for 1 key, it doesn't work on a different key. In order to accomplish this, we use the concept of hashing. + +Imagine you have a drop with 2 keys and you want to password protect each key. Rather than forcing the drop funder to input a unique password for +each key and having them remember each one, we can have them input a single **base password** and derive unique passwords from it that are paired +with the key's public key. + +This is the most scalable option as it allows the drop funder to only need to remember 1 password and they can derive all the other ones using the +hashing algorithm, public key, and current key use. + +In the above scenario, let's say the funder inputs the base password as `basepassword1`. If a user wanted to claim the first key, they would need to input +into the contract: + +`hash("basepassword1" + key1_public_key + key_use)` + +The funder would need to give the user this hash somehow (such as embedding it into the link or having an app that can derive it). It's important to note +that the funder should probably **NOT** give them the base password otherwise the user could derive the passwords for all other keys. + +___ + +## What is Stored On-Chain? + +How does Keypom verify that the user passed in the correct password? If the funder were to simply pass in `hash("mypassword1" + key1_public_key + key_use)` into the +contract as an argument when the key is created, users could just look at the NEAR Explorer and copy that value. + +Instead, the funder needs to pass in a double hash when the key is created: `hash(hash("mypassword1" + key1_public_key + key_use))`. + +This is the value that is stored on-chain and when the user tries to claim the key, they would pass in just the single hash: `hash("mypassword1" + key1_public_key + key_use)`. +The contract would then compute `hash(hash("mypassword1" + key1_public_key + key_use))` and compare it to the value stored on-chain. If they match, the key is claimed. + +Using this method, the base password is not exposed to the user, nobody can look on-chain or at the NEAR explorer and derive the password, and the password is unique +across multiple keys. + +___ + +## Defining Passwords + +New with Keypom V3, passwords are *no longer global*. This means that differfent access keys within your drop can have entirely different passwords, or some can have passwords while others have no passwords. + +This is done when adding keys to a drop, either when using `create_drop` or `add_keys`. These methods accept a **vector of keys objects** defined by the following: + +```rust reference +https://github.com/keypom/keypom/blob/807fea5997987cb1a97bee838c4d2312a7faab51/contract/src/models/external/models.rs#L81-L92 +``` + +Notice that `password_by_use` is mapped to each individual key, meaning you have control over the password design for each access key. + +Here, you need to define the key use number and associated password. The password you pass in should be the double hash, `hash(hash("mypassword1" + key1_public_key + key_use))`. An example `password_by_use` implementation is shown below. + +```javascript +password_by_use = { + 1: hash(hash(`${BASE_PASSWORD}${PUBLIC_KEY}1`)) + 3: hash(hash(`${BASE_PASSWORD}${PUBLIC_KEY}3`)) + 5: hash(hash(`${BASE_PASSWORD}${PUBLIC_KEY}5`)) +} +``` +:::note +Notice that not all uses are defined. Undefined uses will have no password +::: + +### Example Helper Function +You'll notice that this process of manually defining each key use password can grow tedious for each key. Below is an example helper function that was used during contract testing and NEARCON ticket generation. This function would return the record shown above. + +
+Example Password Generation Helper Function +

+ +```javascript +let basePassword = "my-example-password" +let password = await generatePasswordsForKey(publicKey.toString(), [1, 3, 5], basePassword); + +async function generatePasswordsForKey(pubKey, usesWithPassword, basePassword) { + let passwords = {}; + + // Loop through usesWithPassword + for (var use of usesWithPassword) { + let pw = basePassword + pubKey + use.toString() + console.log('pw before double hash: ', pw) + let firstHash = hash(pw) + passwords[use] = hash(firstHash, true); + } + + console.log(`pw after double hash: ${passwords[use]}`) + return passwords; +} + +function hash(string, double=false) { + if (double) { + return createHash('sha256').update(Buffer.from(string, 'hex')).digest('hex'); + } + return createHash('sha256').update(Buffer.from(string)).digest('hex'); +} +``` + +

+
+ + +___ + + + + + +## OLD + +Unlike the passwords per key which is the same for all uses of a key, the drop creator can specify a password for each individual key use. This password follows +the same pattern as the passwords per key in that the funder inputs a `hash(hash(SOMETHING))` and then the user would input `hash(SOMETHING)` and the contract +would hash this and compare it to the value stored on-chain. + +The difference is that each individual key use can have a different value stored on-chain such that the user can be forced to input a different hash each time. +This `SOMETHING` that is hashed can be similar to the global password per key example but this time, the desired key use is added: `hash("mypassword1" + key1_public_key + use_number)` + +In order to pass in the passwords per use, a new data structure is introduced so you only need to pass in passwords for the uses that have them. This is known as the +`JsonPasswordForUse` and is as follows: + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/29c10f949f02f673d4a3cecc21b0f74bca600075/src/lib/types/drops.ts#L193-L198 +``` + + + + +```rust reference +https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/models/json_types.rs#L152-L157 +``` + + + + +## Adding Your First Password + +Whenever keys are added to Keypom, if there's passwords involved, they must be passed in using the following format. + +```rust +passwords_per_use: Option>>>, +passwords_per_key: Option>>, +``` + +Each key that is being added either has a password, or doesn't. This is through the `Vec`. This vector **MUST** be the same length as the number of keys created.This doesn't +mean that every key needs a password, but the Vector must be the same length as the keys. + +As an example, if you wanted to add 3 keys to a drop and wanted only the first and last key to have a password_per_key, you would pass in: +```rust +passwords_per_key: Some(vec![Some(hash(hash(STUFF))), None, Some(hash(hash(STUFF2)))]) +``` + +# Complex Example + +To help solidify the concept of password protected keys, let's go through a complex example. Imagine Alice created a drop with a `uses_per_key` of 3. +She wants to create 4 keys: +- Key A: No password protection. +- Key B: Password for uses 1 and 2. +- Key C: Password for use 1 only. +- Key D: Password that doesn't depend on the use. + +In this case, for Keys B and C, they will have the same base password but Alice wants to switch things up and have a different base password for Key D. +When these keys are added on-chain, the `passwords_per_key` will be passed in as such: + +```rust +passwords_per_key: Some(vec![ + None, // Key A + None, // Key B + None, // Key C + // Key D + Some( + hash(hash("key_d_base_password" + key_d_public_key)) + ), +]), +``` +The passwords for Key B and Key C will be passed in as such: + +```rust +passwords_per_key: Some(vec![ + None, // Key A + + // Key B + vec![ + { + pw: hash(hash("keys_bc_base_password" + key_b_public_key + "0")), + key_use: 0 + }, + { + pw: hash(hash("keys_bc_base_password" + key_b_public_key + "1")), + key_use: 1 + } + ] + + // Key C + vec![ + { + pw: hash(hash("keys_bc_base_password" + key_c_public_key + "0")), + key_use: 0 + } + ] + + None // Key D +]), +``` + +The drop funder would then give the keys out to people: + +## Key A +Alice gives Bob Key A and he would be able to claim it 3 times with no password required. + +## Key D +Alice gives Charlie Key D and he would be able to claim it 3 times with the hashed global key password: `hash("key_d_base_password" + key_d_public_key)`. +When Charlie claims the key, he would input the password `hash("key_d_base_password" + key_d_public_key)` and the contract would hash that and check to see +if it matches what is stored on-chain (which it does). + +If anyone tried to look at what Charlie passes in through the explorer, it wouldn't work since his hash contains the public key for key D and as such it is only +valid for Key D. + +Similarly, if Charlie tried to look at the explorer when Alice created the keys and attempted to pass in `hash(hash("key_d_base_password" + key_d_public_key))`, +the contract would attempt to hash this and it would NOT match up with what's in the storage. + +## Key B +Alice gives Eve Key B and she would need a password for claim 1 and 2. For the first claim, she needs to pass in: `hash("keys_bc_base_password" + key_b_public_key + "0")`. +The contract would then check and see if the hashed version of this matches up with what's stored on-chain for that use. + +The second time Eve uses the key, she needs to pass in hash("keys_bc_base_password" + key_b_public_key + "1") and the same check is done. + +If Eve tries to pass in `hash("keys_bc_base_password" + key_b_public_key + "0")` for the second key use, the contract would hash it and check: + +hash(hash("keys_bc_base_password" + key_b_public_key + "0")) == hash(hash("keys_bc_base_password" + key_b_public_key + "1")) + +Which is incorrect and the key would not be claimed. + +Once Eve claims the key 2 times, the last claim is not password protected and she's free to claim it. + +Key C is similar to Key B except that it only has 1 password for the first use. + +# Use-Cases + +Password protecting key uses is a true game changer for a lot of use-cases spanning from ticketing to simple marketing and engagement. + +### Ticketing and POAPs + +Imagine you had an event and wanted to give out exclusive POAPs to people that came. You didn't want to force users to: +- Have a NEAR wallet +- Have wifi at the door. +- Burn NFTs or tokens to get into the event. + +The important thing to note is that by using password protected key uses, you can **GUARANTEE** that anyone that received a POAP had to +**PHYSICALLY** show up to the event. This is because the POAP would be guarded by a password. + +You could create a ticketing event using Keypom as outlined in the [Ticketing](#nft-ticketing) section and have a key with 2 uses. The first use +would be password protected and the second use is not. The first use will get you through the door and into the event and the second +contains the exclusive POAP and can onboard you. This means that anyone with the ticket, or key, can only receive the POAP if they know the password. + +You can have a scanner app that would scan people's tickets (tickets are just the private key). In this scanner app, the *base password* is stored and +whenever the ticket is scanned, the public key is taken and the following hash is created: + +`hash(base password + public key)` + +This hash is then used to claim a use of the key and you will be let into the party. The scanner app can deterministically generate all the +necessary hashes for all the tickets by simply scanning the QR code (which has the private key exposed). The tickets are worthless unless +you actually show up to the event and are scanned. + +Once you're scanned, you can refresh your ticket page and the use the second key claim which is not password protected. This use contains the +exclusive POAP and you can onboard onto NEAR. + +### Marketing and Engagement + +Let's say that you're at an event and want people to show up to your talks and learn about your project. You can have a scanner app similar to the +one mentioned in the ticketing scenario that derives the password for any use on any key. + +At the beginning of the event, you can give out a bunch of keys that have progressively increasing rewards gated by a password. At the end, the last +key use contains a special reward that is only unlocked if the user has claimed all the previous key uses. + +In order for these uses to be unlocked, People must show up to your talks and get scanned. The scanner will derive the necessary password and unlock +the rewards. Users will only get the exclusive reward if they come to ALL your talks. + +This idea can be further expanded outside the physical realm to boost engagement on your websites as an example: + +You want users to interact with new features of your site or join your mailing list. + +You can have links where uses are ONLY unlocked if the user interacts with special parts of your site such as buying a new NFT or joining your mailing list +or clicking an easter egg button on your site etc. + diff --git a/docs/Concepts/KeypomProtocol/terminology.md b/docs/Concepts/KeypomProtocol/terminology.md new file mode 100644 index 00000000..72b01ee6 --- /dev/null +++ b/docs/Concepts/KeypomProtocol/terminology.md @@ -0,0 +1,92 @@ +--- +sidebar_label: 'Foundational Concepts' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; + +# Foundational Concepts +## Drops vs. Keys +> Keypom revolves around collections of **Access Keys** called **Drops**. + +* ***Access Key***: A NEAR keypair, this is what each user receives to start their Keypom experience. + * Can have assets, such an NFT, FTs, NEAR or FunctionCalls, associated with them. + * When a user receives a key and uses it, they will receive those assets. +* ***Drop***: A collection of access keys that all share the same traits - such as assets and configurations. + * As a funder, you create the drop and fund all the assets + * You can add as many keys as you want to the drop, even after its creation. + +An easy way to think about it is that you *create a drop* but you *distrubute keys*. + +___ + +## What are Assets? +> In the Keypom Protocol, an asset it something you attach to every key in your drop. When someone obtains and uses a key, they will receive the assets - either to a new or existing account. + +Assets can be NEAR, Fungible Tokens, Non-Fungible Tokens, or FunctionCalls. Each key in a drop holds the same assets, meaning a user can receive any key from the drop and be guarenteed the same set of assets. + + +For every use on an Access Key, the different types of assets can be mixed to create an infinite number of experiences! + + + +Access Keys can have multiple uses and their assets are defined **per use**. These can be mix-and-matched to craft any experience you want. An example can be seen below: + + +| **Key Use** | **Assets** | +|-------------|-----------------------------------| +| 1 | NEAR, FunctionCall, Fungible Token| +| 2 | Non-Fungible Token | +| 3 | Fungible Token, NEAR | + + +This means when the user claims their key for the first time, they will receive a FT, some NEAR and call a set of functions. On the second claim, they will receive an NFT while on the third and final claim, they will receive some NEAR and FTs. + +This behaviour is the same accross all the keys in the drop. As the drop funder, you would need to ensure your drop has all the necessary assets to fund all of the keys. Following the above example, if each FT asset represents 1 Go-Team Token and you have 10 keys, you would need to fund your drop with 20 Go-Team Tokens. For more on how to use each asset, see the pages below. + +
+
+
+ +
+
+

Asset Types

+

Keypom building blocks.

+
+
+ +
+
+ +
+
+

Simple Assets

+

NEAR, NFTs and FTs

+
+
+ +
+
+
+
+ +
+
+

Function Call Assets

+

Supercharge your drop

+
+
+ +
+
+ +
+
+

Asset Configuration

+

Change claim behaviour

+
+
+ +
+
+
diff --git a/docs/Tutorials/Advanced/ticketing/architecture.md b/docs/Tutorials/Advanced/ticketing/architecture.md index 590d1839..922e9f38 100644 --- a/docs/Tutorials/Advanced/ticketing/architecture.md +++ b/docs/Tutorials/Advanced/ticketing/architecture.md @@ -39,7 +39,7 @@ In order to send the attendees a POAP, the second key use will need to not only Currently, anyone with a ticket could manually claim the key (sign transactions) using the Keypom SDK. This means that people could first claim the `null` case and then claim the key again to receive the NFT without physically showing up. -To solve this, the first key use can be protected with a [password](../../../Concepts/KeypomProtocol/GithubReadme/password-protect.md) that only the host knows. This password will be provided when the QR code is scanned. By password protected the uses, the only way to receive the NFT even if you have the ticket, is to be physically scanned by the host. +To solve this, the first key use can be protected with a [password](../../../Concepts/KeypomProtocol/password-protect.md) that only the host knows. This password will be provided when the QR code is scanned. By password protected the uses, the only way to receive the NFT even if you have the ticket, is to be physically scanned by the host. ## Keypom Solution diff --git a/docs/exec-summary.md b/docs/exec-summary.md index a448aa93..c52876f5 100644 --- a/docs/exec-summary.md +++ b/docs/exec-summary.md @@ -1,3 +1,7 @@ +--- +sidebar_label: '๐Ÿ’ก Keypom Executive Summary' +--- + # Keypom Executive Summary > To discover the features and details of Keypom, begin your journey [here](Concepts/welcome.md). diff --git a/docusaurus.config.js b/docusaurus.config.js index 4184be45..a767fe85 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -19,7 +19,7 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); ({ hashed: true, language: ["en"], - ignoreFiles: ["docs/1.1/nothing-page", "docs/nothing-page", "docs/1.2/nothing-page", "docs/next/Tutorials/Misc/sign-txn"] + ignoreFiles: ["docs/1.1/nothing-page", "docs/nothing-page", "docs/1.2/nothing-page", "docs/Tutorials/Misc/sign-txn"] }), ], ], @@ -42,9 +42,16 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); // ], // Please change this to your repo. editUrl: 'https://github.com/keypom/keypom-docs/tree/main/', + // versions: { + // current: { + // banner: 'none', + // }, + // }, + lastVersion: 'current', versions: { current: { - banner: 'none', + label: '3.0', + badge: true }, }, @@ -72,47 +79,48 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); }, items: [ { - to: "docs/next/Concepts/welcome", + to: "docs/Concepts/welcome", label: "๐Ÿ“– Concepts", position: "left", }, { - to: "docs/next/Tutorials/welcome", + to: "docs/Tutorials/welcome", label: "๐Ÿ’ป Tutorials", position: "left", }, // { - // to: "docs/next/KeypomV2/welcome", + // to: "docs/KeypomV2/welcome", // label: "๐Ÿค– Keypom V2", // position: "left", // }, { - to: "docs/next/TrialAccounts/introduction", + to: "docs/TrialAccounts/introduction", label: "๐ŸŽ Trial Accounts", position: "left", }, { label: '๐Ÿš€ BOS', - to: 'docs/next/Tutorials/BOS/welcome', + to: 'docs/Tutorials/BOS/welcome', }, { - to: "docs/next/keypom-sdk/Core/welcome", + to: "docs/keypom-sdk/Core/welcome", label: "๐Ÿ“š SDK TypeDocs", position: "left", }, { - to: "docs/next/Cookbook/welcome", + to: "docs/Cookbook/welcome", label: "๐Ÿง‘โ€๐Ÿณ Cookbook", position: "left", }, + { + type: 'docsVersionDropdown', + position: 'right', + }, { href: 'https://github.com/keypom/keypom-docs/tree/main', label: 'GitHub', position: 'right', }, - // { - // type: 'docsVersionDropdown', - // }, ], }, footer: { @@ -125,32 +133,32 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); items: [ { label: '๐Ÿ“– Concepts', - to: 'docs/next/Concepts/welcome', + to: 'docs/Concepts/welcome', }, { label: '๐Ÿ’ป Tutorials', - to: 'docs/next/Tutorials/welcome', + to: 'docs/Tutorials/welcome', }, { - to: "docs/next/TrialAccounts/introduction", + to: "docs/TrialAccounts/introduction", label: "๐ŸŽ Trial Accounts", position: "left", }, { label: '๐Ÿš€ BOS', - to: 'docs/next/Tutorials/BOS/welcome', + to: 'docs/Tutorials/BOS/welcome', }, { label: "๐Ÿ“š SDK TypeDocs", - to: "docs/next/keypom-sdk/Core/welcome", + to: "docs/keypom-sdk/Core/welcome", }, { label: "๐Ÿง‘โ€๐Ÿณ Cookbook", - to: "docs/next/Cookbook/welcome", + to: "docs/Cookbook/welcome", } // { // label: "๐Ÿค–Keypom V2", - // to: "docs/next/KeypomV2/welcome", + // to: "docs/KeypomV2/welcome", // }, ], }, diff --git a/sidebars.js b/sidebars.js index f666401b..fb3a18c2 100644 --- a/sidebars.js +++ b/sidebars.js @@ -8,7 +8,7 @@ const sidebars = { // link: { // type: 'concepts/Linkdrops and Access Keys/linkdrop-welcome', // }, - collapsed: false, + collapsed: true, items: [ 'Concepts/LinkdropsAndAccessKeys/near-access-keys', 'Concepts/LinkdropsAndAccessKeys/linkdrop-basics', @@ -22,40 +22,27 @@ const sidebars = { // }, collapsed: false, items: [ - 'Concepts/KeypomProtocol/overview', + 'Concepts/KeypomProtocol/intro-to-keypom', + 'Concepts/KeypomProtocol/terminology', { type: 'category', - label: 'Types of Drops', + label: 'Keypom Drop Assets', // link: { // item: 'Concepts/Keypom Protocol/Github Readme/Types of Drops/introduction', // }, - collapsed: true, + collapsed: false, items: [ - 'Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/introduction', - 'Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/simple-drops', - 'Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/nft-drops', - 'Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/ft-drops', - 'Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops', + 'Concepts/KeypomProtocol/Assets/asset-types', + 'Concepts/KeypomProtocol/Assets/basic-assets', + 'Concepts/KeypomProtocol/Assets/function-call', + 'Concepts/KeypomProtocol/Assets/key-use-configurations', + 'Concepts/KeypomProtocol/Assets/time-customization', ], }, + 'Concepts/KeypomProtocol/nft-keys', + 'Concepts/KeypomProtocol/drop-configurations', 'Concepts/KeypomProtocol/balances', - { - type: 'category', - label: 'Configuring Your Drop', - // link: { - // type: 'doc', - // id: 'Concepts/Keypom Protocol/Github Readme/Types of Drops/customization-homepage', - // }, - collapsed: true, - items: [ - 'Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/customization-homepage', - 'Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/drop-customization', - 'Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/time-customization', - 'Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/usage-customization', - 'Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/sale-customization', - ], - }, - 'Concepts/KeypomProtocol/GithubReadme/password-protect', + 'Concepts/KeypomProtocol/password-protect', { type: 'category', label: 'Overhead Items', diff --git a/src/pages/index.md b/src/pages/index.md index 9e26a95e..bcd3a355 100644 --- a/src/pages/index.md +++ b/src/pages/index.md @@ -20,7 +20,7 @@ import {FeatureList, Column, Feature} from "../components/featurelist.js"
- +
Learn @@ -33,7 +33,7 @@ import {FeatureList, Column, Feature} from "../components/featurelist.js"
- +
Examples and Tutorials @@ -55,28 +55,28 @@ import {FeatureList, Column, Feature} from "../components/featurelist.js" - - - + + + - - - - + + + + - - - - + + + + - + diff --git a/src/theme/DocVersionBanner/index.js b/src/theme/DocVersionBanner/index.js new file mode 100644 index 00000000..e5c148f2 --- /dev/null +++ b/src/theme/DocVersionBanner/index.js @@ -0,0 +1,148 @@ +import React from 'react'; +import clsx from 'clsx'; +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; +import Link from '@docusaurus/Link'; +import Translate from '@docusaurus/Translate'; +import { + useActivePlugin, + useDocVersionSuggestions, +} from '@docusaurus/plugin-content-docs/client'; +import {ThemeClassNames} from '@docusaurus/theme-common'; +import { + useDocsPreferredVersion, + useDocsVersion, +} from '@docusaurus/theme-common/internal'; +function UnreleasedVersionLabel({siteTitle, versionMetadata, latestVersion, to, onClick}) { + return ( + {versionMetadata.label}, + latestVersionLink: ( + + + + {latestVersion} + + + + ), + }}> + { + 'This is unreleased Keypom documentation for v{versionLabel}. For the lastest, see v{latestVersionLink}' + } + + ); +} +function UnmaintainedVersionLabel({siteTitle, versionMetadata, latestVersion, to, onClick}) { + return ( + {versionMetadata.label}, + latestVersionLink: ( + + + + {latestVersion} + + + + ), + }}> + { + 'You are viewing documentation for Keypom v{versionLabel}. For the lastest, see v{latestVersionLink}' + } + + ); +} +const BannerLabelComponents = { + unreleased: UnreleasedVersionLabel, + unmaintained: UnmaintainedVersionLabel, +}; +function BannerLabel(props) { + const BannerLabelComponent = + BannerLabelComponents[props.versionMetadata.banner]; + return ; +} +function LatestVersionSuggestionLabel({versionLabel, to, onClick}) { + return ( + + + + here + + + + ), + }}> + { + 'For the lastest documentation, see {latestVersionLink}.' + } + + ); +} +function DocVersionBannerEnabled({className, versionMetadata}) { + const { + siteConfig: {title: siteTitle}, + } = useDocusaurusContext(); + const {pluginId} = useActivePlugin({failfast: true}); + const getVersionMainDoc = (version) => + version.docs.find((doc) => doc.id === version.mainDocId); + const {savePreferredVersionName} = useDocsPreferredVersion(pluginId); + const {latestDocSuggestion, latestVersionSuggestion} = + useDocVersionSuggestions(pluginId); + // Try to link to same doc in latest version (not always possible), falling + // back to main doc of latest version + const latestVersionSuggestedDoc = + latestDocSuggestion ?? getVersionMainDoc(latestVersionSuggestion); + return ( +
+
+ savePreferredVersionName(latestVersionSuggestion.name) } /> +
+ {/*
+ savePreferredVersionName(latestVersionSuggestion.name)} + /> +
*/} +
+ ); +} +export default function DocVersionBanner({className}) { + const versionMetadata = useDocsVersion(); + if (versionMetadata.banner) { + return ( + + ); + } + return null; +} diff --git a/static/img/nearcon-tickets.png b/static/img/nearcon-tickets.png new file mode 100644 index 00000000..6759b67f Binary files /dev/null and b/static/img/nearcon-tickets.png differ diff --git a/versioned_docs/version-1.1/nothing-page.md b/versioned_docs/version-1.1/nothing-page.md deleted file mode 100644 index e69de29b..00000000 diff --git a/versioned_docs/version-1.2.1/nothing-page.md b/versioned_docs/version-1.2.1/nothing-page.md deleted file mode 100644 index e69de29b..00000000 diff --git a/versioned_docs/version-1.2/nothing-page.md b/versioned_docs/version-1.2/nothing-page.md deleted file mode 100644 index e69de29b..00000000 diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/Introduction/Introduction.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/Introduction/Introduction.md new file mode 100644 index 00000000..ae12f19c --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/Introduction/Introduction.md @@ -0,0 +1,58 @@ +--- +sidebar_label: 'Introduction to Keypom' +sidebar_position: 1 +--- +> To view our debut talk at NEARCON 2022, click [here](https://www.youtube.com/watch?v=J-BOnfhHV50). + +Keypom is an access key factory created as a result of 3 common problems that arose in the ecosystem. + +1. People want a *cheap, customizable, and unique* onboarding experience for users. +2. Companies don't want to expose **full access keys** in their backend servers. +3. dApps want a *smooth UX* with zero barrier to entry onboarding. + +The contract was initially created as a way to handle the 1 $NEAR minimum deposit required for creating linkdrops using the [regular linkdrop contract](https://github.com/near/near-linkdrop/blob/f24f2608e1558db773f2408a28849d330abb3881/src/lib.rs#L18). + +If users wanted to create linkdrops, they needed to attach a **minimum** of 1 $NEAR. This made it costly and unscalable for projects that wanted to mass onboard onto NEAR. Keypom, on the other hand, has been highly optimized to allow for the lowest possible costs. + +## Problem + +Blockchain technology comes with many benefits such as sovereign ownership, digital rights, privacy, freedom, +peer to peer coordination and much more. The problem with this technology, however, is that there is an extremely +high barrier to entry for an everyday individual. None of it matters if nobody can onboard. + +Itโ€™s confusing to create and fund a crypto wallet. People are unfamiliar with the process, technical jargon, +and the general flow. NEARโ€™s account model is powerful, but extremely underutilized because itโ€™s complex for +developers to take full advantage of. Keypom wraps this up in a single API call. + +With NEARโ€™s goal of onboarding 1 billion users to Web3, there needs to be a solution to this high barrier to +entry for developers building on NEAR and users onboarding to their apps and the NEAR ecosystem. + +Below is a table outlining the minimum costs to onboard a new user onto NEAR with a named account. + +| | 1 Account | 1,000 Accounts | 1,000,000 Accounts | +|----------------------|-----------------|-----------------|--------------------| +| Traditional Linkdrop | ~1 NEAR | ~1,003 NEAR | ~1,002,840 NEAR | +| Keypom | ~0.0035 NEAR | ~3.5 NEAR | ~3,500 NEAR | +| | ~99.65% Cheaper | ~99.65% Cheaper | ~99.65% Cheaper | + +Keypom allows anyone to create highly customizable onboarding experiences for their users. These experiences +can be both for new, or existing users. If someone already has a wallet, they can still use a Keypom link to +experience an app, and then transfer the assets later. + +## Comparable Solutions + +| | **Keypom** | **NEAR Drop** | **Satori** | +|----------------------------------------------|------------|---------------|------------| +| NEAR Drop | โœ… | โœ… | โŒ | +| FT Drop | โœ… | โŒ | โŒ | +| NFT Drop | โœ… | โŒ | โœ… | +| Function Call Drop | โœ… | โŒ | โŒ | +| Embeddable in Dapps | โœ… | โŒ | โŒ | +| Wallet Selector Integration | โœ… | โŒ | โŒ | +| No Fee | โœ… | Maybe? | โŒ | +| No Backend / 3rd Party | โœ… | โœ… | โŒ | +| Campaigns | โœ… | โœ… | โœ… | +| Multi-Step e.g. Tickets click > scan > claim | โœ… | โŒ | โŒ | +| Password Protected Drops | โœ… | โŒ | โŒ | +| Timed Drops e.g. recurring payments | โœ… | โŒ | โŒ | +| Custom Names e.g. user.myapp.near | โœ… | โŒ | โŒ | diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/Introduction/our-solution.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/Introduction/our-solution.md new file mode 100644 index 00000000..602e84f3 --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/Introduction/our-solution.md @@ -0,0 +1,18 @@ +--- +sidebar_label: 'Keypom Solution' +sidebar_position: 2 +--- +# Our Solution + +Keypom allows for the creation of highly customizable access keys. These keys can be thought of as having their +own *smart contracts*. Each access key derives from what's known as a *drop*. These drops outline the different +functionalities and behaviors the key will have. A drop can be thought of as a bucket that access keys belong to. +You can create many different buckets and fill them each with their own keys. Each key will act in accordance to the +drop, or bucket, it belongs to. + +A drop can be one of four different types: + +1. Simple drop. +2. Non Fungible Token drop. +3. Fungible Token drop. +4. Function Call drop. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/customization-homepage.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/customization-homepage.md new file mode 100644 index 00000000..f958c920 --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/customization-homepage.md @@ -0,0 +1,57 @@ +--- +sidebar_label: 'What are Drop Configurations?' +--- +# What are Drop Configurations? + +What sets Keypom apart from the basic [NEAR Linkdrop](https://github.com/near/near-linkdrop)? One major aspect is that Keypom allows for LOADS of customization! + +This can allow for your to create linkdrops where the keys can become multi-use and controlled by start time, time between uses and much more! With these tools and Keypom's 4 drop types, you can create everything from unique onboardings to [tiered and exclusive tickets](../../../../Tutorials/Advanced/ticketing/introduction.md). + +/Users/min/Documents/NEAR_Stuff/keypom-docs/docs/Tutorials/Advanced/ticketing/introduction.md + +This is all done through **Drop Configurations**. + +:::info +The three objects used to customize your drops are **DropConfig**, **TimeConfig**, and **UsageConfig**. + +Any customization will apply to ALL keys in that drop. +::: + +[**DropConfig**](drop-customization.md) - Top level configurations, dictates major parameters such as number of uses per key. + +[**TimeConfig**](time-customization.md) - All configurations related to time, such as time between uses. + +[**UsageConfig**](usage-customization.md) - Administrative configurations, such as whether to delete the drop when all keys are used. + +[**PublicSaleConfig**](sale-customization.md) - Configurations that allow the funder to create a public sale. Public sales are done by allowing users to add keys to the drop at a fee. + +The structure for all the configurations can be seen in the tree below. + +## Drop Configuration Structure +``` bash +DropConfig +โ”œโ”€โ”€ uses_per_key +โ”‚ +โ”œโ”€โ”€ TimeConfig +โ”‚ โ””โ”€โ”€ start +โ”‚ โ””โ”€โ”€ end +โ”‚ โ””โ”€โ”€ throttle +โ”‚ โ””โ”€โ”€ interval +โ”‚ +โ”œโ”€โ”€ UsageConfig +โ”‚ โ””โ”€โ”€ permissions +โ”‚ โ””โ”€โ”€ refund_deposit +โ”‚ โ””โ”€โ”€ auto_delete_drop +โ”‚ โ””โ”€โ”€ auto_withdraw +โ”‚ +โ”œโ”€โ”€ PublicSaleConfig +โ”‚ โ””โ”€โ”€ max_num_keys +โ”‚ โ””โ”€โ”€ price_per_key +โ”‚ โ””โ”€โ”€ allowlist +โ”‚ โ””โ”€โ”€ blocklist +โ”‚ โ””โ”€โ”€ auto_withdraw_funds +โ”‚ โ””โ”€โ”€ start +โ”‚ โ””โ”€โ”€ end +โ”‚ +โ”œโ”€โ”€ root_account_id +``` \ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/drop-customization.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/drop-customization.md new file mode 100644 index 00000000..53db7592 --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/drop-customization.md @@ -0,0 +1,70 @@ +--- +sidebar_label: 'Drop Configurations' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Drop Configurations +Drop Customizations via the `DropConfig` object passed into `create_drop` can help adjust the properties and behaviors of a drop to achieve specific use-cases. + +From changing the amount of times a key can be used before it's deleted to setting a public sale and making profit from keys being added to your drop, understanding the power of the `DropConfig` is crucial to making the most of Keypom! + +:::tip +A configuration applies to **ALL KEYS** across a drop. + +This means that if you want keys with different configurations, you must create multiple drops with their respective configurations. +::: + +# Understanding `DropConfig` + + + +```ts reference +https://github.com/keypom/keypom-js/blob/29c10f949f02f673d4a3cecc21b0f74bca600075/src/lib/types/drops.ts#L64-L82 +``` + + + + +```rust reference +https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/models/json_types.rs#L56-L73 +``` + + + + +For now, the focus will be `uses_per_key` and `root_account_id`. [`TimeConfig`](time-customization.md), [`UsageConfig`](usage-customization.md), and [`PublicSaleConfig`](sale-customization.md) are covered later. + +--- + +## Uses per Key +*Default: 1* + +This parameter allows you to set the number of times a user can claim a key before it is deleted. + +### Use cases +This parameter is incredibly versatile and can be used in numerous ways. Some excellent examples are: + +1. Rewards that progressively increase in value. For example, you could incentivize people to show up to all your talks at a conference. A link would be given out that needed to be physically scanned at your talk to unlock rewards. If you showed up to all the events, a jackpot prize could be claimed. +2. A set number of [Recurring Payments](../../GithubReadme/TypesOfDrops/simple-drops.md#recurring-payments) for subscriptions or contracted/freelanced work. +3. A method to accurately track retention, such as [Event Turnout](../../GithubReadme/TypesOfDrops/fc-drops.md#nft-ticketing) + + +When used with [function call drops](fc-drops.md), some more complex use cases can be created, such as Customizable Multi-Phase Onboarding and [Auto DAO-Registration](../../../../Tutorials/Advanced/daos/introduction.md) + +--- + +## Root Account ID +*Default: `near` or `testnet`* + +The `root_account_id` parameter determines which account the newly-created claiming account will be a sub-account of. For example, the default is `near` so all accounts would end in `.near` such as `benji.near`. Changing the `root_account_id` parameter will change the root of all the accounts that users create through `create_account_and_claim` when using your drop. + +### Use cases +Let's say you have an organization called Moonpom (secretly run by our beloved Pomeranian, Moon) and you want your users want to proudly represent Moonpom! + +You set `root_account_id = "moonpom.near"` and now any account created using your linkdrops will take on the form `${YOUR_USERNAME}.moonpom.near` + +:::caution Important +the `root_account_id` **must** have a contract deployed to it that exposes a method `create_account` to create the sub-account. A sample contract can be found [here](https://github.com/near/near-linkdrop) +::: + diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops.md new file mode 100644 index 00000000..c3eb906a --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops.md @@ -0,0 +1,224 @@ +--- +sidebar_label: 'Function Call Drops' +sidebar_position: 5 +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Function Call Drops + +Function call drops are by far the most powerful feature that Keypom provides. FC drops allow **any** method on **any** +contract to be executed (with some exceptions). In addition, there are a huge variety of customizations and features you can choose from when +defining the drop that come on top of the global options. The possibilities are almost endless. State of the art NFT ticketing, +lazy minting NFTs, auto registration into DAOs, analytics for marketing at events and much more. + +## How does it work? + +Unlike NFT and FT drops, the function calls must have everything paid for **upfront**. There is no two step process +so the creation is similar to Simple drops. Once the drop is created and keys are added, you can immediately start using it. + +### Function Call Config + +When creating the drop, you have quite a lot of customization available. At the top level, there is a FC drop global +config similar to how the *general* config works. + + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/e8c43f4219a79afb3c367296cc90b8d5de977945/src/lib/types/fc.ts#L68-L74 +``` + + + + +```rust reference +https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/models/fc_model.rs#L53-L58 +``` + + + + + +### `Method`/`MethodData` + +In addition to the global config, the user can specify a set of what's known as `Method`. This represents the +information for the function being called. Within this data, there are also a few optional configurations you can use +to extend your use cases. You'll see how powerful these can be in the use cases [section](#use-cases). + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/e8c43f4219a79afb3c367296cc90b8d5de977945/src/lib/types/fc.ts#L7-L63 +``` + + + + +```rust reference +https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/models/fc_model.rs#L18-L48 +``` + + + + + +`Method`/`MethodData` keeps track of the method being called, receiver, arguments, and attached deposit. In addition, there are +some optional fields that can be used to extend the use cases. If you have a contract that requires some more context from +Keypom such as the drop ID, key ID, or account ID that used the key, these can all be specified. + +We've kept it generic such that you can specify the actual argument name that these will be passed in as. For example, if you +had a contract that would lazy mint an NFT and it required the account to be passed in as `receiver_id`, you could specify +an `account_id_field` set to `receiver_id` such that Keypom will automatically pass in the account ID that used the key under the +field `receiver_id`. + +This logic extends to the drop ID, and key Id as well. + +### Key Uses + +For **every key use**, you can specify a *vector* of `Method`/`MethodData` which allows you to execute multiple function calls each +time a key is used. These calls are scheduled 1 by 1 using a simple for loop. This means that most of the time, the function +calls will be executed in the order specified in the vector but it is not *guaranteed*. + +It's important to note that the Gas available is split evenly between *all* the function calls and if there are too many, +you might run into issues with not having enough Gas. You're responsible for ensuring that this doesn't happen. + +The vector of `Method`/`MethodData` is *optional* for each key use. If a key use has `null` rather than `Some(Vector)` or `Maybe>`, +it will decrement the uses and work as normal such that the `throttle_timestamp, `start_timestamp` etc. are enforced. The only +difference is that after the key uses are decremented and these checks are performed, the execution **finishes early**. The null +case does **not** create an account or send *any* funds. It doesn't invoke any function calls and simply *returns once the +checks are done*. This makes the null case act as a "burner" where you disregard any logic. This has many uses which will +be explored in the use cases [section](#use-cases). + +If a key has more than 1 use, you can specify a *different vector* of `Method`/`MethodData` for **each use**. As an example, you could +specify that the first use will result in a null case and the second use will result in a lazy minting function being called. +If you have multiple uses but want them all to do the same thing, you don't have to repeat the same data. Passing in only 1 +vector of `Method`/`MethodData` will result in **all the uses** inheriting that data. + +## Security + +Since all FC drops will be signed by the Keypom contract, there are a few restrictions in place to avoid malicious behaviors. +To avoid users from stealing registered assets from other drops, the following methods cannot be called via FC Drops: + +```rust reference +https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/lib.rs#L926-L934 +``` + +In addition, the Keypom contract cannot be the receiver of any function call. This is to avoid people +from calling private methods through FC Drops. + +### Keypom Arguments + +When a key is used and a function is called, there is a data structure that is **automatically** attached to the arguments. +This is known as the `keypom_args`. It contains the information that the drop creator specified in the `Method`/`MethodData`. + +```rust reference +https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/stage1/function_call.rs#L17-L22 +``` + +#### Motivation + +Let's say there was an exclusive NFT contract that allowed the Keypom contract to mint NFTs as part of an FC drop. Only Keypom +was given access to mint the NFTs so they could be given out as linkdrops. The organizer only wanted links that were part of their +drop to be valid. For this reason, the NFT contract would only mint if Keypom called the `nft_mint` function and there was a field +`series` passed in and it was equal to the drop ID created by the organizer. + +Let's say the owner created an exclusive drop that happened to have a drop ID of 5. They could then go to the NFT contract +and restrict NFTs to only be minted if: +- `series` had a value of 5. +- The Keypom contract was the one calling the function. + +In order for this to work, when creating the drop, the owner would need to specify that the`drop_id_field` was set to a value of `series` +such that the drop ID is correctly passed into the function. + +The problem with this approach is that the NFT contract has no way of knowing which arguments were sent by the **user** when the drop +was created as part of the MethodData `args` and which arguments are automatically populated by the Keypom contract. There is nothing +stopping a malicious user from creating a new drop that has an ID of 6 but hard-coding in the actual arguments that `series` should have +a value of 5. In this case, the malicious drop would have *no* `drop_id_field` and the NFT contract would have no way of knowing that the +`series` value is malicious. + +This can be prevented if a new field is introduced representing what was automatically injected by the Keypom contract itself. At the +end of the day, Keypom will **always** send correct information to the receiving contracts. If those contracts have a way to know what has +been sent by Keypom and what has been manually set by users, the problem is solved. In the above scenario, the NFT contract would simply add +an assertion that the `keypom_args` had the `account_id_field` set to `Some(series)` meaning that the incoming `series` field was set by Keypom +and not by a malicious user. + +## Use Cases + +Function call drops are the bread and butter of the Keypom contract. They are the most powerful and complex drops that can currently be created. +With this complexity, there are an almost infinite number of use-cases that arise. + +### Proof of Attendance Protocols + +A very common use case in the space is what's known as Proof of Attendance. Often times when people go to events, they want a way to prove +that they were there. Some traditional approaches would be to submit your wallet address and you would be sent an NFT or some other form of +proof at a later date. The problem with this is that it has a very high barrier to entry. Not everyone has a wallet. + +With Keypom, you can create a function call drop that allows people to onboard onto NEAR if they don't have a wallet or if they do, they can +simply use that. As part of the onboarding / claiming process, they would receive some sort of proof of attendance such as an NFT. This can +be lazy minted on-demand such that storage isn't paid up-front for all the tokens. + +At this point, the event organizers or the funder can distribute links to people that attend the event in-person. These links would then be +claimed by users and they would receive the proof of attendance. + +### Auto Registration into DAOs + +DAOs are a raging topic in crypto. The problem with DAOs, however, is there is a barrier to entry for users that aren't familiar with the +specific chain they're built on top of. Users might not have wallets or understand how to interact with contracts. On the contrary, they +might be very well versed or immersed in the DAO's topics. They shouldn't be required to create a wallet and learn the onboarding process. + +With Keypom, you can create a function call drop with the main purpose of registering users into a DAO. For people that have a wallet, +this will act as an easy way of registering them with the click of a link. For users that don't have a wallet and are unfamiliar with +NEAR, they can be onboarded and registered into the DAO with the same click of a link. + +### Multisig Contracts + +Another amazing use-case for Keypom is allowing multisig contracts to have ZERO barrier to entry. Often times when using a multisig contract, +you will entrust a key to a trusted party. This party might have no idea what NEAR is or how to interact with your contract. With Keypom, +you can create a drop that will allow them to sign their transaction with a click of a link. No NEAR wallet is needed and no knowledge of the +chain is required. + +At the end of the day, from the users perspective, they are given a link and when they click it, their portion of the multisig transaction is +signed. The action is only performed on the multisig contract once all links have been clicked. This is an extremely powerful way of doing +accomplishing multisig transactions with zero barrier to entry. + +The users don't even need to create a new account. They can simply call `claim` when the link is clicked which will fire the cross-contract call +to the multisig contract and pass in the keypom arguments that will be cross-checked by that contract. + +### NFT Ticketing + +The problem with current NFT ticketing systems is that they require users to have a wallet. This is a huge barrier to entry for people that +are attending events but don't have wallets. In addition, there is often no proof of attendance for the event as the NFT is burned in order +to get into the event which requires an internet connection. + +Keypom aims to solve these problems by having a ticketing system that has the following features. +* Users are not required to have a wallet to enter the event. +* Each ticket is unique and can only be used by one person. +* Attendees are not required to have wifi to gain entry to the event. +* Attendees that did not have a NEAR wallet can get one for free. +* Attendees can choose to receive an NFT proving their attendance at the event. This is commonly known as a [POAP](https://academy.binance.com/en/glossary/proof-of-attendance-protocol-poap). + +In addition, some way to provide analytics to event organizers that contains information such as links that were: +- Given out but not clicked at all. +- Clicked but not attended. +- Partially claimed indicating the number of people that attended but did not onboard or receive a POAP. +- Fully claimed indicating the number of people that attended and received a POAP. + +In order to accomplish this, you can create a drop that has 3 uses per key. These uses would be: +1. Array(`null`) +2. Array(`null`) +3. Array(function call to POAP contract to lazy mint an NFT) + +The event organizer would create the links and distribute them to people however they see fit. When a user receives the link, the first +claim is automatically fired. This is a `null` case so nothing happens except for the fact that the key uses are decremented. At this point, +the organizer knows that the user has clicked the link since the uses have been decremented. + +The next claim happens **only** when the user is at the door. Keypom would expose a QR code that can only be scanned by the host's phone. +This QR code would appear once the first link is clicked and contains the private key for the link. At the event, they wouldn't need any wifi +to get in as they only need to show the host the QR code. Once the host scans it, the site would ensure that they have exactly 2 out of +the 3 uses left. If they don't, they're not let in. At that point, a use is decremented from the key and the next time they visit the +ticket page (when they have internet), they would be able to claim the final use and be onboarded / receive a POAP. + +

ticketing

\ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/ft-drops.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/ft-drops.md new file mode 100644 index 00000000..1c3613b9 --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/ft-drops.md @@ -0,0 +1,92 @@ +--- +sidebar_label: 'Fungible Token Drops' +sidebar_position: 4 +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Fungible Token Drops + +A Fungible Token drop is also a light wrapper around the simple drop. It works very similarly to how its NFT +counterpart does. First, you'll need to create the drop and then you can fund it with assets and register +key uses. + +You can preload a drop with as many FTs as you'd like even if you don't have the keys yet. This will spike the +`registered_uses` and then you can create keys and slowly eat away from this "total supply" overtime. If the +drop runs out, you can send it more FTs to top up. All the keys in the FT drop will share from this supply +and every time a key is used, the `registered_uses` will decrement and the "total supply" will get smaller. + +## How does it work? + +As mentioned in the NFT section, every drop has a field known as `registered_uses`. This tells the contract +how many uses the drop has across all its keys. For simple drops, this field doesn't matter since all the uses +are paid for up-front when the drop is created or when keys are added. With FT drops, however, +there is a 2 step process: +- Firstly, the drop is created and all the $NEAR required is pre-paid for. This is the same as +simple drops, however, the `registered_uses` are set to 0. +- Once the drop is created, the owner must send the contract the FTs in order for keys to be +usable. This process is done through the `ft_transfer_call` workflow baked into the FT standards. +It's up to the owner to facilitate this process. + +## FT Config + +Along with the default global configurations for drops, if you'd like to create a FT drop, +you must specify the following pieces of information when the drop is created. + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/e8c43f4219a79afb3c367296cc90b8d5de977945/src/lib/types/ft.ts#L4-L23 +``` + + + + +```rust reference +https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/models/json_types.rs#L119-L123 +``` + + + + + +By specifying this information, the drop is locked into only accepting FTs coming from the sender and contract. While +you can send as many FTs as you'd like and can over-pay, you *must* send at **least** enough FTs in one call to cover +1 use. As an example, if a drop is created such that 10 FTs will be sent when a key is used, you must send **at least 10** +and cannot break it up into separate calls where you send 5 one time and 5 another. + +## Use Cases + +FT drops have some awesome flexibility due to the fact that they support all the functionalities of the Simple drops, just with +more use-cases and possibilities. Let's look at some use cases to see how fungible token drops can be used. + +### Recurring Payments + +Recurring payments are quite a common situation. Let's say you need to send someone $50 USDC every week. You +could create a key with 5 claims that has a claim_interval` of 1 week. You would then pre-load maybe the +first week's deposit of $50 USDC and register 1 use or you could send $500 USDC for the first 10 weeks. At that +point, you would simply hand over the key to the user and they can claim once a week. + +### Backend Servers + +Taking the recurring payments problem to another level, imagine that instead of leaving the claims up to the +contractor, you wanted to automatically pay them through a backend server. They would give you their NEAR account +and you would send them FTs. The problem is that you don't want to expose your full access key in the server. +By creating a FT drop, you can store **only the function call access key** created by Keypom in the server. +Your backend would them use the key to call the `claim` function and pass in the user's account ID to send +them the FTs. + +### Creating a Wallet with FTs + +Another awesome use-case is to allow users to be onboarded onto NEAR and **also** receive FTs. As an example, +You could do a promotion where you're giving away $10 USDC to the first 100 users that sign up to your mailing +list. You can also give away QR codes at events that contain a new fungible token that you're launching. You can +simply create a FT drop and pre-load it with the FT of your choice. In addition, you can give it 0.02 $NEAR for +new wallets that are created. + +You can pair this with setting the `on_claim_refund_deposit` flag to true which would make it so that if anyone claims +the fungible tokens and they *already have a wallet*, it will automatically refund you the 0.02 $NEAR. That money should +only be used for the creation of new wallets. Since your focus is on the fungible tokens, you don't want to **force users** +to create a new wallet if they have one already by specifying the claim permission to be `CreateAccountAndClaim` but instead, +you want to be refunded in case they do. diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/introduction.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/introduction.md new file mode 100644 index 00000000..9ceb2c7c --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/introduction.md @@ -0,0 +1,63 @@ +--- +sidebar_label: "Overview" +--- +# Types of Drops +There are **four** types of drops, each with different types of assets. These drops can be claimed either with a brand new NEAR account or an existing one. + + +| Drop Type Assets | +| ------------------------------------------ | ------------------------------------------ | +| [Simple Drop](simple-drops.md) | $NEAR | +| [Non-Fungible Token Drop](nft-drops.md) | NFT and optionally $NEAR | +| [Fungible Token Drop](ft-drops.md) | Fungible Tokens and optionally $NEAR | +| [Function Call Drop](fc-drops.md) | Set of function-calls and optionally $NEAR | + +Continue your learning journey with any of the pages below + +
+
+
+ +
+
+

Simple Drop

+

Onboarding with $NEAR.

+
+
+ +
+
+ +
+
+

Non-Fungible Token Drops

+

Share an NFT with a link

+
+
+ +
+
+
+
+ +
+
+

Fungible Token Drop

+

Send users FTs

+
+
+ +
+
+ +
+
+

Function Call Drops

+

Onboard with Keypom's most powerful drop

+
+
+ +
+
+
+

diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/nft-drops.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/nft-drops.md new file mode 100644 index 00000000..3e9cb72f --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/nft-drops.md @@ -0,0 +1,64 @@ +--- +sidebar_label: 'Non Fungible Token Drops' +sidebar_position: 3 +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Non-Fungible Token Drops + +Non-Fungible Token drops are a special type that allows users to "preload" the drop with NFTs. +These tokens will then be *automatically* sent to the **claiming user**. The claiming flow +is fairly similar to simple drops in that users can either create an account or claim to an +existing one. + +NFT drops are essentially a wrapper around simple drops. All the functionalities that simple +drops have are carried over but now, users can receive an NFT as well as $NEAR. This brings +introduces some customization and uniqueness to the use-cases. + +## How does it work? + +Every drop has a field known as `registered_uses`. This tells the contract how many uses the +drop has across all its keys. For simple drops, this field doesn't matter since all the uses +are paid for up-front when the drop is created or when keys are added. With NFT drops, however, +there is a 2 step process: +- Firstly, the drop is created and all the $NEAR required is pre-paid for. This is the same as +simple drops, however, the `registered_uses` are set to 0. +- Once the drop is created, the owner must send the contract the NFTs in order for keys to be +usable. This process is done through the `nft_transfer_call` workflow baked into the NFT standards. +It's up to the owner to facilitate this process. + +Whenever the contract receives tokens, it will push the ID to a vector. These IDs are **popped** off +whenever a key is used. A user will receive the most recent token sent to the contract as the +vector is acting like a *stack*. + +## NFT Config + +Along with the default global configurations for drops, if you'd like to create an NFT drop, +you must specify the following pieces of information when the drop is created. + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/e8c43f4219a79afb3c367296cc90b8d5de977945/src/lib/types/nft.ts#L4-L15 +``` + + + + +```rust reference +https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/models/json_types.rs#L78-L81 +``` + + + + +By specifying this information, the drop is locked into only accepting NFTs from the sender and contract. + +## Use Cases + +NFT drops work really well for when you want to send a *pre-existing* NFT to a user along with +some $NEAR. Since NFT drops are a light wrapper around simple drops, most of the use-cases are +the same although people can now get NFTs as well. This means you can onboard a user with some +$NEAR **and** they *get an NFT* too. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/sale-customization.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/sale-customization.md new file mode 100644 index 00000000..0d0f94f2 --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/sale-customization.md @@ -0,0 +1,158 @@ +--- +sidebar_label: 'Public Sale Configurations' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Public Sale Configurations +The public sale configuration gives the funder the ability to sell access keys in their drop with a variety of configurable behaviors such as the price, or a dedicated allowlist. + +## Use cases +Public sales of access keys allow for a wide range of easier to create and more interactive events. This is done by letting you: +* Set up an extremely cheap, exclusive event. This event can host an infinite amount of people and the cost of ticketing would be ~0.05 $NEAR. +* Sell access to gated function calls. For example, you can have an exclusive guest-book contract where users that signed it gained access to a VIP meet and greet with a famous artist. +* Introduce FIAT payments for your users when they purchase an access key; opening up your tickets, onboardings, and NFT drops to a whole new audience. + + +The sale configurations are outlined below. + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/29c10f949f02f673d4a3cecc21b0f74bca600075/src/lib/types/drops.ts#L159-L187 +``` + + + + +```rust reference +https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/models/json_types.rs#L86-L113 +``` + + + + +--- + +## Maximum Number of Keys +*Default: None* + +The `max_num_keys` parameter dictates the maximum number of keys that can be added to a drop. By default, there is no limit. Using this can help create scarcity, or abide by venue capacities. + +### Use case +Pretend you are hosting an exclusive talk for your dApp and want to limit the attendance 1000 people. + +In this scenario, you could configure the drop to have `max_num_keys = 1000` in order to ensure any keys beyond 1000 cannot be bought and added to the drop. + +--- + +## Price per Key +*Default: None, the keys are free* + +This `price_per_key` parameter defines the price for purchasing a key. + +### Use case +This parameter can be changed based on your needs. For example, if you are running a charity event and want to bring in as many attendees as possible, you would leave both `price_per_key = 0` and `max_num_keys` undefined. This would mean there is no limit on the number of *free* keys that can be added to the drop. + +Alternatively, if you are looking to earn money with your event, you can choose to set `price_per_key` to whatever you see fit. This value is expressed in yoctoNEAR. + +--- + +## Allowlist +*Default: None, anyone can add keys to the drop* + +`Allowlist` specifies a group of users that can add keys to the drop using their `accountID`. For example, if `allowlist = [benji.testnet, minqi.testnet]`, then only `benji.testnet` and `minqi.testnet` can add keys to the drop. + +If left undefined, anybody can add keys to the drop. + +### Use case +In this example, pretend you are running a concert for only your closest friends. To do this, you would set `allowlist` to be a vector of their NEAR `accountID`'s. This way, you can take comfort in knowing that your friends will be the only ones with tickets to the event. + +--- + +## Blocklist +*Default: None, nobody is blocked* + +Contrary to the `allowlist`, the `blocklist` specifies those that are blocked from adding keys to the drop. This is empty by default, meaning nobody is blocked. + +Note that the `blocklist` takes precedent over the `allowlist`. This means that if you are on both lists, you will be blocked. + +### Use case +Lets pretend that you are running a concert but there are known ticket scalpers in the community. To prevent keys from being scalped and ensure your true fans get tickets to your concert, you can add the NEAR `accountID`'s of the scalpers to the `blocklist` vector. + +--- + +## Auto-Withdraw Funds +*Default: False, revenues go to funder's Keypom Balance* + +The `auto_withdraw_funds` parameter dictates where revenue from key sales will go. Every time a key is sold, the revenue will automatically be sent to one of two places: + +1. the funder's Keypom balance +2. the funder's NEAR wallet + +By default, the revenue will go to the funder's Keypom balance. If `auto_withdraw_funds = true`, the revenue generated will be sent to the funder's NEAR wallet. + +### Use case +Let's say you are an event promoter who is new to NEAR. You realize that you are only going to use Keypom for a single event. + +In this scenario, rather than sending revenues to your Keypom balance and then needing to manually withdraw it once the event is over, you can set `auto_withdraw_funds = true` while creating the drop in order to guarantee that the revenues will go to your NEAR wallet automatically. + +--- + +## Start +*Default: None, keys can be added immediately* + +The `start` parameter dictates when keys can be purchased and added to the drop. Similar to [time configurations](time-customization.md), this is measured in non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. A sample configuration is made available below. + +### Use case +Pretend you are an event coordinator for a popular event and have a limited capacity. To ensure fairness, you set a date and time for the sale to begin and let all your users know. + +To do this, you can configure the `start` parameter. + +--- + +## End +*Default: None, keys can be added indefinitely* + +The `end` parameter defines when keys can no longer be purchased and added to the drop. + +### Use case +For an upcoming event, you want to create a pre-sale of tickets for dedicated fans. To do this you can create a drop, separate from the main ticket sale, that begins early and ends before the general admission tickets go on sale. + +To do this, you can configure the `end` parameter. + +--- + + +## Example Public Sale Configuration + +```ts +const ONE_SECOND_NS = 1e9; + +pub_sale: { + // Maximum of 100 Keys + max_num_key: 100, + + // 1 $NEAR per key + price_per_key: parseNearAmount("1"), + + // only allow benji.testnet and minqi.testnet to add keys + allowlist: ["benji.testnet", "minqi.testnet"], + + // don't allow boogieman.testnet to add keys + blocklist: ["boogieman.testnet"], + + // send revenue back to funder's NEAR wallet + auto_withdraw_funds: true, + + // start 5 minutes from now + start: (Date.now() * 1000000) + ONE_SECOND_NS * 300, + + // end 15 minutes from now + end: (Date.now() * 1000000) + ONE_SECOND_NS * 900 +} + +``` + + diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/simple-drops.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/simple-drops.md new file mode 100644 index 00000000..9272132d --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/simple-drops.md @@ -0,0 +1,37 @@ +--- +sidebar_label: 'Simple Drops' +sidebar_position: 2 +--- + +# Simple Drops + +The most basic type of drop is the simple kind. Any keys that are part of a simple drop can +only be used for 1 thing: **transferring $NEAR**. Once the key is claimed, the claiming account +will receive the $NEAR specified in the `deposit_per_use`. Simple drops are a great way to send $NEAR to claiming accounts while not storing a lot +of information on the contract. Below are a couple use cases. + +## Backend Servers + +Let's say you have a backend server that should send 10 $NEAR to the first 3 +people that redeem an NFT. Rather than exposing your full access key in the backend server, +you could create a simple drop that either has 3 keys or 1 key that is claimable 3 times. +In the drop, you'd specify that each time the key is claimed, the specified account would +receive 10 $NEAR. + +## Recurring Payments + +Recurring payments are quite a common situation. If you need to send someone 10 $NEAR once a +month for 6 months, you could create a simple drop that has a `claim_interval` of 1 month with +a `start_timestamp` of next week. Every time the key is used, 10 $NEAR is sent to the account. If +the contractor missed a month's payment, they can claim the key late but can never use the key more +than what is intended. + +

recurring payments

+ +## Quick Onboarding + +If you need to quickly onboard users onto NEAR, you could create a simple drop with a +small amount of $NEAR (enough to create a wallet) and set the claim permission to be +`CreateAccountAndClaim`. This means that the key can only be used to create accounts. +You can then add keys as you wish to the drop and give them out to users so they can create +accounts and be onboarded onto NEAR. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/time-customization.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/time-customization.md new file mode 100644 index 00000000..aeb8a79d --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/time-customization.md @@ -0,0 +1,109 @@ +--- +sidebar_label: 'Time Configurations' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Time Configurations +Time configurations are particularly useful in defining limits on ***when*** a key may be used. This can have a wide range of applications from [Subscriptions](../../../../Tutorials/Advanced/subscriptions/introduction.md) to [Ticketing](../../../../Tutorials/Advanced/ticketing/introduction.md). + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/29c10f949f02f673d4a3cecc21b0f74bca600075/src/lib/types/drops.ts#L87-L112 +``` + + + + +```rust reference +https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/models/drop_model.rs#L89-L108 +``` + + + +:::tip +All these time parameters are measured in non-leap-nanoseconds and can be tricky to work with. An example struct has been provided [below](time-customization.md). +::: + + +--- + +## Start +*Default: none, Keys can be used anytime* + +`Start` time is useful for any drops where you intend to restrict access until a certain time. Setting a `start` time effectively sets an activation time; a time where the keys become usable afterwards. Before a `start` time is reached, if a user tries to `claim` the key or use `create_account_and_claim`, it will not work. + +### Use case +Let's say you are running a concert, and you want to give fans exclusive access using preferred and general admission tickets. Those with preferred admission tickets can enter anytime, even when the band is setting up. General admission, on the other hand, may only enter once the band is set up. + +In this case, you would hand out general admission tickets with a start time in the time configurations and another set of preferred admission tickets with an earlier start time in the time configurations. + +To do this, you would need to create two drops, one for preferred admission and another for general admission. This is because, as covered in the [Drop Configurations Introduction](customization-homepage.md), one set of configurations will apply to **all** keys in that drop. + +--- + +## End +*Default: none, Keys can be used anytime* + +The end parameter acts as a deactivation time. This means that once the end time is reached, all the keys in the drop will be deactivated and can no longer be used. + +### Use case +Let's pretend that you are at NEARCON representing an NFT marketplace looking to onboard users onto your platform. Your strategy is to offer an exclusive NFT to users that sign up during NEARCON. + +To do this, you hand out QR codes with an NFT drop embedded in the QR code during the event. To ensure that the users sign up *during* NEARCON, you set the drop configuration's `end` parameter to be the end of NEARCON. + +--- + +## Throttle +*Default: none, Keys can be used anytime* + +The `throttle` parameter controls how much time must pass between key uses. This works great if you want to control how frequently somebody is able to claim their assets. + +### Use case +Pretend you are running an NFT raffle for your latest creation, the MoonNFT. For this raffle, the 20th person claiming their key will be the winner and will receive their own personalized MoonNFT. + +To protect again spam and ensure a fair playing field, you can configure the drop to have a 5 minute cooldown using the `throttle` parameter. This way, a contestant cannot spam claim the key to increase their odds of winning. + +--- + +## Interval +*Default: none, Keys can be used anytime* + +The `interval` parameter is similar to the `throttle` parameter but uses the `start` time as a constant reference. This means if `interval` is every week, the key will become useable on the same day every week, regardless of when the last key use was. + +### Use case +Pretend you have a subscription to Moon's **weekly** dog biscuit delivery service that charges you every Monday. Due to all the horror stories of data breaches and identity theft, you now no longer give out your credit card information. For this reason, you wish to pay with $NEAR but the current linkdrop standard does not allow for a subscription model. + +With Keypom, you can give Moon a multi-use simple drop with a `throttle` parameter set to 2 weeks. This way, Moon will only be able to claim every week, making it a subscription. This is also beneficial in giving a sense of security to Moon, as they can claim later than Monday and know that they will be able to claim again next Monday. + +If, for one week, Moon forgets to claim, he would be able to claim twice the next week. + + +The massive benefit here is that you can have a subscription service in the NEAR ecosystem and never need to expose any of your private information. + + +--- + +## Example Time Configuration + +```ts +const ONE_SECOND_NS = 1e9; + +time: { + // Start time is 30 seconds from now + start: (Date.now() * 1000000) + ONE_SECOND_NS * 30, + + // End time is 5 minutes from start time + end: (Date.now() * 1000000) + ONE_SECOND_NS * 330, + + // Time between use is 15 seconds + throttle: ONE_SECOND_NS * 15, + + // Time after start for first use is 15 seconds + interval: ONE_SECOND_NS * 15, +} +``` + + diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/usage-customization.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/usage-customization.md new file mode 100644 index 00000000..28a0beca --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/usage-customization.md @@ -0,0 +1,85 @@ +--- +sidebar_label: 'Usage Configurations' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Usage Configurations +Usage configurations control behaviors surrounding *how* a key can be used. For example, dictating whether a key can be used to call only `claim`, or `create_account_and_claim`. + + + + +```ts reference +https://github.com/keypom/keypom-js/blob/29c10f949f02f673d4a3cecc21b0f74bca600075/src/lib/types/drops.ts#L117-L154 +``` + + + + +```rust reference +https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/models/drop_model.rs#L142-L154 +``` + + + + +--- + +## Permissions +*Default: `claim` AND `create_account_and_claim`* + +The `permissions` parameter assigns which claim methods the user can call with the key you give them. They can either call both, or just one. + +### Use case +Pretend you are hosting a talk about your NEAR dApp: `Kramerly`. Your only goal is to onboard as many *new* users from the audience as possible. If the user already has a NEAR wallet, they shouldn't be able to claim assets and onboard. This is similar to free-trials in Web2 whereby only new users are able to participate. + +To do this, you can set the `permissions` parameter to `create_account_and_claim`. + +--- + +## Refund Deposit +*Default: False* + +This `refund_deposit` parameter defines whether or not the `deposit_for_use` amount should be refunded to the drop owner if `claim` is called rather than `create_account_and_claim`. + +Part of funding a drop is *optionally* covering the cost for creating a new named account. Sometimes, you might want to sponsor a small amount of $NEAR to cover that cost but it should only be used for account creation. If an account is *not* being created (through calling `create_account_and_claim`, the `deposit_per_use` should be sent back to the funder. + +### Use case +This parameter is usually a helpful mechanism when onboarding large numbers of users onto NEAR. Pretend you are onboarding 100,000 new users. Since they are new, you factor in the storage deposit needed to create the new wallets into your funding costs. After the event, however, it turns out half of the users had existing wallets. + +If `refund_deposit` was true, you would be refunded the `deposit_per_use` that normally would have been sent to the existing NEAR wallets. + +--- + +## Auto-Delete Drop +*Default: False* + +If `auto_delete_drop` is set to `true`, the drop will be deleted once all the keys have been used and deleted. + +### Use case +A great use case is for one-off drops where you don't plan on adding more keys to. By setting `auto_delete_drop` to true, the drop will automatically be deleted once all the keys are used. + +--- + +## Auto-Withdraw +*Default: False* + +This parameter is used to automatically withdraw your Keypom balance once you delete your last drop. + +### Use case +This parameter is useful for users that create 1-off drops and don't want to worry about deleting their drop once it's used or having to manually withdraw their Keypom balance. + +A funder could create a drop and give out keys without ever needing to return back to Keypom. Once the drop is exhausted, it is deleted and the funder's balance is automatically withdrawn. + +Note that this must be used together with `auto_delete_drop`. + +## Account Creation Fields +*Default: None* + +The `account_creation_fields` allows you to specify any arguments to be passed in to `create_account` when creating your account + +### Use case +Pretend you are looking to use Keypom to onboard users and give them custom subaccounts. To ensure that only the people using your drop can create a subaccount, you can add a secret `account_creation_fields` argument to your drop. + +This way, if someone outside of the drop were to try to call `create_account` on your contract, they would need to pass in the secret `account_creation_field` that they would not know. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/contribute.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/contribute.md new file mode 100644 index 00000000..2564aa7d --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/contribute.md @@ -0,0 +1,18 @@ +--- +sidebar_label: 'Contributing' +sidebar_position: 9 +--- +# Contributing + +First off, thanks for taking the time to contribute! Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are **greatly appreciated**. + +Please try to create bug reports that are: + +- _Reproducible._ Include steps to reproduce the problem. +- _Specific._ Include as much detail as possible: which version, what environment, etc. +- _Unique._ Do not duplicate existing opened issues. +- _Scoped to a Single Bug._ One bug per report. + + + +You can use [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) to check for common markdown style inconsistency. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/costs.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/costs.md new file mode 100644 index 00000000..c513cafc --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/costs.md @@ -0,0 +1,62 @@ +--- +sidebar_label: 'Costs' +sidebar_position: 4 +--- +# Costs + +It is important to note that the Keypom contract is 100% **FEE FREE** and will remain that way for the *foreseeable future*. This contract is a public good and is meant to inspire change in the NEAR ecosystem. + +With that being said, there are several mandatory costs that must be taken into account when using Keypom. These costs are broken down into two categories: per key and per drop. + +> **NOTE:** Creating an empty drop and then adding 100 keys in separate calls will incur the same cost as creating a drop with 100 keys in the same call. + +## Per Drop + +When creating an empty drop, there is only one cost to keep in mind regardless of the drop type: +- Storage cost (**~0.006 $NEAR** for simple drops) + +## Per Key +Whenever keys are added to a drop (either when the drop is first created or at a later date), the costs are outlined below. + +### Key Costs for Simple Drop + +- $NEAR sent whenever the key is used (can be 0). +- Access key allowance (**~0.0187 $NEAR per use**). +- Storage for creating access key (**0.001 $NEAR**). +- Storage cost (**~0.006 $NEAR** for simple drops) + +### Additional Costs for NFT Drops + +Since keys aren't registered for use until **after** the contract has received the NFT, we don't know how much storage the token IDs will use on the contract. To combat this, the Keypom contract will automatically measure the storage used up for storing each token ID in the `nft_on_transfer` function and that $NEAR will be taken from the funder's balance. + +### Additional Costs for FT Drops + +Since accounts claiming FTs may or may not be registered on the Fungible Token contract, Keypom will automatically try to register **all** accounts. This means that the drop creators must front the cost of registering users depending on the `storage_balance_bounds` returned from the FT contract. This applies to every use for every key. + +In addition, Keypom must be registered on the FT contract. If you create a FT drop and are the first person to ever do so for a specific FT contract on Keypom, Keypom will be automatically registered when the drop is created. This is a one time cost and once it is done, no other account will need to register Keypom for that specific FT contract. + +### Additional Costs for FC Drops + +Drop creators have a ton of customization available to them when creation Function Call drops. A cost that they might incur is the attached deposit being sent alongside the function call. Keypom will charge creators for all the attached deposits they specify. + +> **NOTE:** The storage costs are dynamically calculated and will vary depending on the information you store on-chain. + +## Deleting Keys and Drops + +Creators have the ability to delete drops and keys at any time. In this case, **all** the initial costs they incurred for the remaining keys will be refunded to them (minus Gas fees of course). + +## Automatic Refunds When Keys are Used + +One way that Keypom optimizes the fee structure is by performing automatic refunds for some of the initial costs that creators pay for when keys are used. All the storage that is freed along with any unused allowance is automatically sent back to the creator whenever a key is used. This model drastically reduces the overall costs of creating drops and creates incentives for the keys to be used. + +## Account Balances for Smooth UX + +In order to make the UX of using Keypom seamless, the contract introduces a debiting account model. All costs and refunds go through your account's balance which is stored on the contract. This balance can be topped up or withdrawn at any moment using the `add_to_balance()` and `withdraw_from_balance()` functions. + +This account balance is not *required*, however. You can create a drop by attaching a deposit to the call. Keep in mind that this will create an account balance for you behind the scenes, however. + + +## Built With + +- [near-sdk-rs](https://github.com/near/near-sdk-rs) +- [near-api-js](https://github.com/near/near-api-js) \ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/licenses.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/licenses.md new file mode 100644 index 00000000..5a641956 --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/licenses.md @@ -0,0 +1,16 @@ +--- +sidebar_label: 'License and Acknowledgments' +sidebar_position: 10 +--- + +# License + +This project is licensed under the **GPL License**. + +# Acknowledgments + +Thanks for these awesome resources that were used during the development of the **Keypom Contract**: + +- +- +- \ No newline at end of file diff --git a/docs/Concepts/KeypomProtocol/GithubReadme/password-protect.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/password-protect.md similarity index 100% rename from docs/Concepts/KeypomProtocol/GithubReadme/password-protect.md rename to versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/password-protect.md diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/querying.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/querying.md new file mode 100644 index 00000000..8fcebdc8 --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/querying.md @@ -0,0 +1,64 @@ +--- +sidebar_label: 'Querying Information from Keypom' +sidebar_position: 7 +--- +# Query Information From Keypom + +Keypom allows users to query a suite of different information from the contract. This information can be broken down into two separate objects that are returned. JsonDrops and JsonKeys. +```rs +pub struct JsonDrop { + // Drop ID for this drop + pub drop_id: DropId, + // owner of this specific drop + pub owner_id: AccountId, + // Balance for all keys of this drop. Can be 0 if specified. + pub deposit_per_use: U128, + // Every drop must have a type + pub drop_type: JsonDropType, + // The drop as a whole can have a config as well + pub config: Option, + // Metadata for the drop + pub metadata: Option, + // How many claims + pub registered_uses: u64, + // Ensure this drop can only be used when the function has the required gas to attach + pub required_gas: Gas, + // Keep track of the next nonce to give out to a key + pub next_key_id: u64, +} + +pub struct JsonKeyInfo { + // Drop ID for the specific drop + pub drop_id: DropId, + pub pk: PublicKey, + // How many uses this key has left. Once 0 is reached, the key is deleted + pub remaining_uses: u64, + // When was the last time the key was used + pub last_used: u64, + // How much allowance does the key have left. When the key is deleted, this is refunded to the funder's balance. + pub allowance: u128, + // Nonce for the current key. + pub key_id: u64, +} +``` + +## Key Specific +- **`get_key_balance(key: PublicKey)`**: Returns the $NEAR that will be sent to the claiming account when the key is used +- **`get_key_total_supply()`**: Returns the total number of keys currently on the contract +- **`get_keys(from_index: Option, limit: Option)`**: Paginate through all keys on the contract and return a vector of key info +- **`get_key_information(key: PublicKey)`**: Return the key info for a specific key +- **`get_key_information_batch(keys: Vec)`**: Return a vector of key info for a set of public keys + +## Drop Specific +- **`get_drop_information(drop_id: Option, key: Option)`**: Return the drop info for a specific drop. This can be queried for by either passing in the drop ID or a public key. +- **`get_key_supply_for_drop(drop_id: DropId)`**: Return the total number of keys for a specific drop +- **`get_keys_for_drop(drop_id: DropId, from_index: Option, limit: Option)`**: Paginate through all keys for a specific drop and return a vector of key info +- **`get_drop_supply_for_owner(account_id: AccountId)`**: Return the total number of drops for a specific account +- **`get_drops_for_owner(account_id: AccountId, from_index: Option, limit: Option)`**: Paginate through all drops for a specific account and return a vector of drop info +- **`get_nft_supply_for_drop(drop_id: DropId)`**: Get the total number of NFTs registered for a given drop. +- **`get_nft_token_ids_for_drop(drop_id: DropId, from_index: Option, limit: Option)`**: Paginate through token IDs for a given drop +- **`get_next_drop_id()`**: Get the next drop ID that will be used for a new drop + +### Utility +- **`get_root_account()`**: Get the global root account that all created accounts with be based off. +- **`get_user_balance()`**: Get the current user balance for a specific account. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/testing.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/testing.md new file mode 100644 index 00000000..6864a165 --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/GithubReadme/testing.md @@ -0,0 +1,30 @@ +--- +sidebar_label: 'Keypom Tests' +sidebar_position: 8 +--- +# Running the Keypom Tests + +We have put together a suite of test cases that can be found in the `__tests__` folder. These range anywhere from simple config tests all the way to full blown ticketing and POAPs. + +In the `__tests__` folder, there are sub-folders with each type of test. Some of these sub-folders contain a `utils` folder with some utility functions used. + +All the tests use `workspaces-js`. In order to run all the tests, run the following command. + +```bash +yarn && yarn test +``` + +This will run through each test 1 by 1. If you wish to only run a set of specific tests, the full list of commands can be found below. + +```bash +"test:internals" +"test:stage1" +"test:stage1:simple" +"test:ticketing" +"test:poaps" +"test:configs" +"test:nft-drops" +"test:ft-drops" +"test:profiling" +"test:passwords" +``` \ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/balances.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/balances.md new file mode 100644 index 00000000..01ebbe78 --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/balances.md @@ -0,0 +1,77 @@ +--- +sidebar_label: 'Keypom Balances' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Keypom Balances +## What is a Keypom Balance? +Let's put on our imagination caps for a second; pretend you're an event host and you are in charge of ticketing for numerous events. You deduce that for the sake of organization, the best approach would be to create separate drops for separate events. + +Being the busy event organizer that you are, sometimes you need to create these drops and keys while on the road. As we can see in the [basic tutorials](../../Tutorials/Basics/simple-drops.md), you need to attach a deposit to every one of your function calls: every time you create a drop, add keys, delete keys etc. This can be a real headache for a busy event organizer! + +This is where the concept of a **Keypom Balance** comes in real handy! + +Every account that uses Keypom carries an internal balance (in $NEAR) on the Keypom contract. Effectively, the Keypom balance is similar to a debit card. You can overload your balance and sip from it as you interact with the contract. + +Let's go back to your event organizer persona; this Keypom Balance allows you to simply preload your "debit card" with loads of $NEAR and then go about your business without needing to worry about transferring $NEAR for ever function call! +## Interacting with Balances +There are a few functions that you can use to interact with your Keypom balance. Let's quickly run through their meanings, and then show some examples! + + + + +```ts +// Deposit some amount of $NEAR or yoctoNEAR$ into the Keypom contract. This amount can then be used to create drops or add keys without having to explicitly attach a deposit every time. It can be thought of like a bank account. +export const addToBalance{ + /** Account object that if passed in, will be used to sign the txn instead of the funder account. */ + account?: Account, + /** If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. */ + wallet?: AnyWallet, + /** Amount of tokens to add but considering the decimal amount (non human-readable). + Transferring one $NEAR should be passed in as "1000000000000000000000000" and NOT "1" */ + amountYocto?: string + /** Human readable format for the amount of tokens to add. + Transferring one $NEAR should be passed in as "1" and NOT "1000000000000000000000000" */ + amountNear?: string, + /** When signing with a wallet, a success URl can be included that the user will be redirected to once the transaction has been successfully signed. */ + successUrl?: string +} + +// Withdraw your balance back into your wallet. +export const withdrawBalance { + /** Account object that if passed in, will be used to sign the txn instead of the funder account. */ + account?: Account, + /** If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. */ + wallet?: AnyWallet, +} + +//This allows you to view your own or other people's Keypom balance. This can be useful to determine +//if you need to top up if you are on the verge of creating a large drop +export const getUserBalance{ + accountId: string +} +``` + + + + +```rust +// Deposit some amount of $NEAR or yoctoNEAR$ into the Keypom contract. This amount can then be used to create drops or add keys without having to explicitly attach a deposit every time. It can be thought of like a bank account. +pub fn add_to_balance(&mut self) + +// Allows users to withdraw their balance +pub fn withdraw_from_balance(&mut self) + +// Return the current balance for a given account +pub fn get_user_balance(&self, account_id: AccountId) -> U128 +``` + + + + + + +For example, Alice wants to add 10 $NEAR to her Keypom balance. She will do this by calling `addToBalance` and transferring 10 $NEAR to the Keypom contract. Then, if Alice wants to create a drop that costs her 5 $NEAR, she can simply create the drop and Keypom will automatically deduct from her internal Keypom balance rather than needing to transfer 5 $NEAR to the contract. + +Once she has created the drop, she can check her balance using `getUserBalance`, which will return 5 $NEAR. Then, she can withdraw this 5 $NEAR into her NEAR wallet; this will cause her Keypom balance to go down to 0 $NEAR. diff --git a/versioned_docs/version-2.0/Concepts/KeypomProtocol/overview.md b/versioned_docs/version-2.0/Concepts/KeypomProtocol/overview.md new file mode 100644 index 00000000..522ad55c --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/KeypomProtocol/overview.md @@ -0,0 +1,74 @@ +--- +sidebar_label: 'Introduction to Keypom' +sidebar_position: 1 +--- +# Introduction to Keypom +> To view our debut talk at NEARCON 2022, click [here](https://www.youtube.com/watch?v=J-BOnfhHV50). + +Keypom is an access key factory created as a result of 3 common problems that arose in the ecosystem. + +1. People want a *cheap, customizable, and unique* onboarding experience for users. +2. Companies don't want to expose **full access keys** in their backend servers. +3. dApps want a *smooth UX* with zero barrier to entry onboarding. + +The contract was initially created as a way to handle the 1 $NEAR minimum deposit required for creating linkdrops using the [regular linkdrop contract](https://github.com/near/near-linkdrop/blob/f24f2608e1558db773f2408a28849d330abb3881/src/lib.rs#L18). + +If users wanted to create linkdrops, they needed to attach a **minimum** of 1 $NEAR. This made it costly and unscalable for projects that wanted to mass onboard onto NEAR. Keypom, on the other hand, has been highly optimized to allow for the lowest possible costs. + +## Problem + +Blockchain technology comes with many benefits such as sovereign ownership, digital rights, privacy, freedom, +peer to peer coordination and much more. The problem with this technology, however, is that there is an extremely +high barrier to entry for an everyday individual. None of it matters if nobody can onboard. + +Itโ€™s confusing to create and fund a crypto wallet. People are unfamiliar with the process, technical jargon, +and the general flow. NEARโ€™s account model is powerful, but extremely underutilized because itโ€™s complex for +developers to take full advantage of. Keypom wraps this up in a single API call. + +With NEARโ€™s goal of onboarding 1 billion users to Web3, there needs to be a solution to this high barrier to +entry for developers building on NEAR and users onboarding to their apps and the NEAR ecosystem. + +Below is a table outlining the minimum costs to onboard a new user onto NEAR with a named account. + +| | 1 Account | 1,000 Accounts | 1,000,000 Accounts | +|----------------------|-----------------|-----------------|--------------------| +| Traditional Linkdrop | ~1 NEAR | ~1,003 NEAR | ~1,002,840 NEAR | +| Keypom | ~0.0035 NEAR | ~3.5 NEAR | ~3,500 NEAR | +| | ~99.65% Cheaper | ~99.65% Cheaper | ~99.65% Cheaper | + +Keypom allows anyone to create highly customizable onboarding experiences for their users. These experiences +can be both for new, or existing users. If someone already has a wallet, they can still use a Keypom link to +experience an app, and then transfer the assets later. + +## Comparable Solutions + +| | **Keypom** | **NEAR Drop** | **Satori** | +|----------------------------------------------|------------|---------------|------------| +| NEAR Drop | โœ… | โœ… | โŒ | +| FT Drop | โœ… | โŒ | โŒ | +| NFT Drop | โœ… | โŒ | โœ… | +| Function Call Drop | โœ… | โŒ | โŒ | +| Embeddable in Dapps | โœ… | โŒ | โŒ | +| Wallet Selector Integration | โœ… | โŒ | โŒ | +| No Fee | โœ… | Maybe? | โŒ | +| No Backend / 3rd Party | โœ… | โœ… | โŒ | +| Campaigns | โœ… | โœ… | โœ… | +| Multi-Step e.g. Tickets click > scan > claim | โœ… | โŒ | โŒ | +| Password Protected Drops | โœ… | โŒ | โŒ | +| Timed Drops e.g. recurring payments | โœ… | โŒ | โŒ | +| Custom Names e.g. user.myapp.near | โœ… | โŒ | โŒ | + +# Our Solution + +Keypom allows for the creation of highly customizable access keys. These keys can be thought of as having their +own *smart contracts*. Each access key derives from what's known as a *drop*. These drops outline the different +functionalities and behaviors the key will have. A drop can be thought of as a bucket that access keys belong to. +You can create many different buckets and fill them each with their own keys. Each key will act in accordance to the +drop, or bucket, it belongs to. + +A drop can be one of four different types: + +1. Simple drop. +2. Non Fungible Token drop. +3. Fungible Token drop. +4. Function Call drop. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/LinkdropsAndAccessKeys/linkdrop-basics.md b/versioned_docs/version-2.0/Concepts/LinkdropsAndAccessKeys/linkdrop-basics.md new file mode 100644 index 00000000..6a4bda67 --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/LinkdropsAndAccessKeys/linkdrop-basics.md @@ -0,0 +1,28 @@ +--- +sidebar_label: 'Linkdrop Basics' +sidebar_position: 5 +--- +# How Linkdrops Work + +For some background as to how linkdrops works on NEAR: + +*The funder that has an account and some $NEAR:* +- creates a keypair locally `(pubKey1, privKey1)`. The blockchain doesn't know of this key's existence yet since it's all local for now. +- 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. +- Funder will then create a link to send to someone that contains this `privKey1`. The link follows the following 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. + +*The receiver of the link that is claiming the linkdrop:* +- Receives the link which includes `privKey1` and sends them to the NEAR wallet. +- Wallet creates a new keypair `(pubKey2, privKey2)` locally. The blockchain doesn't know of this key's existence yet since it's all local for now. +- Receiver will then choose an account ID such as `new_account.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 pre-loaded. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/LinkdropsAndAccessKeys/near-access-keys.md b/versioned_docs/version-2.0/Concepts/LinkdropsAndAccessKeys/near-access-keys.md new file mode 100644 index 00000000..086310ef --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/LinkdropsAndAccessKeys/near-access-keys.md @@ -0,0 +1,13 @@ +--- +sidebar_label: 'NEAR Access Key Model' +sidebar_position: 1 +--- +# NEAR Access Key Model + +A Keypair is generated locally and the pubkey is add to your account. + +Access keys with numerous types are unique to NEAR. There are Full Access (similar to traditional keypairs) and Function Call Access Keys. These Function Call Access Keys can only call specified accounts and methods. It cannot be used to send any NEAR, deploy a contract, create an account etc. + +This means the Function Call Access key can be used as a throwaway key. + +Your account can have any number of Access Keys, including ZERO. If there are zero, the account cannot deploy or withdraw funds (rugging). This is done as a form of trust for users. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Concepts/welcome.md b/versioned_docs/version-2.0/Concepts/welcome.md new file mode 100644 index 00000000..6c662dbf --- /dev/null +++ b/versioned_docs/version-2.0/Concepts/welcome.md @@ -0,0 +1,106 @@ +--- +sidebar_label: 'Home' +--- +# Concepts +Welcome to the concepts section of Keypom's developer documentation. Here you'll learn all about Keypom. + +## Major Concepts + +
+
+
+ +
+
+

Types of Drops

+

Learn about types of Keypom drops.

+
+
+ +
+
+ +
+
+

Drop Configurations

+

Customize your drops.

+
+
+ +
+
+
+
+ +
+
+

Keypom Balances

+

See how Keypom Balances can save you time.

+
+
+ +
+
+ +
+
+

Costs

+

Find out about Keypom's low costs.

+
+
+ +
+
+
+

+ +## Other Resources + +Here are some additional resources, and references. These may help you deepen your understanding or clarify any issues. + +
+
+
+ +
+
+

Source Code

+

Explore Keypom's smart contracts.

+
+
+ +
+
+ +
+
+

Keypom JavaScript SDK

+

Delve into the source code of the SDK.

+
+
+ +
+
+
+
+ +
+
+

NEAR Docs

+

Documentation and Tutorials for NEAR.

+
+
+ +
+
+ +
+
+

Nomicon

+

Concepts and Standards on NEAR.

+
+
+ +
+
+
\ No newline at end of file diff --git a/versioned_docs/version-2.0/Cookbook/balances.md b/versioned_docs/version-2.0/Cookbook/balances.md new file mode 100644 index 00000000..8ee7cd73 --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/balances.md @@ -0,0 +1,75 @@ +--- +sidebar_label: 'Balances' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Balances +This part of the cookbook contains everything related to Keypom balances. This balance acts like a debit card, where you deposit $NEAR up front and create drop and interact with Keypom without needing to attach deposits to everything you do. For more on balances, see [here](../Concepts/KeypomProtocol/balances.md). +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +Ensure that you have initialized Keypom using the `initKeypom` function prior to running any of the SDK examples. For more info on this, see the [introduction page](welcome.md#connection-to-near-and-initializing-the-sdk) +::: + +## Viewing User Keypom Balances +To view your Keypom balance, you can use the following. This will allow you to decipher if you need to add more $NEAR to your balance before creating a drop. + + + + +```js +// Query for the drop information for a specific drop +const userBal = await getUserBalance({ + accountId: "benjiman.testnet", +}) + +console.log('userBal: ', userBal) +``` + + + + + +___ +## Adding to Keypom Balances +If you don't have sufficient funds to create your drop, you may add more $NEAR to your balance using the following. When specifying the amount to add, you can use `amountNear` or `amountYocto` to add in NEAR or yoctoNEAR respectively. + + + + +```js +await addToBalance({ + account: fundingAccount, + amountNear: "5" +}); +``` + + + + + +___ + +## Withdrawing from Keypom Balance +If you are confident you no longer need Keypom or simply wish to withdraw your Keypom balance back into your NEAR wallet, you can use the following: + + + + +```js +await withdrawBalance({ + account: fundingAccount +}) +``` + + + + + +___ + diff --git a/versioned_docs/version-2.0/Cookbook/drops/NEAR.md b/versioned_docs/version-2.0/Cookbook/drops/NEAR.md new file mode 100644 index 00000000..7ec4112c --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/drops/NEAR.md @@ -0,0 +1,109 @@ +--- +sidebar_label: 'Simple NEAR Drops' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Simple NEAR Drops +This part of the cookbook contains a quick guide on the simple NEAR drop. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +These scripts will not run without the proper setup shown in the [introduction page](../welcome.md#connection-to-near-and-initializing-the-sdk). +::: + +## Creating a Simple Drop +A drop is the fundamental building block of Keypom. It is a collection of access keys that all share the same properties. A simple drop allows you to send $NEAR by sharing those access keys in the form of a linkdrop. + + + + +```js +// Creating drop with 2 single use keys +const {keys} = await createDrop({ + account: fundingAccount, + numKeys: 2, + depositPerUseNEAR: "0.1", +}); + +console.log(keys) +``` + + + + +:::caution +`createDrop` is limited to adding 50 password protected keys or 100 non-protected keys at a time. To add more keys, see the [large drops](#creating-a-large-drop) example below. +::: + +___ + +## Creating a Large Drop +Adding keys, either using `createDrop` or `addKeys` is limited to 50 password protected or 100 non-protected keys. To bypass this, the drop can be created first and then the keys can be added by looping `addKeys`. + + + + +```js +// Creating drop with 0 single use keys +let {dropId} = await createDrop({ + account: fundingAccount, + depositPerUseNEAR: "0.001", +}); + +let numKeys = 200 +let keysAdded = 0; +let allSecretKeys = []; +while (keysAdded < numKeys) { + const keysToAdd = Math.min(50, numKeys - keysAdded); + const {secretKeys, publicKeys} = await generateKeys({ + numKeys: keysToAdd, + }); + await addKeys({ + account: fundingAccount, + dropId, + publicKeys + }); + keysAdded += keysToAdd; + allSecretKeys = allSecretKeys.concat(secretKeys); +} +``` + + + + + +___ + +## Delete Drop +A drop can be deleted manually at any time using `deleteDrops`. This will refund all unclaimed key balances back to the drop funder's Keypom balance. + + + + +```js +// Get all the drops for a given user +let drops = await getDrops({accountId: "minqi.testnet"}); + +// Delete all the drops currently funded by `minqi.testnet` +await deleteDrops({ + account: fundingAccount, + drops +}) + +// Delete 2 seperate drops given their IDs +await deleteDrops({ + account: fundingAccount, + dropIds: ["123123123123123", "12391238012380123"] +}) +``` + + + + + +___ diff --git a/versioned_docs/version-2.0/Cookbook/drops/customizations/dropConfig.md b/versioned_docs/version-2.0/Cookbook/drops/customizations/dropConfig.md new file mode 100644 index 00000000..32ecafd0 --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/drops/customizations/dropConfig.md @@ -0,0 +1,81 @@ +--- +sidebar_label: 'Drop Configurations' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Drop Configurations +This part of the cookbook contains everything related to drop configurations, including multi-use drops, and creating custom subaccounts. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +These scripts will not run without the proper setup shown in the [introduction page](../../welcome.md#connection-to-near-and-initializing-the-sdk). +::: + +## Creating a Multi-Use Simple Drop +To make all the keys in the drop multi-use, you can specify `usesPerKey` in the dropConfig parameter `config`. In this example, each of the 2 keys created will have 5 uses. + + + + +```js +// Creating drop with 2 keys with 5 uses each +const {keys} = await createDrop({ + account: fundingAccount, + numKeys: 2, + config:{ + usesPerKey: 5 + }, + depositPerUseNEAR: "0.1", +}); + +console.log(keys) +``` + + + + + +:::caution +`createDrop` is limited to adding 50 password protected keys or 100 non-protected keys at a time. To add more keys, see the [large drops](#creating-a-large-drop) example. +::: + +___ + +## Creating Custom Subaccounts +By specifying a custom `dropRoot`, all new accounts created using your drop will be a subaccount of the specified account. For example, all accounts created with the drop below will follow the form of `${YOUR_USERNAME}.moonpom.near`. + + + + +```js +// Creating drop with 2 keys with 5 uses each +const {keys} = await createDrop({ + account: fundingAccount, + numKeys: 2, + config:{ + dropRoot: "mint-brigade.testnet" + }, + depositPerUseNEAR: "0.1", +}); + +console.log(keys) +``` + + + + + +:::caution +the `dropRoot` account **must** have a contract deployed to it that exposes a method `create_account` to create the sub-account. A sample contract can be found [here](https://github.com/near/near-linkdrop) + +In addition, it is wise to [`gatekeep account creation`](usageConfig.md#gatekeeping-account-creation) to ensure that not anyone can create subaccounts of your account. + +For this reason, the above code **will not work** out of the box. +::: + +___ diff --git a/versioned_docs/version-2.0/Cookbook/drops/customizations/password.md b/versioned_docs/version-2.0/Cookbook/drops/customizations/password.md new file mode 100644 index 00000000..84a75712 --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/drops/customizations/password.md @@ -0,0 +1,142 @@ +--- +sidebar_label: 'Password Protection' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Password Protection +This part of the cookbook contains everything related password protecting your drops. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +These scripts will not run without the proper setup shown in the [introduction page](../../welcome.md#connection-to-near-and-initializing-the-sdk). +::: + +## Password Protecting your Entire Drop +Password protecting your drop prevents unauthorized people from claiming keys in your drop. A claim will fail if the [*actual password*](#claiming-a-password-protected-key) (base password is NOT the claiming password) is not included in the claim transaction. + + + + +```js +// Create drop with 1 single use password protected key +let {keys, dropId} = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: "0.1", + basePassword: "base-password" +}) + +console.log(keys) +``` + + + + + +___ + +## Claiming a Password-Protected Key +When claiming a password protected key, the password is not actually the base password. The base password is just one component that is universal for all keys across the entire drop. The actual password for each claim is different but follows the following format format: + +``` +hash(basePassword + publicKey + current_key_use) +``` + + + + +```js +let base_password = "base-password" + +// Create drop with 1 password protected key +let {keys, dropId} = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: "0.1", + basePassword: base_password +}) + +// Create password using base + pubkey + key use as string +const keyInfo1 = await getKeyInformation({ + publicKey: keys.publicKeys[0] +}) +let passwordForClaim = await hashPassword(base_password + keys.publicKeys[0] + keyInfo1.cur_key_use.toString()) + +// Claim with created password +await claim({ + accountId: "minqianlu.testnet", + secretKey: keys.secretKeys[0], + password: passwordForClaim +}) +``` + + + + + +___ + +## Password Protecting a Specific Key Use +Rather than password protecting your entire drop, you may only want to protect certain key uses. A great use case of this is for [ticketing](../../../Tutorials/Advanced/ticketing/architecture.md#attendance-required-for-poap), when a bouncer would scan your ticket to claim your key and admit you into the event but only they know the password. This would prevent people admitting themselves into the event and gaining access to any POAPs and goodies available only to those who physically attend. + +To specify key uses to password protect, simply add it to the `passwordProtectedUses` array. + + + + +```js +// Create drop with 10 password protected keys and 5 key uses each +let {keys, dropId} = await createDrop({ + account: fundingAccount, + numKeys: 10, + config:{ + usesPerKey: 5 + }, + depositPerUseNEAR: "0.1", + basePassword: "base-password", + // Password protect the first, third and fourth key uses + passwordProtectedUses: [1, 3, 4], +}) + +console.log(keys) +``` + + + + + +___ + +## Delete Drop +A drop can be deleted manually at any time using `deleteDrops`. This will refund all unclaimed key balances back to the drop funder's Keypom balance. + + + + +```js +// Get all the drops for a given user +let drops = await getDrops({accountId: "minqi.testnet"}); + +// Delete all the drops currently funded by `minqi.testnet` +await deleteDrops({ + account: fundingAccount, + drops +}) + +// Delete 2 seperate drops given their IDs +await deleteDrops({ + account: fundingAccount, + dropIds: ["123123123123123", "12391238012380123"] +}) +``` + + + + + +___ diff --git a/versioned_docs/version-2.0/Cookbook/drops/customizations/saleConfig.md b/versioned_docs/version-2.0/Cookbook/drops/customizations/saleConfig.md new file mode 100644 index 00000000..24c49bb7 --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/drops/customizations/saleConfig.md @@ -0,0 +1,226 @@ +--- +sidebar_label: 'Access Key Marketplace' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Sale Configurations +This part of the cookbook contains everything related to drops, including creating a drop, password protecting it, and utilizing Keypom arguments. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +These scripts will not run without the proper setup shown in the [introduction page](../../welcome.md#connection-to-near-and-initializing-the-sdk). +::: + +## Public Sale Drop +A public sale drop is one where you can sell the access keys from a drop to other users. These keys will all have the same properties and can be bought by anyone. The maximum number of keys in the drop can be set using `maxNumKeys`. + + + + +```js +// Create drop with a maximum of 10 keys that can be added by anyone +const { keys, dropId } = await createDrop({ + account: fundingAccount, + depositPerUseNEAR: 0.1, + config: { + sale: { + maxNumKeys: 10, + pricePerKeyNEAR: 1 + } + } +}); + +console.log(keys) +``` + + + + + +___ + +## Allowing Only Certain Users to Buy Keys +A public sale drop can be turned into a more private sale by only allowing certain accounts to purchase keys from the drop. This is done by using the `allowlist` argument. Any `accountId` specified here will be able to buy keys from your drop. If someone not on the list tries to buy from your drop, they will be rejected. + +By default, if no `allowlist` is included, then anybody can purchase a key. + + + + +```js +// Create drop with a maximum of 10 keys that can be added by benji and min +const { keys, dropId } = await createDrop({ + account: fundingAccount, + depositPerUseNEAR: 0.1, + config: { + sale: { + maxNumKeys: 10, + pricePerKeyNEAR: 1 + allowlist: ["benji.testnet", "minqi.testnet"] + } + } +}); + +console.log(keys) +``` + + + + + +___ + +## Blocking People from a Public Sale +To protect your public sale, you may also choose to block certain accounts from purchasing keys. This can be done by using the `blocklist` argument. This prohibits select accounts from purchasing keys from your drop. + +:::note +here that since no `allowlist` is specified, anybody can purchase keys. However, since `evil-moon.testnet` is on the blocklist, they will not be allowed to do so. This means that everybody except for `evil-moon.testnet` has permission to purchase a key. +::: + + + + +```js +// Create drop with a maximum of 10 keys that can be added anyone but evil-moon +const { keys, dropId } = await createDrop({ + account: fundingAccount, + depositPerUseNEAR: 0.1, + config: { + sale: { + maxNumKeys: 10, + pricePerKeyNEAR: 1 + blocklist: ["evil-moon.testnet"] + } + } +}); + +console.log(keys) +``` + + + + + +___ + +## Buying Keys from a Public Sale +If you are allowed to buy tickets from a public sale, you can simply create a new key and call `addKeys` on the public sale drop with the ticket price attached to the `extraDepositNEAR` argument. + + + + +```js +// 10 $NEAR ticket price +const TICKET_PRICE = "10" +// Desired sale's dropId +const SALE_DROP_ID = "1684876169052" + +// Generate a random key +const {publicKeys} = await generateKeys({ + numKeys: 1 +}); + +await addKeys({ + account: fundingAccount, + publicKeys, + dropId: SALE_DROP_ID, + extraDepositNEAR: TICKET_PRICE +}) +``` + + + + + +:::note +In its the example above, anybody can buy as many tickets as they'd like within the limits of the drop. For further customization, you could build a "public sale bot" contract. + +This contract would act as an entry point that users interface with and buy tickets from; allowing you to restrict the number of tickets and add further customization. To facilitate this, you would need to [create an `allowlist`](#allowing-only-certain-users-to-buy-keys) containing the bot contract. +::: + +___ + +## Modifying Sale `allowlist` +After your public sale drop has been created, you can modify the `allowlist` by adding or removing users from it using `addToSaleAllowlist` and `removeFromSaleAllowlist`. + + + + +```js +const {dropId} = await createDrop({ + numKeys: 0, + depositPerUseNEAR: 0.1, + config: { + sale: { + maxNumKeys: 2, + pricePerKeyNEAR: 1, + allowlist: ["evil-moon.testnet"] + } + } +}); + +// Remove evil-moon from allowlist +await removeFromSaleAllowlist({ + account: fundingAccount, + dropId, + accountIds: ["evil-moon.testnet"] +}); + +// Add benji and minqi to allowlist +await addToSaleAllowlist({ + account: fundingAccount, + dropId, + accountIds: ["benji.testnet", "minqi.testnet"] +}); +``` + + + + + +___ + +## Modifying Sale `blocklist` +After your public sale drop has been created, you can modify the `blocklist` by adding or removing users from it using `addToSaleBlocklist` and `removeFromSaleBlocklist`. + + + + +```js +const {dropId} = await createDrop({ + numKeys: 0, + depositPerUseNEAR: 0.1, + config: { + sale: { + maxNumKeys: 2, + pricePerKeyNEAR: 1, + blocklist: ["minqi.testnet", "benji.testnet"] + } + } +}); + +// Remove evil-moon benji and minqi from blocklist +await removeFromSaleBlocklist({ + account: fundingAccount, + dropId, + accountIds: ["benji.testnet", "minqi.testnet"] +}); + +// Add evil-moon to blocklist +await addToSaleBlocklist({ + account: fundingAccount, + dropId, + accountIds: ["evil-moon.testnet"] +}); +``` + + + + + +___ \ No newline at end of file diff --git a/versioned_docs/version-2.0/Cookbook/drops/customizations/timeConfig.md b/versioned_docs/version-2.0/Cookbook/drops/customizations/timeConfig.md new file mode 100644 index 00000000..f691c21e --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/drops/customizations/timeConfig.md @@ -0,0 +1,131 @@ +--- +sidebar_label: 'Time Configurations' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Time Configurations +This part of the cookbook contains everything related to time configurations, including start and end times, a time throttled drop, and using it to create a recurring payment tool. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +These scripts will not run without the proper setup shown in the [introduction page](../../welcome.md#connection-to-near-and-initializing-the-sdk). +::: + +:::tip +All time values are measured in Unix Time (non-leap-nanoseconds since January 1, 1970 0:00:00 UTC). +::: + +## Drop with a Start and End Time +The drop below is only active for 1.5 minutes, starting 15 seconds after the drop is created. Any claims before or after that window will fail. + + + + +```js +const ONE_SECOND_NS = 1e9; + +// Creating timed drop with 1 double use keys +const {keys, dropId} = await createDrop({ + account: fundingAccount, + numKeys: 1, + config:{ + time: { + // Start time is 15 seconds from now + start: (Date.now() * 1000000) + ONE_SECOND_NS * 15, + // End time is 90 seconds from start time + end: (Date.now() * 1000000) + ONE_SECOND_NS * 105, + }, + }, + depositPerUseNEAR: "0.1", +}); + +console.log(keys) +``` + + + + + +___ + +## Time Throttled Drop +A drop with a define time throttle will not allow consecutive `claims` on the same key within the indicated time. With the drop below, users can only claim their key every 15 seconds. If they try to `claim` twice in ten seconds, the second `claim` will fail as 15 seconds has not elapsed since the first `claim`. + + + + +```js +const ONE_SECOND_NS = 1e9; + +// Creating time throttled drop with a double use keys +const {keys} = await createDrop({ + account: fundingAccount, + numKeys: 1, + config:{ + usesPerKey: 2, + time: { + // Time between use is 15 seconds + throttle: ONE_SECOND_NS * 30, + }, + }, + depositPerUseNEAR: "0.1", +}); + +console.log(keys) +``` + + + + + +___ + +## Creating Recurring Payments +Recurring payments are quite a common situation. Say you need to send a contractor 50 $NEAR every week for 4 weeks. With Web2, they would need to provide a payment method and trust the you with this sensitive information. + +By leveraging a time configuration, you can eliminate this risk by sending them a key with limited funds attached. You could create a drop where there is one key with 4 uses, usable once a week. + +First is the `start` and `end` time. These define a period time for which the drop is active and can be used by the contractor, in this case 30 days after the drop is created. + +Next, the `interval` parameter is specified. This is set to 1 week, meaning each week after the start time, a new `claim` is made available for the contractor. This is different from the `throttle` parameter as that uses the previous claim as a reference. + +**This allows the contractor to `claim` multiple times if they miss one week rather than being forced to wait a week after each claim and potentially get pushed out of the drop's 30 day validity and lose out on funds they are entitled to.** + + + + +```js +const ONE_SECOND_NS = 1e9; + +// Creating timed drop with 1 key with 4 uses +const {keys} = await createDrop({ + account: fundingAccount, + numKeys: 1, + config:{ + usesPerKey: 4, + time: { + // Start time is now + 5s + start: (Date.now() * 1000000) + ONE_SECOND_NS * 5, + // End time is 30 day after start time + end: (Date.now() * 1000000) + ONE_SECOND_NS * 2592000, + // Time after start for first use is 1 week + interval: ONE_SECOND_NS * 604800, + }, + }, + depositPerUseNEAR: "50", +}); + +console.log(keys) +``` + + + + + +___ + diff --git a/versioned_docs/version-2.0/Cookbook/drops/customizations/usageConfig.md b/versioned_docs/version-2.0/Cookbook/drops/customizations/usageConfig.md new file mode 100644 index 00000000..0059455f --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/drops/customizations/usageConfig.md @@ -0,0 +1,210 @@ +--- +sidebar_label: 'Claiming Behavior' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Usage Configurations +This part of the cookbook contains everything related to claiming behavior and usage configurations. These will range from permissions for different types of claims, to automatically deleting the drop once all the keys have been used. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +These scripts will not run without the proper setup shown in the [introduction page](../../welcome.md#connection-to-near-and-initializing-the-sdk). +::: + +## Only New Accounts can Claim +Using `permissions` in the `usage` config, you can specify whether an account can call `claim`, `create_account_and_claim` or both. Here, the claimer must create a new account as they may only call `create_account_and_claim`. + +If no `permissions` are specified, the claimer can use either function. + + + + +```js +const { keys } = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: "1", + config: { + usage:{ + permissions: `create_account_and_claim` + } + } +}); + +console.log(keys) +``` + + + + + +___ + +## Only Existing Accounts can Claim +Using `permissions` in the `usage` config, you can specify whether an account can call `claim`, `create_account_and_claim` or both. Here, the claimer must have an existing account as they may only call `claim`. + +If no `permissions` are specified, the claimer can use either function. + + + + +```js +const { keys } = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: "1", + config: { + usage:{ + permissions: `claim` + } + } +}); + +console.log(keys) +``` + + + + + +___ +## Refunding Deposit when `Claim` is Called +When creating keys for your drop, each is loaded with enough $NEAR to cover the cost of creating an account for each claim. If a user claims with an existing account, this deposit is lost and transferred to the user. If you wish to retain those deposits whenever `claim` is called instead of `create_account_and_claim`, you can use the following. + + + + +```js +const { keys } = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: "1", + config: { + usage:{ + refundDeposit: true + } + } +}); + +console.log(keys) +``` + + + + + +___ + +## Automatically Deleting Drop when Empty +By default, depleted drops are not deleted unless you manually delete them. To delete them automatically, include the following. + + + + +```js +const { keys } = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: "1", + config: { + usage:{ + autoDeleteDrop: true + } + } +}); + +console.log(keys) +``` + + + + + +___ + +## Automatically Withdrawing your Balance +By default, withdrawing your Keypom balance back into your wallet is only done when call `withdrawBalance`. If you wish to withdraw it once all your drops have been depleted, you can turn on `autoDeleteDrop` and `autoWithdraw`. + +This will ensure that once this drop is empty it is automatically deleted and, assuming it is the final drop on your account, will automatically withdraw your Keypom balance. + +:::note +This will only automatically withdraw your balance if and only if the last drop you have. If you empty a this drop but it is not the last drop on your account, you will need to manually withdraw your balance. +::: + + + + +```js +const { keys } = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: "1", + config: { + usage:{ + autoDeleteDrop: true, + autoWithdraw: true + } + } +}); + +console.log(keys) +``` + + + + + +___ + +## Gatekeeping Account Creation +When accounts are created with drops using a custom [`dropRoot`](dropConfig.md#using-a-custom-drop-root), they will be subaccounts of the `dropRoot`. + +If you wish to make these subaccounts exclusive, you can gatekeep this process by using `accountCreationFields` to check if the claiming account is coming from your drop. Note that the `dropRoot` account would need to expose a `create_account` function that looks similar to the following: + +```rust +#[payable] +pub fn create_account(&mut self, new_account_id: AccountId, new_public_key: PublicKey, funder: String, keypomArgs: keypom_args) -> Promise { + assert!(keypomArgs.funderIdField == "funder_id","Call must come from valid Keypom drop"); + assert!(funder == EXPECTED_FUNDER == "funder_id","Funder must be approved"); + ... +} +``` + +The following shows a drop where users can only claim with a new account, and only those using your drop can create subaccounts of `moonpom.near` + + + + +```js +// Creating FC drop that injects accountId into function call arguments +let {keys, dropId} = await createDrop({ + account: fundingAccount, + numKeys: 1, + config: { + usage:{ + permissions: `create_account_and_claim`, + accountCreationFields: { + funderIdField: "funder_id" + } + }, + dropRoot: "mint-brigade.testnet" + }, + depositPerUseNEAR: "1", +}) + +console.log(keys) +``` + + + + + +For more info on injected `keypom_args`, see the [`keypom_args`](../fc.md#using-and-verifying-injected-keypom-arguments) section. + + +___ diff --git a/versioned_docs/version-2.0/Cookbook/drops/fc.md b/versioned_docs/version-2.0/Cookbook/drops/fc.md new file mode 100644 index 00000000..c8d9c2fe --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/drops/fc.md @@ -0,0 +1,390 @@ +--- +sidebar_label: 'Function Call Drops' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Function Call Drops +This part of the cookbook contains a quick overview on how to create an assortment of function call drops, using Keypom injected arguments, and attaching NFTs to your FC drop by lazy minting them. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +These scripts will not run without the proper setup shown in the [introduction page](../welcome.md#connection-to-near-and-initializing-the-sdk). +::: + +## Creating a Single Method, Single Use Function Call Drop +A Function Call Drop allows the user to call almost any function on any NEAR smart contract when claiming. An example is shown below where the method `mint` is called on `MY_CONTRACT` with the specified `memo` and `metadata` arguments. + + + + +```js +MY_CONTRACT = "guest-book.examples.keypom.testnet" + +// Creating a single key single use FC drop +let {keys} = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: "0.1", + fcData: { + methods: [ + // First key use + [ + { + receiverId: MY_CONTRACT, + methodName: "add_message", + args: JSON.stringify({ + text: "first" + }), + attachedDeposit: parseNearAmount("0.001"), + }, + ], + ] + } +}) + +console.log(keys) +``` + + + + + +___ + +## Single Method, Multi-Use Drop +To further expand the FC drop, you have the ability to call a different method for each claim. This is shown below, where the first use calls `mint`, the second call does nothing, and the third calls `sell`. + + + + +```js +MY_CONTRACT = "guest-book.examples.keypom.testnet" + +// Creating a single key single use FC drop +let {keys} = await createDrop({ + account: fundingAccount, + numKeys: 1, + config: { + usesPerKey: 3 + }, + depositPerUseNEAR: "0.1", + fcData: { + methods: [ + // First key use + [ + { + receiverId: MY_CONTRACT, + methodName: "add_message", + args: JSON.stringify({ + text: "first" + }), + attachedDeposit: parseNearAmount("0.001"), + }, + ], + // Second key use + null, + // Third key use + [ + { + receiverId: MY_CONTRACT, + methodName: "add_message", + args: JSON.stringify({ + text: "first-point-five" + }), + attachedDeposit: parseNearAmount("0.001"), + } + ], + ] + } +}) + +console.log(keys) +``` + + + + + +___ + +## Multi-Method, Single Use Key Drop +With each `claim`, you can also call multiple functions. Note this would call each function in succession after the previous one is resolved. In the example below, the `mint`, `null` case, and `sell` functions are called during the first `claim`. + + + + +```js +MY_CONTRACT = "guest-book.examples.keypom.testnet" + +// Creating a single key single use FC drop +let {keys} = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: "0.1", + fcData: { + methods: [ + // First key use + [ + { + receiverId: MY_CONTRACT, + methodName: "add_message", + args: JSON.stringify({ + text: "first" + }), + attachedDeposit: parseNearAmount("0.001"), + }, + null + { + receiverId: MY_CONTRACT, + methodName: "add_message", + args: JSON.stringify({ + text: "second" + }), + attachedDeposit: parseNearAmount("0.001"), + }, + ], + ] + } +}) + +console.log(keys) +``` + + + + + +___ + +## Multi-Method, Multi-Use Drop +By combining the [multi-claim](#creating-a-multi-claim-function-call-drop) and [multi-function call](#creating-a-multi-function-call-drop) drops together, you can call multiple number of functions for multiple claims. As an example, a key with 3 uses can be seen: + +1. `add_message` +2. `null` +3. `nft_mint`, `add_message`, `nft_transfer` + +The drop for this would look like the following + + + + + +```js +MY_CONTRACT = "guest-book.examples.keypom.testnet" + +// Creating a single key single use FC drop +let {keys: key4} = await createDrop({ + account: fundingAccount, + numKeys: 1, + config: { + usesPerKey: 3 + }, + depositPerUseNEAR: "0.1", + fcData: { + methods: [ + // First key use + [ + { + receiverId: MY_CONTRACT, + methodName: "add_message", + args: JSON.stringify({ + text: "first" + }), + attachedDeposit: parseNearAmount("0.001"), + } + ], + // Second key use + null, + // Third key use + [ + { + receiverId: NFT_CONTRACT, + methodName: "nft_mint", + args: JSON.stringify({ + token_id: "keypom-cookbook-1", + receiver_id: "minqi.testnet", + metadata: { + title: "My Test Keypom NFT", + description: "NFT from my first NFT Drop!", + media: "https://bafybeiftczwrtyr3k7a2k4vutd3amkwsmaqyhrdzlhvpt33dyjivufqusq.ipfs.dweb.link/goteam-gif.gif", + }, + }), + attachedDeposit: parseNearAmount("0.001"), + }, + { + receiverId: MY_CONTRACT, + methodName: "add_message", + args: JSON.stringify({ + text: "second" + }), + attachedDeposit: parseNearAmount("0.001"), + }, + { + receiverId: NFT_CONTRACT, + methodName: "nft_transfer", + args: JSON.stringify({ + receiver_id: "benjiman.testnet + token_id: "keypom-cookbook-1" + }), + attachedDeposit: parseNearAmount("0.001"), + }, + ], + ] + } +}) + +console.log(keys) +``` + + + + + +___ + +## Using and Verifying Injected Keypom Arguments +Keypom Args are important pieces of information injected automatically by Keypom when a key is claimed. The pieces of information can include: + +- Drop ID that the access key belongs to +- Funder's `accountId` of the drop +- The claiming account's `accountId` +- The current access key's `keyId` + +The information is injected into the `args`, but their specific location depends on the field specified. In the example below, the `funderId` is being injected into an `originalOwner` field in the `args`, and the claiming account's `accountId` is being injected into the `metadata` object under the field `newOwner`. + + + + +```js +// Creating FC drop that injects accountId into function call arguments +let {keys, dropId} = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: "0.1", + fcData: { + methods: [ + [ + { + receiverId: MY_NFT_CONTRACT, + methodName: "mint", + args: JSON.stringify({ + mint_id: MINT_ID, + metadata: { + description: "my new NFT" + } + }), + // Injecting claiming account ID into the metadata object as originalOwner + accountIdField: "metadata.newOwner", + funderIdField: "originalOwner", + } + ], + ] + } +}) + +console.log(keys) +``` + + + + + +### Verifying Injected Arguments +In addition to the injected arguments, Keypom will also automatically send an object called `keypom_args`. This object is meant for your use to validate that certain arguments were indeed injected by Keypom. This object cannot be spoofed, and any attempt to do so will cause the claim to fail. + +:::info +To validate the injected argument the receiving `mint` function should look like this. + +```rust +#[payable] +pub fn mint(&mut self, mint_id: String, originalOwner: String, metadata: data, keypomArgs: keypom_args) -> Promise { + assert!(originalOwner == DROP_FUNDER_ID && keypomArgs.funderIdField == "originalOwner", "Call must come from valid Keypom drop"); + // Optionally can also validate that keypomArgs.accountIdField == "metadata.newOwner" if you want to ensure newOwner was not hardcoded. + ... +} +``` +::: + +___ + +## Attaching NFTs to your FC Drop +As part of your FC drop, you can send the user an NFT. The best way to do this would be to lazy-mint them, as to not waste funds minting NFTs belonging to keys that are ultimately not claimed. + +To do this, you must create an NFT series, and then include a `nft_mint` call as one of the key's function calls. The Keypom NFT contracts, `nft-v2.keypom.testnet` and `nft-v2.keypom.near`, have the functionality to create a series and then mint the NFT using just the `dropId`. + + + + +```js +// Create drop with 10 keys and 2 key uses each +let {keys, dropId} = await createDrop({ + account: fundingAccount, + numKeys: 30, + depositPerUseNEAR: "0.1", + fcData: { + methods: [ + [ + { + receiverId: `nft-v2.keypom.${NETWORK_ID}`, + methodName: "nft_mint", + args: "", + dropIdField: "mint_id", + accountIdField: "receiver_id", + attachedDeposit: parseNearAmount("0.1") + } + ], + ] + } +}) + +await createNFTSeries({ + account: fundingAccount, + dropId, + metadata: { + title: "Moon NFT Ticket!", + description: "A cool NFT POAP for the best dog in the world.", + media: "bafybeibwhlfvlytmttpcofahkukuzh24ckcamklia3vimzd4vkgnydy7nq", + copies: 30 + } +}); +``` + + + + + +___ + +## Delete Drop +A drop can be deleted manually at any time using `deleteDrops`. This will refund all unclaimed key balances back to the drop funder's Keypom balance. + + + + +```js +// Get all the drops for a given user +let drops = await getDrops({accountId: "minqi.testnet"}); + +// Delete all the drops currently funded by `minqi.testnet` +await deleteDrops({ + account: fundingAccount, + drops +}) + +// Delete 2 seperate drops given their IDs +await deleteDrops({ + account: fundingAccount, + dropIds: ["123123123123123", "12391238012380123"] +}) +``` + + + + + +___ diff --git a/versioned_docs/version-2.0/Cookbook/drops/ft.md b/versioned_docs/version-2.0/Cookbook/drops/ft.md new file mode 100644 index 00000000..23231822 --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/drops/ft.md @@ -0,0 +1,78 @@ +--- +sidebar_label: 'Fungible Token Drops' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Fungible Token Drops +This part of the cookbook contains a quick overview on how to create an FT drop. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +These scripts will not run without the proper setup shown in the [introduction page](../welcome.md#connection-to-near-and-initializing-the-sdk). +::: + +## Creating a Fungible Token Drop +The process of creating an FT drop starts by checking if the funder has sufficient fungible tokens to actually create the drop. The `amountToTransfer` represents the total amount of FT to transfer for the entire drop. If you want to transfer 1 FT for 50 keys, `amountToTransfer` will be 50 fungible tokens. Next, this amount is compared to the funder's FT balance. Once that check is complete, then the FT drop can be created by including the `ftData` argument in `createDrop`. + + + + +```js +// Note that drop funder must have enough FTs to fund drop. +// If amount is "3" and there are 4 keys, Funder FT balance must be more than 12 +const { keys } = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: 1, + ftData: { + contractId: FT_CONTRACT, + senderId: YOUR_ACCOUNT, + // This balance per use is balance of human readable FTs per use. + amount: "1" + // Alternatively, you could use absoluteAmount, which is dependant on the decimals value of the FT + // ex. if decimals of an ft = 8, then 1 FT token would be absoluteAmount = 100000000 + }, +}); + +console.log(keys) +``` + + + + + +___ + +## Delete Drop +A drop can be deleted manually at any time using `deleteDrops`. This will refund all unclaimed key balances back to the drop funder's Keypom balance. + + + + +```js +// Get all the drops for a given user +let drops = await getDrops({accountId: "minqi.testnet"}); + +// Delete all the drops currently funded by `minqi.testnet` +await deleteDrops({ + account: fundingAccount, + drops +}) + +// Delete 2 seperate drops given their IDs +await deleteDrops({ + account: fundingAccount, + dropIds: ["123123123123123", "12391238012380123"] +}) +``` + + + + + +___ diff --git a/versioned_docs/version-2.0/Cookbook/drops/nft.md b/versioned_docs/version-2.0/Cookbook/drops/nft.md new file mode 100644 index 00000000..02309f30 --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/drops/nft.md @@ -0,0 +1,81 @@ +--- +sidebar_label: 'Non-Fungible Token Drops' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Non-Fungible Token Drops +This part of the cookbook contains a quick overview on how to create an NFT drop. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +These scripts will not run without the proper setup shown in the [introduction page](../welcome.md#connection-to-near-and-initializing-the-sdk). +::: + +## Creating a Non-Fungible Token Drop +An NFT drop is created by first minting the NFTs to be sent, and then including the `token_ids` in the `nftData` argument. This examples shows a single NFT, with a one single-use key. For a larger distribution, consider using an [FC to lazy mint NFTs](fc.md#attaching-nfts-to-your-fc-drop). + + + + +```js +// The funding account `minqi.testnet` has the token `token_123` on the contract `nft.examples.testnet` +const NFT_CONTRACT = `nft.examples.testnet`; +const NFT_TOKEN_ID = `token_123`; +const SENDING_ACCOUNT = `minqi.testnet`; + +const { keys } = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: "1", + nftData: { + // NFT Contract Id that the tokens will come from + contractId: NFT_CONTRACT, + // Who will be sending the NFTs to the Keypom contract + senderId: SENDING_ACCOUNT, + // List of tokenIDs + tokenIds: [NFT_TOKEN_ID] + } +}); + +console.log(keys) +``` + + + + + +___ + +## Delete Drop +A drop can be deleted manually at any time using `deleteDrops`. This will refund all unclaimed key balances back to the drop funder's Keypom balance. + + + + +```js +// Get all the drops for a given user +let drops = await getDrops({accountId: "minqi.testnet"}); + +// Delete all the drops currently funded by `minqi.testnet` +await deleteDrops({ + account: fundingAccount, + drops +}) + +// Delete 2 seperate drops given their IDs +await deleteDrops({ + account: fundingAccount, + dropIds: ["123123123123123", "12391238012380123"] +}) +``` + + + + + +___ diff --git a/versioned_docs/version-2.0/Cookbook/drops/trial.md b/versioned_docs/version-2.0/Cookbook/drops/trial.md new file mode 100644 index 00000000..865b8a32 --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/drops/trial.md @@ -0,0 +1,96 @@ +--- +sidebar_label: 'Trial Account Drops' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Trial Account Drops +This part of the cookbook contains a quick overview on how to create a trial account drop. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +These scripts will not run without the proper setup shown in the [introduction page](../welcome.md#connection-to-near-and-initializing-the-sdk). +::: + +## Creating a Trial Account Drop +When creating a trial account drop, there are 3 main parameters to define. The first is `callableContracts`, indicating what contracts the trial account can call. This will prevent rugging from the funder's perspective. Next is `maxAttachableNearPerContract` which just outlines how much $NEAR can be attached to any function call on any of the aforementioned contracts. The order of this is the same as the order defined in `callableContracts`. Lastly is the `callableMethods` parameter, which defines what methods the trial account is allowed to call on the allowed contracts. A `*` indicated any contract is callable. + +When creating the drop, the trial account's balance is then defined by its starting balance and ending balance, known as the `startingBalanceNEAR` and `trialEndFloorNEAR` respectively. + + + + +```js +// What contracts can the trial account call? +const callableContracts = [ + 'guest-book.examples.keypom.testnet', + 'v1.social08.testnet' +] +// What is the maximum amount of $NEAR that can be attached to a call for each callable contract? +// 1 NEAR for guestbook, 2 NEAR for NEAR social +const maxAttachableNEARPerContract = [ + '1', + '2' +] +// What methods can the trial account call? +// Any function can be called on either contracts. +const callableMethods = [ + ['*'], + ['*'] +] + +const wasmDirectory = `${require('path').resolve(__dirname, '..')}/trial-accounts/ext-wasm/trial-accounts.wasm` +const {keys} = await createTrialAccountDrop({ + account: fundingAccount, + numKeys: 1, + contractBytes: [...readFileSync(wasmDirectory)], + // How much $NEAR should be made available to the trial account when it's created? + startingBalanceNEAR: 2.5, + callableContracts, + callableMethods, + maxAttachableNEARPerContract, + // Once the trial account has spent this much $NEAR, the trial will be over. + trialEndFloorNEAR: 1.25 +}) + +console.log(keys) +``` + + + + + +___ + +## Delete Drop +A drop can be deleted manually at any time using `deleteDrops`. This will refund all unclaimed key balances back to the drop funder's Keypom balance. + + + + +```js +// Get all the drops for a given user +let drops = await getDrops({accountId: "minqi.testnet"}); + +// Delete all the drops currently funded by `minqi.testnet` +await deleteDrops({ + account: fundingAccount, + drops +}) + +// Delete 2 seperate drops given their IDs +await deleteDrops({ + account: fundingAccount, + dropIds: ["123123123123123", "12391238012380123"] +}) +``` + + + + + +___ diff --git a/versioned_docs/version-2.0/Cookbook/keys.md b/versioned_docs/version-2.0/Cookbook/keys.md new file mode 100644 index 00000000..8f0a3a41 --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/keys.md @@ -0,0 +1,184 @@ +--- +sidebar_label: 'Keys' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Keys +This part of the cookbook contains everything related to keys in a drop, including adding keys to a drop, checking key usage and getting the number of active keys in a drop. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +Ensure that you have initialized Keypom using the `initKeypom` function prior to running any of the SDK examples. For more info on this, see the [introduction page](welcome.md#connection-to-near-and-initializing-the-sdk) +::: + + +## Adding Keys to a Drop +Additional keys may be added to a drop using the `addKeys` function. This is particularly helpful when you want to [create a large drop](drops/NEAR.md#creating-a-large-drop). + + + + +```js +// Create an empty simple drop with no keys. +const {dropId} = await createDrop({ + account: fundingAccount, + depositPerUseNEAR: 1, +}); + +// Add 10 completely random keys. The return value `keys` contains information about the generated keys +const {keys} = await addKeys({ + account: fundingAccount, + dropId, + numKeys: 10 +}) +``` + + + + + +:::caution +`addKeys` is limited to adding 50 password protected keys or 100 non-protected keys at a time. To add more keys, see the [example below](#adding-lots-of-keys). +::: + +___ + +## Adding Lots of Keys +Adding keys, either using `createDrop` or `addKeys` is limited to 50 password protected or 100 non-protected keys. To bypass this, the drop can be created first and then the keys can be added by looping `addKeys`. + + + + +```js +// Creating drop with 0 single use keys +let {dropId} = await createDrop({ + account: fundingAccount, + depositPerUseNEAR: "0.001", +}); + +// Loop to add 200 keys +let numKeys = 200 +let keysAdded = 0; +let allSecretKeys = []; +while (keysAdded < numKeys) { + const keysToAdd = Math.min(50, numKeys - keysAdded); + const {secretKeys, publicKeys} = await generateKeys({ + numKeys: keysToAdd, + }); + await addKeys({ + account: fundingAccount, + dropId, + publicKeys + }); + keysAdded += keysToAdd; + allSecretKeys = allSecretKeys.concat(secretKeys); +} +``` + + + + + +___ + +## Removing Keys from a Drop +Just as keys can be added to a drop retroactively, they can also be removed. The following shows that process. + + + + +```js +// Create drop with 5 keys +const {keys, dropId} = await createDrop({ + account: fundingAccount, + numKeys: 5, + depositPerUseNEAR: 1, +}); + +// Delete first key from drop +await deleteKeys({ + account: fundingAccount, + dropId, + publicKeys: keys.publicKeys[0] // Can be wrapped in an array as well +}) +``` + + + + + +___ + +## Checking Key Usage +A good use case for checking key usage is when you want to track the progress/retention of the keys in your drop. An excellent example is the [ticketing tutorial](../Tutorials/Advanced/ticketing/architecture.md#keypom-solution) where each key use represented a different phase of the ticketing experience. To do this, you can get and parse the [`keyInfo`](../keypom-sdk/Core/interfaces/KeyInfo.md) object by calling `getKeysForDrop`. + + + + +```js +// Query for the key supply for the drop that was created +const keyInfos = await getKeysForDrop({ + dropId +}) + +// Check key usage of first key +const keyUsage = keyInfos[0].remaining_uses + +console.log(keyUsage) +``` + + + + + +___ + +## Checking Key Balance +Similar to how checking a key usage is done, you can parse the [`keyInfo`](../keypom-sdk/Core/interfaces/KeyInfo.md) object to see a key's remaining allowance. + + + + +```js +// Query for the key supply for the drop that was created +const keyInfos = await getKeysForDrop({ + dropId +}) + +// Check key usage of first key +const keyBalance = keyInfos[0].allowance + +console.log(keyBalance) +``` + + + + + +___ + +## Check Number of Keys Remaining in a Drop +When a key is fully depleted, it is deleted from the drop. To check the number of remaining keys, and thus the amount of keys to still be claimed, you can use `getKeySupplyForDrop`. + + + + +```js +// Query for the key supply for a drop +const keySupply = await getKeySupplyForDrop({ + dropId +}) + +console.log(keySupply) +``` + + + + + +___ diff --git a/versioned_docs/version-2.0/Cookbook/utilities.md b/versioned_docs/version-2.0/Cookbook/utilities.md new file mode 100644 index 00000000..707f14e4 --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/utilities.md @@ -0,0 +1,84 @@ +--- +sidebar_label: 'Utilities' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Utilities +This part of the cookbook contains utilities and miscellaneous common Keypom use cases. This includes creating NFT series, using the DAO bot and more. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +:::info note +Ensure that you have initialized Keypom using the `initKeypom` function prior to running any of the SDK examples. For more info on this, see the [introduction page](welcome.md#connection-to-near-and-initializing-the-sdk) +::: + + +### Create NFT Series + + + + +```js +const {keys} = await createDrop({ + account: fundingAccount, + numKeys: 2, + config:{ + usesPerKey: 1 + }, + depositPerUseNEAR: "0.1", +}); +``` + + + + + +___ + +### Utilize DAO Bot + + + + +```js +const {keys} = await createDrop({ + account: fundingAccount, + numKeys: 2, + config:{ + usesPerKey: 1 + }, + depositPerUseNEAR: "0.1", +}); +``` + + + + + +___ + +### Create Recurring Payments + + + + +```js +const {keys} = await createDrop({ + account: fundingAccount, + numKeys: 2, + config:{ + usesPerKey: 1 + }, + depositPerUseNEAR: "0.1", +}); +``` + + + + + +___ diff --git a/versioned_docs/version-2.0/Cookbook/welcome.md b/versioned_docs/version-2.0/Cookbook/welcome.md new file mode 100644 index 00000000..76ad813a --- /dev/null +++ b/versioned_docs/version-2.0/Cookbook/welcome.md @@ -0,0 +1,22 @@ +--- +sidebar_label: 'Introduction' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Introduction +Welcome to the Keypom cookbook! Here you can explore Keypom's building blocks that help create awesome onboarding experiences. The idea of these pages is for them to act as a quick reference for common use cases when using the Keypom protocol. Every use case will have a corresponding code snippet using the Keypom JS SDK. +## Getting Started +For the cookbook, you will need the following installed. +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + + +## Connection to NEAR and Initializing the SDK +When working with the SDK, you will always need to connect to NEAR and initiate Keypom using the `initKeypom` function. This will always be the first function you call to interact with the SDK. + +`initKeypom` initializes the SDK to allow for interactions with the Keypom smart contracts. Without it, none of the other SDK functions would work as expected. [More info](../keypom-sdk/Core/modules.md#initkeypom) on the `initKeypom` function. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/simple-drop/simple-example.js#L10-L35 +``` diff --git a/versioned_docs/version-2.0/TrialAccounts/Creation/drop-creation.md b/versioned_docs/version-2.0/TrialAccounts/Creation/drop-creation.md new file mode 100644 index 00000000..f8657072 --- /dev/null +++ b/versioned_docs/version-2.0/TrialAccounts/Creation/drop-creation.md @@ -0,0 +1,81 @@ +--- +sidebar_label: 'Create Your First Drop' +--- + +# Introduction + +Up until this point, you should have installed the Keypom SDK and its dependencies and should have a basic understanding of how trial accounts work and what is needed to create one. In this tutorial, you'll go through the process of creating the trial account drop that will be used to onboard users into the guest-book app. + +## Creating the Script + +Starting at the `keypom-docs-example` directory, navigate to the `advanced-tutorials/trial-accounts` folder and open the `create-trial-drop.js` file. + +```bash +cd advanced-tutorials/trial-accounts +``` + +There, you will see the code that is used to create the trial account drop. + +--- + +## Connecting to NEAR +The first step to creating the drop is connecting to the NEAR network. + +This is done with `NEAR-API-JS` and consists of: + +* Selecting which network to connect to (testnet or mainnet). + +* Specifying the location where the keys are stored for the drop funder's account. This location is commonly in the `~/.near-credentials` folder on your local machine. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/trial-accounts/create-trial-drop.js#L11-L29 +``` + +--- + +## Initializing the SDK + +The process for creating a drop always starts with calling the `initKeypom` function. + +`initKeypom` initializes the SDK to allow for interactions with the Keypom smart contracts. Without it, none of the other SDK functions would work as expected. + +```js +// Change this to your account ID +const FUNDER_ACCOUNT_ID = "minqi.testnet"; +const NETWORK_ID = "testnet" +async function createTrialAccount() { + // Initiate connection to the NEAR blockchain. + const CREDENTIALS_DIR = ".near-credentials"; + const credentialsPath = path.join(homedir, CREDENTIALS_DIR); + ... + ... + let near = await connect(nearConfig); + + // Initialize the SDK and point it to the custom NEAR object that was created. + await initKeypom({ + near, + network: NETWORK_ID + }); +} +``` + +## Creating the Trial Drop + +Now that both the SDK and NEAR connections have been established, it's time to create the drop itself. This is done using the `createTrialAccountDrop` function. You'll start by defining the restrictions that the trial account will have. You'll want the trial account to only call methods on the guest book contract and attach up to 1 $NEAR per method. In this case, the guest book contract is deployed to the `guest-book.examples.keypom.testnet` account. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/trial-accounts/create-trial-drop.js#L37-L51 +``` + +:::note +Note that a `*` was passed in for the callable methods. This means that the trial account can call any method as long as it's on the guest book contract. +::: + +Once this is finished, you can create the drop itself. The account will start with `2.5 $NEAR` and will reach the floor once `1.25 $NEAR` has been spent on attached deposits and burnt gas. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/trial-accounts/create-trial-drop.js#L53-L67 +``` + +In the above example, you only created 1 drop but you can create as many as you want for your users. It's super simple and the Keypom SDK has abstracted all the complexities away from you. In the next tutorial, you'll run the script and instantly sign into the guest-book app. + diff --git a/versioned_docs/version-2.0/TrialAccounts/Creation/getting-started.md b/versioned_docs/version-2.0/TrialAccounts/Creation/getting-started.md new file mode 100644 index 00000000..79509987 --- /dev/null +++ b/versioned_docs/version-2.0/TrialAccounts/Creation/getting-started.md @@ -0,0 +1,40 @@ +--- +sidebar_label: 'Before You Begin' +--- +# Introduction +In the following tutorials, you'll learn how Trial Accounts work behind the scenes and how to create a basic drop that can be used to instantly sign a user into the guest-book app. You'll also learn about the underlying flow for the official Keypom wallet selector plugin and how it's used to create instant sign-in experiences for users. + +--- + +## Prerequisites + +In order to successfully complete the tutorials, you'll need to have the following: + +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + +--- + +## Project Structure + +In this section, you'll prepare the project structure that will be used in the following tutorials. The core of the project is found in the [Keypom Docs Examples](https://github.com/keypom/keypom-docs-examples) repository. + +First, you'll want to clone the repo: + +```bash +git clone https://github.com/keypom/keypom-docs-examples.git && cd keypom-docs-examples +``` + +Second, install the dependencies for the SDK: + +``` +yarn install +``` + +At this point, all the dependencies should be installed and you're ready to move on to the next step which is creating the trial drop. + + + + + + diff --git a/versioned_docs/version-2.0/TrialAccounts/Creation/integration.md b/versioned_docs/version-2.0/TrialAccounts/Creation/integration.md new file mode 100644 index 00000000..dda5e0db --- /dev/null +++ b/versioned_docs/version-2.0/TrialAccounts/Creation/integration.md @@ -0,0 +1,175 @@ +--- +sidebar_label: 'Integrating Into Your Apps' +--- + +# Introduction + +In the previous tutorial, you looked at the script necessary to create the trial account drop and how simple it was. In this tutorial, you'll start a local version of the guest-book app and see how easy it is to integrate and support trial accounts. + +:::warning +The UI for trial accounts while in the guest-book app in this tutorial are NOT finalized. Benji sucks at UI design and we're getting a designer to help us out. This is just a placeholder for now and is meant to be a proof of concept. +::: + +## Starting the Guest Book + +Starting at the `keypom-docs-examples` directory, navigate to the `advanced-tutorials/trial-accounts/guest-book` folder and install the dependencies. + +```bash +cd advanced-tutorials/trial-accounts/guest-book && yarn install +``` + +Once the dependencies have been installed, you can start the app. + +```bash +yarn start +``` + +This should open the guest-book app in your browser and you should see the following: + +

+ ticketing +

+ +:::note +If you're signed in already, it's because you've used the same port for another application that was left signed in. Simply sign out or open the link in a new incognito window. +::: + +--- + +## Creating the Trial Account + +Now that the guest-book is running, it's time to run the trial creation script. Open a new terminal and navigate to the `keypom-docs-examples` directory. Navigate to the `advanced-tutorials/trial-accounts` folder and open the `create-trial-drop.js` file. + +```bash +cd advanced-tutorials/trial-accounts +``` + +From here, make sure you change the account ID that is being used to sign transactions to an account that you're currently signed in with: + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/f1f634a629808f0d0943e508c2be6576622d32b1/advanced-tutorials/trial-accounts/create-trial-drop.js#L11 +``` + +In addition, change the `guestBookInstance` to whichever URL your app is running on: + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/f1f634a629808f0d0943e508c2be6576622d32b1/advanced-tutorials/trial-accounts/create-trial-drop.js#L70 +``` + +Once this is finished, you can run the following command to create the trial account drop. + +```bash +node create-trial-drop +``` + +This should output the following: + +```bash +Receipts: GCQ5qw2DYfnH4otYww94sJeVT2hEaEXj58Ky3J8FKdCS, FRCyeeVGgGq1YRRkxFRApjGpDdWyxZn4LQJTDoc22SV1 +Log [v2.keypom.testnet]: Warning: Balance is less than absolute minimum for creating an account: 2840000000000000000000 +Log [v2.keypom.testnet]: Current Block Timestamp: 1680902177371759044 +Log [v2.keypom.testnet]: 31 calls with 155000000000000 attached GAS. Pow outcome: 2.5000782. Required Allowance: 39626233977241600000000 +Log [v2.keypom.testnet]: Total required storage Yocto 837110000000000000000000 +Log [v2.keypom.testnet]: Current balance: 8.0866179, + Required Deposit: 3.6777362, + total_required_storage: 0.83711, + Drop Fee: 0, + Key Fee: 0 Total Key Fee: 0, + allowance: 0.0396262 total allowance: 0.0396262, + access key storage: 0.001 total access key storage: 0.001, + deposits less none FCs: 0 total deposits: 0 lazy registration: false, + deposits for FCs: 2.8 total deposits for FCs: 2.8, + uses per key: 1 + None FCs: 0, + length: 1 + GAS to attach: 150000000000000 +Log [v2.keypom.testnet]: New user balance 4.4088817 +Log [v2.keypom.testnet]: Fees collected 0 + + + Guest-Book App: +http://localhost:1234/trial-url#v2.keypom.testnet/3HbgYBvVMSfTBpXQ4fSecbPzwup2YkJPipNmT7e2iyw5MfzfMN3rHccsPddWcTGFTehCux7AbmtJiRqd78x4F57g + +Good Luck! +``` + +## Using the Guest Book + +Now that the drop is created, it's time to create a brand new account! Open the URL and you should see the following screen: + +

+ ticketing +

+ +Enter a valid username and click Create. This will start the claiming process. + +

+ ticketing +

+ +The claiming process should take a few seconds and then you should see the following screen: + +

+ ticketing +

+ +Once you click the button, you should be instantly signed into the guest-book app. + +### Signing Your First Transaction + +Now that you're signed in, you can instantly begin using the guest-book app. Try signing a message with `0.01 $NEAR` and see what happens! + +

+ ticketing +

+ +After a few seconds, the transaction should go through and your message should show up at the bottom of the messages list! Notice how there was no redirects to the NEAR wallet for approval and no sign in. + +### Invalid Actions + +Recall that the trial account cannot attach more than 1 $NEAR to a given transaction. Try signing a message with `1.1 $NEAR` and you should be greeted with the following modal: + +

+ ticketing +

+ +If you then sign the message with `1 $NEAR` or less, it should go through properly. + +### Trial Over + +After you've spent `1.25 $NEAR` on the app and you try to sign another message, you should see the following trial over modal: + +

+ ticketing +

+ +In this case, since FastAuth isn't complete, clicking the button will send you somewhere special. + +### Losing Access to Local Storage + +If the account were to lose access of the local storage or their computer blew up, all they would need is the original trial account link to gain access to their account again. To test this behavior, close the app and open a brand new incognito window. Paste the original link and you should immediately be signed back into the app. + +## Behind the Scenes + +In order for the guest-book app to be fully compatible with trial accounts, it only needs to add the SDK's wallet selector plugin. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/28444a492c513b8244e25ccaf067ca54f305b090/advanced-tutorials/trial-accounts/guest-book/near-wallet.js#L45-L55 +``` + +You'll notice that there are a couple of parameters that are passed into the `setupKeypom` function. You need to specify: + +- `trialAccountSpecs.url` and `instantSignInSpecs.url`: The URL format that must be met in order to trigger the sign-in flow. + - You may notice the `ACCOUNT_ID` and `SECRET_KEY` markers in the URLs. These define where the account ID and secret key will go for the links you plan to distribute. For more information, see the [TypeDocs](../../keypom-sdk/Selector/welcome.md#trial-account-specs). +- `signInContractId`: The contract ID that regular users create access keys for when signing in. +- [`trialAccountSpecs.modalOptions`](../../keypom-sdk/Selector/welcome.md#modal-options): Information that you can specify that will customize the modals that are shown to the user while on your app. Here, `KEYPOM_OPTIONS` from `./keypom-data` are imported and used. + +### Customizing the Modals + +By default, the modals that are shown to the user can be heavily customized to match the look and feel of your website. If you brand the regular wallet selector modal, the CSS will **automatically be applied** to the trial account modals. + +In addition, you can specify a suite of titles and descriptions. These will be covered further in a different tutorial. + +## Conclusion + +In this tutorial, you learned how to create a link that will allow users to experience your app through a trial account. You then created a new testnet account, instantly signed into the guest-book app and went through different scenarios that a user might encounter while using your app. \ No newline at end of file diff --git a/versioned_docs/version-2.0/TrialAccounts/Creation/understanding-trial-accounts.md b/versioned_docs/version-2.0/TrialAccounts/Creation/understanding-trial-accounts.md new file mode 100644 index 00000000..3a25ce6a --- /dev/null +++ b/versioned_docs/version-2.0/TrialAccounts/Creation/understanding-trial-accounts.md @@ -0,0 +1,134 @@ +--- +sidebar_label: 'Understanding Trial Accounts' +--- + +# Basis of Trial Accounts + +A Trial Account is simply an account on NEAR that has a set of pre-defined restrictions that limit the methods that it can call. This is achieved by deploying a very small no-std Rust smart contract on it (~25 kb or 0.25 $NEAR) that acts as a proxy, or middleman, for any outbound calls it makes. + +The contract deployed to the account exposes a method `execute` that takes a set of actions as arguments, checks whether the actions are allowed, and then executes them. To achieve this middleman behavior, the Trial Account cannot have any full access keys (otherwise it could bypass the `execute` method, and in turn, the restrictions). The account should *only* have one limited access key that can call the `execute` method on its own contract. + +Whenever a Trial Account wants to call a method on an external contract, say `nft_mint` on the `nft.examples.testnet` account, it needs to call `execute` and pass in the desired function call as arguments. The contract will then check whether those actions are allowed and if they are, it will execute the desired behavior. + +To help illustrate this behavior, the follow diagram shows the above scenario. + +

+ ticketing +

+ +## Keypom Drops + +From the above, a Trial Account can be created by deployed a valid contract to an account that only has a limited access key on it with the correct permissions. This can all be achieved with a [Function Call drop](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops.md). + +In order to create accounts ending with `.near` or `.testnet`, you'll need the `near` and `testnet` accounts to create sub-accounts. This is done by calling the `create_account` function on their contracts (the code is found [here](https://github.com/near/near-linkdrop/blob/49279e529c254fa7736465b4a39d05cb8f1e5443/src/lib.rs#L130)). This is exactly how regular linkdrops work, including [Keypom](https://github.com/keypom/keypom/blob/7a654aa847f2ce9dedf65755c6a08817eece4666/contract/src/stage3/claim.rs#L129). + +By calling `create_account`, a new sub-account is created with a full access key. This is close to the behavior we want for Trial Accounts but not exactly. In order to create a new account that has a limited access key and a contract deployed, you can call the `create_account_advanced` function instead of `create_account`, code found [here](https://github.com/near/near-linkdrop/blob/49279e529c254fa7736465b4a39d05cb8f1e5443/src/lib.rs#L156). This function can accept `wasm` for a contract, and limited access key arguments. + +A Keypom function call drop can then be programmed to: +- Call the `create_account_advanced` function. +- Pass in user provided args for the new account ID. +- Pass in the `wasm` for the contract to be deployed. +- Pass in the limited access key arguments to create a key that can call `execute` on the newly created account. +- Once the account is created, Keypom will automatically call a setup method on the new account that will set the restrictions. + +Keypom has abstracted away all these complexities using a simple ready-made function [createTrialAccountDrop](../../keypom-sdk/Core/modules.md#createtrialaccountdrop). + +## Understanding Trial Restrictions + +There are 3 different restrictions that can be applied to a Trial Account: +- Callable contracts +- Callable methods +- Attached Deposits + +### Callable Contracts + +As a trial funder, you have complete control over exactly which contracts a trial account can call. This can be any number of contracts and should be passed in using an array. For example, if you wanted the trial to only call methods on the `v2.keypom.testnet` and `nft.examples.testnet` contracts, you would pass in the following: + +```js +const callableContracts = [ + "v2.keypom.testnet", + "nft.examples.testnet" +] +``` + +### Callable Methods + +Not only do you have full control over the contracts that a trial account can call, but you can also specify individual methods on a per-contract basis. In the above example, if you wanted the account to be able to call any method on the `v2.keypom.testnet` contract, but only the `nft_mint` and `nft_transfer` methods on the `nft.examples.testnet` contract, you would pass in the following: + +```js +const callableMethods = [ + ["*"], + ["nft_mint", "nft_transfer"] +] +``` + +:::note +The `*` symbol is used to represent no restrictions on methods for a given contract. +::: + +### Max Attachable Deposit + +The last restriction that you can set on a given trial account is the maximum amount of $NEAR that can be attached to function calls for a given contract. In the above scenario, say you wanted to limit an account to the following restrictions: +- Attaching up to 5 $NEAR to any method on the `v2.keypom.testnet` contract. +- Only attaching 1 yoctoNEAR to methods on the `nft.examples.testnet` contract. + +You would pass in the following: + +```js +const maxAttachableDeposit = [ + "5000000000000000000000000", + "1" +] +``` + +## Exit Conditions + +The final thing to understand about trial accounts is how they can be exited. While the account is in the trial state, it has restrictions and isn't usable in the wider ecosystem. As a funder, you can specify conditions that need to be met in order for the account to exit the trial state. + +### Trial Over Floor + +The main condition that dictates how long an account will be in the trial state before it must exit is the trial floor. This is an amount of $NEAR that must be spent before the account is eligible to exit. The amount consists of both gas burnt as well as deposits to successful function calls. + +For example, if an account attached 1 $NEAR to a function call and also burnt 75 TGas, it would be `1.0075 $NEAR` closer to the floor. Overtime, as an account executes more and more transactions, it will come closer to the floor. Once the floor has been reached, the account will be eligible to exit. + +:::note +It's important to note that once the floor has been met, the account can continue to execute transactions. Reaching the floor simply means that the account *can* exit the trial state (assuming all other conditions have been met). +::: + +### Repay Conditions + +If the funder chooses to, they can also specify a repay condition. This is an amount of $NEAR that must be paid back to them in order for the account to exit the trial state. + +This process happens automatically when the exit method is called but it will throw an error if the account doesn't possess enough funds to repay the funder. This amount can be 0 $NEAR meaning that once the account reaches the floor, it can immediately exit without needing to repay. + +The $NEAR needed to repay the funder can be gained in one of three ways: +1. Gained during the trial (e.g selling an NFT you minted, winning an on-chain lottery etc.). +3. Sent by another account. +2. Sent with an on-ramp (similar to how accounts are funded currently). + +While there is still friction in the last case, the user has **experienced your application first** and the onboarding is pushed until after their trial is over. Currently, people need to go through the complicated onboarding process first and only experience the app afterwards. + +As an example, let's say you're building a roulette app and you want to give users a trial account to experience what you're building in the hope that they will continue to use it afterwards. You give someone 10 $NEAR and set a repay condition of 5 $NEAR. During their trial, they could have won 20 $NEAR from the roulette app by putting all their money on red. + +This would satisfy the repay condition and they would be able to keep the rest of the $NEAR that they won. + +### What Happens On Exit? + +When regular accounts are created on NEAR, they start with a full access key and don't have any smart contract deployed to them. This behavior should be the same for trial accounts except they keep any assets they had during the trial state. When the account exits, the following will happen: + +- The limited access key is removed from the account. +- The trial contract is removed from the account. +- Any state that was set on the trial contract is removed. +- The full access key is added to the account. +- Any repay conditions are paid out. +- Any $NEAR that was *not* gained during the trial is returned to the funder. This includes the bytes freed from deleting the contract and is meant to be a way to resist Sybil attacks. + +This means that the account will act as a fresh NEAR account with a set of starting assets such as NFTs or FTs that it gained during the trial. If the account wanted to, it could deploy a contract such as multi-sig, nETH etc. + +When a trial account exits, it will be given a full access key and the restrictions will be removed. This means that the account will be able to call any method on any contract and attach any amount of $NEAR to function calls. + +## Conclusion + +In this tutorial, you learnt the basics of how trial accounts operate and what is needed to create them. You also learnt about the different restrictions that can be applied to trial accounts, how they can be exited and what happens when they exit. + +In the next tutorial, you'll learn how to create a simple trial account drop that will be used to instantly sign a user into the guest-book application. \ No newline at end of file diff --git a/versioned_docs/version-2.0/TrialAccounts/introduction.md b/versioned_docs/version-2.0/TrialAccounts/introduction.md new file mode 100644 index 00000000..116896bb --- /dev/null +++ b/versioned_docs/version-2.0/TrialAccounts/introduction.md @@ -0,0 +1,61 @@ +--- +sidebar_label: 'Getting Started' +--- +# Keypom Trial Accounts + +Keypom Trial Accounts are an exciting new opportunity for Web3 apps to seamlessly onboard users whether theyโ€™re completely new to crypto or seasoned veterans. With the click of a link, users require no software, wallet setup, wallet connection, and are **instantly signed into apps** with their trial account, ready to make on-chain transactions. + + +

+ ticketing +

+ +:::info +Check out this slick [demo of Keypom Trial Accounts (4min)](https://www.youtube.com/watch?v=rQf_wlA5eEw). +::: + +## Benefits + +The key benefit of using trial accounts is that the app developers, also referred to as the funders of the trial accounts, have granular control over the smart contracts, methods and amounts of NEAR tokens used during the trial. These rules are specified when the trial account is created and ensure that the funder **cannot be rugged by the user**. + +Traditionally on NEAR, [linkdrops](../Concepts/LinkdropsAndAccessKeys/linkdrop-basics.md) have been used to create accounts containing $NEAR. Since this $NEAR is unlocked, users could simply take it and spend it *anywhere in the ecosystem*, exactly like giving someone cash. This defeated the purpose for app developers to provide users with a small amount of $NEAR to trial their applications. + +With trial accounts, $NEAR is placed inside a smart contract deployed to the user's account along with rules specified by the app developer when the account is created. This means that giving away a trial account is not like giving cash, but instead **a gift card**. + +Trial Accounts support all types of NEAR FunctionCall actions, including those with attached deposits e.g. 1 yocto for FT and NFT transfers, making them the ideal choice as a first touch point for new users to NEAR applications. + +Our vision is for trial accounts to be the point of entry for onboarding onto any NEAR application. Once the trial is over, the user can exit to a full and unrestricted NEAR Account, retaining any assets they received during the trial period. The exit process happens through any external onboarding mechanism that supports the linkdrop standard such as FastAuth, MyNEARWallet etc. + +## Getting Started + +To learn how to create trial accounts and integrate them into your app, there are a few basic tutorials to get you started. + +:::note +Trial Accounts are still in early stage development and are not meant to be used for production. The Keypom team is working on finalizing the contract and getting it audited as soon as possible. +::: + +
+
+
+ +
+
+

Trial Accounts

+

In-depth guide on Trial Accounts

+
+
+ +
+
+ +
+
+

Integrate In Your Apps

+

Learn how to be fully compatible with Trial Accounts!

+
+
+ +
+
+
+

\ No newline at end of file diff --git a/versioned_docs/version-2.0/TrialAccounts/offboarding.md b/versioned_docs/version-2.0/TrialAccounts/offboarding.md new file mode 100644 index 00000000..0b73e1cd --- /dev/null +++ b/versioned_docs/version-2.0/TrialAccounts/offboarding.md @@ -0,0 +1,238 @@ +--- +sidebar_label: 'Offboarding Trial Accounts' +--- +# Introduction + +In this tutorial, you'll learn how to support trial accounts exiting into your wallet. + +Trial Accounts are a great way to onboard new users to applications with the click of a link. The in-app experience is seamless but at some point, the trial must end. This process should remove all restrictions from the user's account and allow them to interact with the any app on NEAR. This process is known as offboarding and is a critical part of the user's journey. + +As part of the offboarding process, a full access key will be added to the account and this should be stored somewhere safe. For this reason, we wanted to make sure trial accounts could be exited into any wallet or app that supports the official linkdrop standard (e.g MyNEARWallet / FastAuth). + +The desired user experience is as follows: +1. Click a link or scan a QR code. +2. Enter a username. +3. Immediately get signed into the app and start using it. +4. Once your trial is over, a modal pops up with options for onboarding. +5. Click the desired option (such as MyNEARWallet) and get redirected. +6. Offboard with the app and get a new private key based on the option you chose (seedphrase, biometrics etc.) +7. The trial account has now been converted into a full, unrestricted NEAR account that can interact with the rest of the ecosystem. + +

+ ticketing +

+ +## Utilizing Linkdrops + +Most wallets support linkdrop claiming since it leads to more opportunities for them to gain new users. This can be used to our advantage if the trial account offboarding process is treated as a regular linkdrop, then the account can be offboarded into almost every wallet. Before learning how this is accomplished, you should first understand the basics of claiming linkdrops. + +### Claiming + +As per the official linkdrop standard, there are 3 methods that are important for claiming linkdrops: + +```ts +/// Returns the KeyInfo associated with a given public key +/// Panics if the key does not exist +function get_key_information(key: string) -> KeyInfo + +/// Transfer assets linked to a given public key to an `account_id`. +/// +/// Arguments: +/// * `account_id` the account that should receive the linkdrop assets. +/// +/// Returns `true` if the claim was successful meaning all assets were sent to +/// the `account_id`. +function claim(account_id: string) -> Promise + +/// Creates a new NEAR account and transfers all assets linked to a given public +/// key to the *newly created account*. +/// +/// 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 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 +``` + +For an arbitrary linkdrop (a URL containing the contract and secret key), the flow is as follows: +1. The user clicks a link or scans a QR code representing the linkdrop. +2. The app calls `get_key_information` to check what's in the linkdrop. + - If the linkdrop was already claimed (or doesn't exist), the call will panic and the frontend should indicate that the drop is invalid. +3. Depending on what is returned from the call, the app should display what assets the user is about to claim (e.g NFTs, FTs, $NEAR etc.) +4. The frontend exposes a form field and the user either inputs a new account or an existing one. +5. If a new account is created, the frontend will call `create_account_and_claim` and pass in the new account ID and an access key that will have full access permission over the account. + - This key is generated based on what the app allows. For example, MyNEARWallet generates the key using a seedphrase while FastAuth generates it using biometrics. +6. The linkdrop is claimed and the assets are sent to the user's account. + +### Trial Account Linkdrops + +Now that the basics of linkdrop claiming have been covered, you'll look at how trial accounts can be treated as a linkdrop. From above, there are a few requirements that need to be met: +- The URL should contain a contract and secret key +- The trial contract should implement the `get_key_information` method so that frontends know when a drop is valid. +- The trial contract should implement the `create_account_and_claim` method for claiming. + +Recall that for claiming assets to a new account, linkdrop contracts will create the account and add the public key as a full access key to the account. This access key is generated on a per-app basis. For example, MyNEARWallet generates the key using a seedphrase while FastAuth generates it using biometrics. + +In the case of the trial account contract, the exact same flow can happen except the account creation is *already done*. When calling `create_account_and_claim`, the contract should accept the new public key and do the following (assuming the account can exit): +1. Delete the existing limited access key used during the trial. +2. Create a new access key with the `new_public_key` and give it full access to the account. +3. Repay the funder for any required $NEAR. +4. Delete any state that is being used by the contract. +5. Delete the trial contract and free up all the storage. + +Notice that the only parameter that was *actually* used was `new_public_key` but in the official linkdrop standard, the `create_account_and_claim` function takes two parameters: + +```ts +function create_account_and_claim(new_account_id: string, new_public_key: string) +``` + +The `new_account_id` field is disregarded by the trial account contract since the account already exists. You can pass in any value for this field and it will be ignored. + +For example, the following code could be used to completely offboard a trial account using `near-api-js`. The pseudo code is: +1. Initialize the NEAR connection. +2. Set the trial account key in the keystore. +3. Get the key information and check if the account can exit the trial. +4. Generate a random keypair that will be used as the account's new full access key. +5. Call `create_account_and_claim` with the new public key and the required gas coming from the call to get key information. + +```ts +const NETWORK_ID = 'testnet'; +// Generate a new keystore and connect to the NEAR network +let keyStore = new keyStores.InMemoryKeyStore(); + +let nearConfig = { + networkId: NETWORK_ID, + keyStore: keyStore, + nodeUrl: `https://rpc.${NETWORK_ID}.near.org`, + walletUrl: `https://wallet.${NETWORK_ID}.near.org`, + helperUrl: `https://helper.${NETWORK_ID}.near.org`, + explorerUrl: `https://explorer.${NETWORK_ID}.near.org`, +}; + +let near = await connect(nearConfig); + +// Account ID of the trial account +const trialAccountId = "benji-demo-12345.testnet"; + +// Trial Account Secret Key +const trialAccountSecretKey = "5XorwuVXhTpscqddyyrRB9QVZDTn3mut9Zeu7drtdxexurhgf2V4WHJ8RyLoJppmHagMg6gcdAQrG8gJf9JA2XB" +const keyPair = KeyPair.fromString(trialAccountSecretKey); +await keyStore.setKey(NETWORK_ID, trialAccountId, keyPair); + +// Create the account object for the trial +const trialAccountObj = new Account(near.connection, trialAccountId); + +// Check if the trial account is able to exit +const keyInfo = await trialAccountObj.viewFunction(trialAccountId, 'get_key_information', {key: keyPair.getPublicKey().toString()}); +if (keyInfo.trial_data?.exit == true) { + // This will be the full access key for the new account + const newKeyPair = KeyPair.fromRandom('ed25519'); + + // How much gas should be attached to the create account call + const requiredGas = keyInfo.required_gas; + + // If the account can exit, generate a new random access key which will be used for the full access key + await trialAccountObj.functionCall({ + contractId: trialAccountId, + methodName: 'create_account_and_claim', + args: { + new_account_id: "", + new_public_key: newKeyPair.getPublicKey().toString() + }, + attachedDeposit: 0, + gas: requiredGas + }); +} +``` + +### Rendering Linkdrops + +Wallets and apps that support the claiming of linkdrops should render their claim pages differently depending on what assets are contained in the linkdrop. For example, if the linkdrop contains $NEAR, the page could look like this: + +

+ ticketing +

+ +If the linkdrop contains NFTs, the page could look like this: + +

+ ticketing +

+ +This is done using the `get_key_information` method and rendering the page depending on the result. In the official linkdrop standard, the return value is an object `KeyInfo` that looks as follows: + +```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`. + /// It is up to the smart contract developer to calculate the required gas (which can be done either automatically on the contract or on the client-side). + required_gas: string, + + /// yoctoNEAR$ amount that will be sent to the account that claims the linkdrop (either new or existing) + /// when the key is successfully used. + yoctoNEAR: 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 account that claims the linkdrop (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 account that claims the linkdrop (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. +} +``` + +The frontend can check what's contained and render the page accordingly. + +## Supporting Trial Account Offboarding + +This idea of conditional rendering is the key to supporting trial account offboarding. In general, when a frontend renders the page for users that will call `create_account_and_claim`, the flow is as follows: +1. Show the user what assets they've received +2. Prompt the user for a new username +3. Give the user their private key (biometrics, seedphrase, etc.) +4. Call `create_account_and_claim` with the new username and the generated public key + +While this approach *could* work with trial accounts, it is not ideal as there's no need to ask for a username since the account already exists. + +### Rendering Trial Account Linkdrops + +A better flow for offboarding trial accounts would be to skip the new username prompt mentioned above. This means that the user's journey would look like this: + +1. Show the user a screen indicating that they're about to exit the trial account +3. Give the user their private key (biometrics, seedphrase, etc.) +4. Call `create_account_and_claim` with an empty username and the generated public key + +In order to support this flow, the frontend should check if the linkdrop contains a trial account. This can be done by checking the information returned from `get_key_information`. The trial accounts will return the following object: + +```ts +/// Information about a specific public key. +type KeyInfo = { + /// How much Gas should be attached when calling `create_account_and_claim` in order to exit the account + required_gas: string, + + /// This will always be zero for trial accounts since the linkdrop doesn't contain $NEAR and instead contains the actual account + yoctoNEAR: '0', + + /// Specific data that is used to determine whether or not a linkdrop is a trial account + trial_data: { + /// If the trial account can exit, this will be true. + exit: boolean + } +} +``` + +If the `trial_data` field is present, the frontend can assume that the linkdrop is a trial account and render the page accordingly. + +### In Summary + +Frontends that support the official linkdrop standard should be able to ingest an arbitrary linkdrop and render their claim page based on the assets contained in the drop. While the standard officially supports only 3 types of drops: $NEAR, NFTs, and FTs, it is easily extendable to support other types of assets. + +In the case of trial accounts, the key information will return a new field `trial_data` that will indicate whether or not the account can exit. If the exit boolean is set to true, the frontend should skip the prompt for a new username and directly call `create_account_and_claim` while passing in an empty username and the corresponding public key that should be added as full access. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/AccessKeyMarketplace/concept.md b/versioned_docs/version-2.0/Tutorials/Advanced/AccessKeyMarketplace/concept.md new file mode 100644 index 00000000..07faeccd --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/AccessKeyMarketplace/concept.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Concept' +--- +# Concept \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/AccessKeyMarketplace/final.md b/versioned_docs/version-2.0/Tutorials/Advanced/AccessKeyMarketplace/final.md new file mode 100644 index 00000000..d90001ba --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/AccessKeyMarketplace/final.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Final Product' +--- +# Final Product \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/AccessKeyMarketplace/skeleton.md b/versioned_docs/version-2.0/Tutorials/Advanced/AccessKeyMarketplace/skeleton.md new file mode 100644 index 00000000..d5e552ef --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/AccessKeyMarketplace/skeleton.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Skeleton Code' +--- +# Skeleton Code \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/CustomizedOnboarding/final.md b/versioned_docs/version-2.0/Tutorials/Advanced/CustomizedOnboarding/final.md new file mode 100644 index 00000000..d90001ba --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/CustomizedOnboarding/final.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Final Product' +--- +# Final Product \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/CustomizedOnboarding/introduction.md b/versioned_docs/version-2.0/Tutorials/Advanced/CustomizedOnboarding/introduction.md new file mode 100644 index 00000000..b20757bd --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/CustomizedOnboarding/introduction.md @@ -0,0 +1,25 @@ +--- +sidebar_label: 'Introduction' +--- +# Introduction + +One of the biggest pain-points with Web3 is that users need to fund wallets before they interact with a dApp. In Web2, a user can find value in an application by using it before they go through the messy onboarding process. + +**Keypom will allow apps to create links that will automatically sign users into their applications and give them a free trial. ** + +This can be thought of as giving someone a gift card that only works at your store. This concept is extremely powerful and has been around the Web2 world for a long time. As an example, a casino might give out 10$ vouchers so that people come and play. Once the voucher runs out, people can either leave or top-up their balance and stay longer. The import thing to note with this is that users are only pulling out their credit cards once theyโ€™ve actually experienced the casino. + +With Keypomโ€™s limited access accounts, people will be able to interact, spend $NEAR, sign transactions and gather assets with the simple click of a link. Once the free trial is over and users have collected value through interacting with the dApp, they can then choose to upgrade their account and onboard. + +Much like the gift-card analogy, users will be locked into only interacting with the dApp specified in the link. They can't take the funds embedded in the โ€œvoucherโ€ and leave. The funds are allocated for only 1 purpose: free trials of a specific application. + +

+ ticketing +

+ + +In this tutorial, you'll learn how to create your very own customized onboarding. + +:::info +๐Ÿšง Full tutorial coming soon... ๐Ÿšง +::: \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/CustomizedOnboarding/skeleton.md b/versioned_docs/version-2.0/Tutorials/Advanced/CustomizedOnboarding/skeleton.md new file mode 100644 index 00000000..d5e552ef --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/CustomizedOnboarding/skeleton.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Skeleton Code' +--- +# Skeleton Code \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ReceiverContracts/concept.md b/versioned_docs/version-2.0/Tutorials/Advanced/ReceiverContracts/concept.md new file mode 100644 index 00000000..07faeccd --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ReceiverContracts/concept.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Concept' +--- +# Concept \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ReceiverContracts/final.md b/versioned_docs/version-2.0/Tutorials/Advanced/ReceiverContracts/final.md new file mode 100644 index 00000000..d90001ba --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ReceiverContracts/final.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Final Product' +--- +# Final Product \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ReceiverContracts/skeleton.md b/versioned_docs/version-2.0/Tutorials/Advanced/ReceiverContracts/skeleton.md new file mode 100644 index 00000000..d5e552ef --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ReceiverContracts/skeleton.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Skeleton Code' +--- +# Skeleton Code \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/RewardGating/concept.md b/versioned_docs/version-2.0/Tutorials/Advanced/RewardGating/concept.md new file mode 100644 index 00000000..07faeccd --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/RewardGating/concept.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Concept' +--- +# Concept \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/RewardGating/final.md b/versioned_docs/version-2.0/Tutorials/Advanced/RewardGating/final.md new file mode 100644 index 00000000..d90001ba --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/RewardGating/final.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Final Product' +--- +# Final Product \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/RewardGating/skeleton.md b/versioned_docs/version-2.0/Tutorials/Advanced/RewardGating/skeleton.md new file mode 100644 index 00000000..d5e552ef --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/RewardGating/skeleton.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Skeleton Code' +--- +# Skeleton Code \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/daos/architecture.md b/versioned_docs/version-2.0/Tutorials/Advanced/daos/architecture.md new file mode 100644 index 00000000..ccdce9ea --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/daos/architecture.md @@ -0,0 +1,99 @@ +--- +sidebar_label: 'Solution Architecture' +--- +# Solution Architecture +In this section, you'll break down the requirements for the onboarding experience in order to create a solution architecture. This means translating the features from the [introduction](introduction.md) into tangible goals for the specific Keypom drop and its configurations. + +The two major requirements for the auto-registration experience are: +- Members don't need an existing wallet to join the DAO. +- The invitations do not require a 2 step process where a council votes and reaches a quorum for every registration. + +## Seamless Wallet Creation + +Since each user will be given a Keypom linkdrop, the wallet creation is handled by whatever claim platform they choose (MyNEARWallet, Meteor, FastAuth etc.). This means that there is no funding required from the user's perspective, eliminating KYC, credit cards, exchanges and other barriers. + +The end user experience is to simply enter an account name and secure the wallet with whatever method they choose (iOS app, seedphrase, biometrics etc.). + +## Single Step Registration + +DAOs require a 2 step process for members to join. The first step is to create a proposal for adding them to the DAO and the second is to vote on that proposal and reach a quorum. This means that the DAO must constantly monitor for incoming proposals, leading to long wait times for new users. + +If DAOs want to mass register members, this process is very inefficient. From a technical stand-point, what happens is: + +1. An [`AddMemberToRole`](https://github.com/near-daos/sputnik-dao-contract#proposal-types) proposal is created. +2. A quorum of voting members, such as the DAO's council, must be reached to approve this proposal. + +### Optimizing the Approach + +In order for this process to be streamlined and completed automatically, Keypom must be able to first add a proposal and then **also** approve it as **part of the linkdrop claiming process**. + +First, Keypom must be given a role that is capable of creating and approving proposals for adding new members. + +Second, Keypom must be given a role that automatically reaches quorum whenever it votes. For this tutorial, that role will only have 1 member so that whenever Keypom votes to accept the `AddMemberToRole` proposal, 100% of the members will have voted and it will be automatically accepted. + +To combine both these features into one step, a FunctionCall drop can be created that first calls [`add_proposal`](https://github.com/near-daos/sputnik-dao-contract#add-proposal) and then [`act_proposal`](https://github.com/near-daos/sputnik-dao-contract#approve-proposal) to vote on and approve the new member joining the DAO. + +While this works in theory, unfortunately, the `act_proposal` function requires a `proposal_id` that is returned from the `add_proposal` function. This is an issue for the following reasons: +1. With Keypom FC drops, there is no way to get a return value and use it to call another function. +2. SputnikV2 does not support custom `proposal_id`'s, meaning there is no way to hard code the `proposal_id` or inject the Keypom `drop_id` as the `proposal_id` ahead of time. + +### Middleman Solution + +Up until this point, the general flow for auto registering users is clear. An FC drop must be made that somehow invokes the `add_proposal` and `act_proposal` functions one after another. The problem with relying entirely on Keypom is that the return value for `add_proposal` must be known and used. + +This can be fixed by introducing a middleman contract. Rather than calling `add_proposal` and `act_proposal` directly through the FC drop, you can instead call **a single function on the middleman contract**. Once invoked, this middleman contract will then call `add_proposal`, parse the return value and call `act_proposal` in succession. + +While Keypom is extremely versatile, there are cases where custom behavior will be needed. By introducing a middleman, you can customize exactly what will happen when a key is used. + +In summary, rather than having the FC drop look as follows: + +``` +add_proposal + -> DAO Contract + -> Returns proposal ID +act_proposal (I need proposal ID somehow) + -> DAO Contract +``` + +The FC drop will instead do the following: +``` +Call middleman contract + add_proposal + -> DAO Contract + -> Returns proposal ID + Parse return value and get proposal ID + act_proposal + -> DAO Contract +``` + +--- + +## Full Solution Architecture +From above, here are the key features that need to be implemented. +### Keypom Solution +On the Keypom side, an FC drop will be used to call the middleman. This FC drop must: +- Only call the DAO bot once, to prevent double registration or multiple people registering with the same key. +- Send the DAO bot the `AddMemberToRole` proposal object *and* the desired DAO. +- Attach the wallet address for the account that will be onboarded to the middleman contract when auto-registering them into the DAO. + +### DAO Bot Solution + +The middleman contract that relays the add and act proposal functions can be referred to as the DAO bot. + +Recall that Keypom would need to be in its own special role. This was because Keypom was the `predecessor` for the `add_proposal` and `act_proposal` calls to the DAO contract. Now that the middleman is introduced, Keypom is no longer the predecessor. For this reason, the middleman DAO bot must have the special role instead. + +The middleman must: +- Ensure all incoming calls are made by Keypom and have a sufficient attached deposit. +- Take in a proposal object for adding a new member to a DAO (which includes the account ID of the new member). +- Take in a desired DAO contract and call `add_proposal` with the proposal object. +- Parse the return value which should be the proposal ID and then call `act_proposal` to automatically register the new member into the DAO. + +--- + +## Conclusion + +In this section, you explored and expanded on all the requirements for the auto-registration process. This started with using a Keypom linkdrop to facilitate [seamless wallet creation](#seamless-wallet-creation). Then, the onboarding process was automated and streamlined by introducing a [single-step registration](#optimizing-the-approach). This was done using a FunctionCall drop that would create and approve `AddMemberToRole` proposals as part of the linkdrop claiming process. + +However, you also saw the limitations of relying entirely on Keypom; that the `add_proposal` return value must be known and used. You solved this by introducing a [middleman contract](#middleman-solution) which would receive function calls from Keypom and execute the auto-registration. + +From this analysis, you set [concrete goals](#full-solution-architecture) for the Keypom FunctionCall drop and the middleman DAO bot contract. With these goals in mind, you can start to build out this solution! diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot-flow.drawio b/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot-flow.drawio new file mode 100644 index 00000000..8b853273 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot-flow.drawio @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot-flow.png b/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot-flow.png new file mode 100644 index 00000000..9c43387f Binary files /dev/null and b/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot-flow.png differ diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot-flow.svg b/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot-flow.svg new file mode 100644 index 00000000..53e2ede8 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot-flow.svg @@ -0,0 +1 @@ +
Prospective
Member
Prosp...
Claim their
FC Key
Claim their...
Is drop funder a
council member?
Is drop funder a...
Did Keypom call
DAO bot?
Did Keypom call...
Keypom DAO Bot
Keypom DAO Bot
Auto-register
new member
Auto-register...
DAO
DAOText is not SVG - cannot display \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot-fns.drawio b/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot-fns.drawio new file mode 100644 index 00000000..5496e3d3 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot-fns.drawio @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot.md b/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot.md new file mode 100644 index 00000000..a2180e74 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/daos/daobot.md @@ -0,0 +1,105 @@ +--- +sidebar_label: 'Designing the DAO Bot' +--- +# The DAO Bot + +## Introduction +In this section you'll be creating the middleman DAO bot contract in order to securely facilitate auto-registration into your DAO. This bot will be tailored according to the functionality and specifications found in the [Solution Architecture](architecture.md#keypom-solution). + +## Designing the DAO Bot + +[Recall](./architecture.md#dao-bot-solution) that the DAO bot needs accomplish the following: + +1. Ensure all incoming calls are made by Keypom and have a sufficient attached deposit. +2. Take in a proposal object for adding a new member to a DAO (which includes the account ID of the new member). +3. Take in a desired DAO contract and call `add_proposal` with the proposal object. +4. Parse the return value which should be the proposal ID and then call `act_proposal` to automatically register the new member into the DAO. + +With this in mind, the aim of this tutorial will be to write a Rust smart contract that will match the above properties. This process can be broken down into two stages: +1. Adding the proposal +2. Approving the proposal + +> If you wish to simply use the DAO bot without modifying it, you can move ahead to the [Final Product](./final.md) page. + +### Accessing the Code + +For this section of the tutorial, you will need to clone a separate [DAO bot repository](https://github.com/keypom/dao-bot/tree/main). From there you can navigate to the skeleton code folder found below. + +```bash +git clone https://github.com/keypom/dao-bot.git && cd src-skeleton +``` + +This is the skeleton code and will allow you to follow along as the DAO bot is built out. If you wish to examine the completed version, that can be found in the `src` folder. + +In the expandable section below, you can see the skeleton code from the file `lib.rs`. + +
+DAO Bot Skeleton Code +

+ +```rust reference +https://github.com/keypom/dao-bot/blob/2c3a7bac8b18e1134483f0736e2ca9e2152f8509/src-skeleton/lib.rs#L1-L123 +``` + +

+
+ + +You may notice a few structs and enums predefined; these are simply present to match the structures from the [SputnikV2 contract](https://github.com/near-daos/sputnik-dao-contract/tree/main/sputnikdao2/src) and allow the contract to work with proposal inputs. + +--- + +## Adding the Proposal + +Since the middleman contracts needs to call `add_proposal` on the DAO contract, this requires the use of cross-contract calls. For a refresher on making cross contract calls, see [NEAR docs](https://docs.near.org/develop/contracts/crosscontract#snippet-sending-information). + +The first thing that needs to be checked is that the attached deposit is enough to cover the add proposal cost and Keypom is the predecessor to the call. Once that's done, the DAO bot can make a cross contract call to the dao contract and call `add_proposal`, passing in the proposal object. + +```rust reference +https://github.com/keypom/dao-bot/blob/0d8abdb2151d224763aa7808cda88d58eb31e495/src-v1/lib.rs#L103-L120 +``` + +When the `add_proposal` function finishes executing, the DAO bot can then invoke a callback method to parse the returned proposal ID and call `act_proposal`. + + +## Approving the Proposal + +In the callback after the proposal has been added, the DAO bot will first check the success of the call and then parse the return value for the proposal ID. + +Using the proposal ID, the DAO bot can then make another cross contract call to the DAO contract and call `act_proposal` to approve the proposal. + +``` rust reference +https://github.com/keypom/dao-bot/blob/0d8abdb2151d224763aa7808cda88d58eb31e495/src-v1/lib.rs#L123-L143 +``` + +:::note Recall +The DAO bot has been added to the DAO in its own role. This means that when the DAO bot votes to approve, it automatically reaches a quorum and passes the proposal +::: + +--- + +## Final Code + +Putting everything together, the final code for the DAO bot smart contract should be: + +```rust reference +https://github.com/keypom/dao-bot/blob/0d8abdb2151d224763aa7808cda88d58eb31e495/src-v1/lib.rs#L1-L153 +``` + +--- + +## Security Concerns + +So far, you've seen both the FunctionCall drop and middleman DAO bot contract be created. You've seen how they communicate with each other and how the DAO bot can verify that only Keypom can interact with it. However there is a glaring security vulnerability. + +What happens if somebody else creates an identical FunctionCall drop to manipulate your DAO through the DAO bot against your wishes? How can the DAO bot be upgraded further to put control of your DAO back into your hands? + +--- + +## Conclusion + +In this tutorial, you've created the all new DAO bot on function call at a time. This started with verifying the calls were coming from Keypom with a sufficient attached deposit. Then, this was followed up by [calling `add_proposal`](#adding-the-proposal) using the received proposal and DAO contract. Finally, you parsed the return value and [called `act_proposal` using the `proposal_id`](#approving-the-proposal). + +As hinted in the final [security section](#security-concerns), the next tutorial will involve finding the DAO bot's vulnerabilities and further improving it. + + diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/daos/drop.md b/versioned_docs/version-2.0/Tutorials/Advanced/daos/drop.md new file mode 100644 index 00000000..a43abf22 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/daos/drop.md @@ -0,0 +1,267 @@ +--- +sidebar_label: 'Creating the Drop' +--- +# Creating the Drop + +## Introduction +In this section, you'll take the first step to creating the DAO onboarding experience by designing the FC drop. This drop will be tailored according to the functionality and specifications found in the [Solution Architecture](architecture.md#keypom-solution). + +Recall that the following properties must be met: + +* A [Function Call drop](../../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops.md) must be used and configured so that it calls a method on the DAO bot contract. +* The middleman contract will then invoke the `add_proposal` method, parse the return value and pass the proposal ID into the `act_proposal` method to approve. + +With this in mind, the aim of this tutorial will be to create the drop matching the above properties. This process can be broken down into two stages: + +1) Connect to the NEAR blockchain. +2) Create the drop with function call data. + +Starting at the `keypom-docs-examples` directory, navigate to the `advanced-tutorial/dao-onboarding-skeleton` folder and open the `createDaoDrop.js` file. + +```bash +cd advanced-tutorials/dao-onboarding-skeleton +``` + +There, you can see the following skeleton code in the file `createDaoDrop.js`. +``` js reference +https://github.com/keypom/keypom-docs-examples/blob/3d2ebdfdfe601bc7471a62e859682abaf9afb7cf/advanced-tutorials/dao-onboarding-skeleton/createDaoDrop.js#L1-L29 +``` + +:::note +While the skeleton code allows you to follow alongside the tutorial, the completed code can be found in `advanced-tutorial/dao-onboarding`. +::: + +--- + +## Connecting to NEAR +In this section, you'll be addressing the first step which is connecting to the NEAR network. + +This is done with `NEAR-API-JS` and consists of: + +* Selecting which network to connect to (testnet or mainnet). + +* Specifying the location where the keys are stored for the drop funder's account. This location is commonly in the `~/.near-credentials` folder on your local machine. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/3d2ebdfdfe601bc7471a62e859682abaf9afb7cf/advanced-tutorials/dao-onboarding/pre-security/createDaoDrop.js#L19-L39 +``` + +--- + +## Creating the Drop +In this section, you'll create the function call drop to meet the functional requirements defined earlier. + +### Function Call Drop Basics + +#### Initializing the SDK + +This process starts with calling the `initKeypom` function to initialize the SDK. + + +```js +// Change this to your account ID +const FUNDER_ACCOUNT_ID = "minqi.testnet"; +const NETWORK_ID = "testnet" +async function createDaoDrop() { + // Initiate connection to the NEAR blockchain. + const CREDENTIALS_DIR = ".near-credentials"; + ... + ... + let near = await connect(nearConfig); + + await initKeypom({ + near, + network: NETWORK_ID, + }); +} +``` + +After `initKeypom` is called, the FC Drop can be created by calling `createDrop` and adding an `fcData` parameter. + +#### Defining the Function Call Data + +The `fcData` is an object that defines the methods that will be called for any given key use: + + +```bash +fcData +โ””โ”€โ”€ methods +``` + +For this Keypom drop, only a single function call will be needed which invokes a method on the middleman contract. In this tutorial, that method is called `new_auto_registration`. + +```js +methods: [ + [ + "new_auto_registration" + ] +] +``` + +In reality, each method is not simply a string as shown above. The methods require the following parameters: + +- `receiverId`: The contract receiving the function call. +- `methodName`: The function to be called on the receiver contract. +- `args`: A stringified JSON object of all the arguments to be passed into `methodName`. +- `attachedDeposit`: The yoctoNear deposit attached to the function call when the key is used. + +For more information on the `methods` parameter, please see the [TypeDocs](../../../keypom-sdk/Core/interfaces/Method.md) + +In summary, the `fcData` should look something like this: + +```js +fcData: { + methods: [ + // First key use + [ + { + receiverId: DAO_BOT, + methodName: "new_auto_registration", + args: SOME_ARGS, + attachedDeposit: SOME_DEPOSIT + } + ], + ] +} +``` + +The required arguments and attached deposits will be covered in a later section. + +### Adding Proposal and Injected Arguments + +The DAO bot will need to know what proposal to add and so that information should be passed in as arguments. From the [SputnikV2 ReadMe](https://github.com/near-daos/sputnik-dao-contract#add-proposal), it can be seen that the proposal will need the following structure. +```json +{ + "proposal": { + "description": "Auto-Registering New Member", + "kind": { + "AddMemberToRole": { + "member_id": "new-moon-dao-member-1.testnet", + "role": "new-onboardee" + } + } + } +} +``` +:::caution +The `role` in the proposal **must already exist** in the DAO. This is because the `AddMemberToRole` proposal from SputnikV2 only works with existing roles. +::: + +In order for the onboarding to perform as expected, the `member_id` field must be set to the wallet address for the account that is onboarding. To do this you can use Keypom Arguments which are important pieces of information that can be passed into specified fields when a key is used. + +The following optional Keypom arguments are exposed for each individual method in the `fcData` alongside the required receiverId, methodName, attachedDeposit etc. + +They tell Keypom where to inject certain parameters for each function call. + +- `accountIdField`: The name of the account that is claiming the linkdrop. +- `dropIdField`: The [`dropId`](../../../keypom-sdk/Core/interfaces/Drop.md#dropid) of the drop that the claim is being called on. +- `keyIdField` The unique identifier, [`keyId`](../../../keypom-sdk/Core/interfaces/KeyInfo.md#keyid), of the key that is being used to claim. +- `funderIdField` the `accountId` of the person funding the drop. + +In this case, the `accountIdField` should be set to `proposal.kind.AddMemberToRole.member_id`. This will, upon the key being claimed, tell Keypom to inject the `accountId` of the user claiming into the argument's proposal object under the `kind.AddMemberToRole.member_id` field. + +In addition to the `accountIdField`, an attached deposit must be sent to cover the cost of the DAO's [proposal bond](https://github.com/near-daos/sputnik-dao-contract/blob/2b19edb50e4542e1b8a6769023f2318c70255ee9/sputnikdao2/src/policy.rs#L153C1-L154). In this case, the bond is set to 0.1 $NEAR. + +Finally, the FC drop should pass the desired DAO contract to the middleman DAO bot into the `dao_contract` argument. + +In summary, the final `fcData` should look as follows. + +```js +fcData: { + methods: [ + [ + { + receiverId: DAO_BOT_CONTRACT, + methodName: "new_auto_registration", + args: JSON.stringify({ + dao_contract: DAO_CONTRACT, + proposal: { + description: "Auto-Registering New Member", + kind: { + AddMemberToRole:{ + role: "new-onboardee-role" + } + } + } + }), + accountIdField: "proposal.kind.AddMemberToRole.member_id", + // Attached deposit of 0.1 $NEAR, the Sputnik proposal deposit, for when the receiver makes this function call + attachedDeposit: parseNearAmount("0.1") + } + ], + ] +} +``` + +### Gas Requirements +The final consideration to make is the amount of gas needed to claim the drop. To determine this amount, you can test your drop by using `create_account_and_claim`. To maximize gas usage, it is important to use an `account_id` of maximum length (64 characters). + +By default, MyNearWallet will attach 100 [TGas](https://docs.near.org/concepts/basics/transactions/gas#thinking-in-gas) to linkdrop claims. This can be used as a starting point when testing your drop but if more gas is needed, it can be overriden manually. + +If you were to use the default 100 TGas, it would work for claims to existing wallets but would throw an error for `create_account_and_claim`. This is because the drop uses more Gas when a new account is created. This can be seen in the screenshot below. To mitigate this, you can set the required gas to be 175 TGas. + +

failed txn not enough gas

+ +:::note +For the majority of use-cases, the 100 TGas default is more than enough. With the DAO bot, however, the middleman contract is quite complex and requires more Gas +::: + +To combat this, you can add a `requiredGas` argument to your `createDrop`. This will increase the overall amount of gas available to each key in your drop. + +```js +const TERA_GAS = 1000000000000; +let {keys, dropId} = await createDrop({ + account: fundingAccount, + numKeys: 1, + ... + requiredGas: (175*TERA_GAS).toString(), + ... +}) +``` + +With this modification, the [transaction](https://explorer.testnet.near.org/transactions/AoH2PDMvtdeNqwxjMJdPE6BmVxV1TKVGhdCybL9YsyG6) shows that the drop is claimed successfully and the user is registered into the DAO. + +### Final Drop Structure + +Putting it all together, the final drop structure should look something like this: + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/3d2ebdfdfe601bc7471a62e859682abaf9afb7cf/advanced-tutorials/dao-onboarding/pre-security/createDaoDrop.js#L48-L81 +``` + +--- + +## Creating Onboarding Links +The last step in this process is to create the links themselves so that you can easily register people into your DAO. For this tutorial, you will make use of MyNEARWallet's linkdrop claim flow which has the following URL: `https://testnet.mynearwallet.com/linkdrop/CONTRACT_ID/SECRET_KEY`. + +You can utilize the `formatLinkdropUrl` function for convenience. It can take a custom URL that contains `CONTRACT_ID` and `SECRET_KEY` and it will replace them with the contract ID and secret keys passed in. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/3d2ebdfdfe601bc7471a62e859682abaf9afb7cf/advanced-tutorials/dao-onboarding/pre-security/createDaoDrop.js#L84-L89 +``` + +--- + +## Final Code + +Putting everything together, the final code for the drop should be as shown below: + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/3d2ebdfdfe601bc7471a62e859682abaf9afb7cf/advanced-tutorials/dao-onboarding/pre-security/createDaoDrop.js#L1-L105 +``` + +:::note +This drop will not work until the DAO bot is created and deployed. The full script and process will be tested in the [Final Product](./final.md) section. +::: + +--- + +## Conclusion + +So far, you've broken down the DAO auto-registration tool into functional requirements. You then used them to write a script to create the accompanying drop. + +This included [creating the proposal and using the `accountIdField`](#adding-proposal-and-injected-arguments) to attach the wallet address for the account that will be onboarded. You then finished that off by [creating the linkdrops](#creating-onboarding-links) to distribute to prospective onboardees. + +In the next tutorial, you'll be creating the DAO bot that the FC drop you just created will be interacting with. + + diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/daos/final.md b/versioned_docs/version-2.0/Tutorials/Advanced/daos/final.md new file mode 100644 index 00000000..b8d54976 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/daos/final.md @@ -0,0 +1,178 @@ +--- +sidebar_label: 'Final Product' +--- +# Final Product +Welcome to the last section of this DAO auto-registration tutorial! Here, you'll be seeing the full toolchain in action. + +## Getting Started +To follow along on your own machine, you can clone the code from the [Keypom docs examples repository](https://github.com/keypom/keypom-docs-examples) and run the following command in the root folder `keypom-docs-examples`: + +``` bash +cd advanced-tutorials/dao-onboarding && yarn +``` + +:::note +If you have been following along and wish to run your own code, run: + +``` bash +cd advanced-tutorials/dao-onboarding-skeleton && yarn +``` +::: + +## Creating and Claiming the Drop + +Before you create and claim your drop, you must ensure that the DAO bot (`dao-bot.keypom.near` or `keypom-dao-bot.testnet`) holds its own special role on your DAO. This role must have permissions to add and vote on `AddMemberToRole` proposals. + +Additionally, as highlighted in the [drop creation](./drop.md#adding-proposal-and-injected-arguments) section, the role that you are planning to auto-register new members into must already exist. + +:::info note +This demonstration will be done on mainnet using `createDaoDrop-mainnet`. This is to provide you with visuals on [BOS](https://near.org/hack.near/widget/DAO.Profile?daoId=keypom-test.sputnik-dao.near). + +

bos showcase

+ +::: + +To execute the script, run the following command in the `advanced-tutorials/dao-onboarding` folder: + +```bash +node createDaoDrop-mainnet +``` + +This should give you the following output: +```bash +Receipts: DFf4iY9S4vUiVEZJy2neq4EhcKJXFKyoQqsDb2rvZrHF, 3E7S1h6dBmRZ14BA91CatTzaTEUmj3zLxyYAMG36MZpz + Log [v2.keypom.near]: Current Block Timestamp: 1685141815019548108 + Log [v2.keypom.near]: 21 calls with 105000000000000 attached GAS. Pow outcome: 1.8602935. Required Allowance: 20248156910387200000000 + Log [v2.keypom.near]: Total required storage Yocto 13850000000000000000000 + Log [v2.keypom.near]: Current balance: 1.223441, + Required Deposit: 0.2350981, + total_required_storage: 0.01385, + Drop Fee: 0, + Key Fee: 0 Total Key Fee: 0, + allowance: 0.0202481 total allowance: 0.0202481, + access key storage: 0.001 total access key storage: 0.001, + deposits less none FCs: 0.1 total deposits: 0.1 lazy registration: false, + deposits for FCs: 0.1 total deposits for FCs: 0.1, + uses per key: 1 + None FCs: 0, + length: 1 + GAS to attach: 100000000000000 + Log [v2.keypom.near]: New user balance 0.9883428 + Log [v2.keypom.near]: Fees collected 0 + + + Auto-Registration Links: + + https://wallet.near.org/linkdrop/v2.keypom.near/5JesG9FdfuFq3b3PA7p3NPY1SpZvi1DdtPs9ANumx9VRDE5iXyUsMT4Qcn132DFiDNiwjccFyoqAYGYP46UVuTVb +``` + +## Claiming the Drop and Viewing Changes + +For this example, the drop will be claimed with [`keypom-dao-tutorial-member.near`](https://explorer.near.org/accounts/keypom-dao-tutorial-member.near). The aim will be to auto-register this account into [MoonDAO](https://near.org/hack.near/widget/DAO.Profile?daoId=keypom-test.sputnik-dao.near). + +

explorer claim

+ +After claiming, you can check the DAO policy [here](https://near.org/hack.near/widget/DAO.Profile?daoId=keypom-test.sputnik-dao.near) in the *Policy* tab. + +

bos policy

+ +๐ŸŽ‰ As you can see, `keypom-dao-tutorial-member.near` has automatically been registered into the DAO by simply claiming a linkdrop! ๐ŸŽ‰ + +The transaction for this auto-registration can be found [here](https://explorer.near.org/transactions/2z9L9HcFKTJUANMcrQaSQMXsSbPihc472Lk83AgEtszH). + +### Additional Viewing Methods + +You can also view the proposal that was created and approved by the DAO bot by using the following: + +``` +near view keypom-test.sputnik-dao.near get_proposal '{"id":9}' +``` + +
+Auto-Registration Proposal +

+ +``` bash +View call: keypom-test.sputnik-dao.near.get_proposal({"id":9}) +{ + id: 9, + proposer: 'dao-bot.keypom.near', + description: 'mooooooooon', + kind: { + AddMemberToRole: { + member_id: 'keypom-dao-tutorial-member.near', + role: 'new-onboardee-role' + } + }, + status: 'Approved', + vote_counts: { 'Keypom DAO Bot': [ 1, 0, 0 ] }, + votes: { 'dao-bot.keypom.near': 'Approve' }, + submission_time: '1685145461041750017' +} +``` + +

+
+ +The DAO policy can also be checked through the command line as well: +``` +near view keypom-test.sputnik-dao.near get_policy' +``` + +
+DAO Policy +

+ +``` bash +View call: keypom-test.sputnik-dao.near.get_policy() +{ + roles: [ + { name: 'all', kind: 'Everyone', permissions: [], vote_policy: {} }, + { + name: 'new-onboardee-role', + kind:{ + Group: [ + 'keypom-dao-tutorial-member.near', + 'minlu.near', + 'mintlu.near' + ] + }, + }, + ... + ... + ], + default_vote_policy: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + proposal_bond: '100000000000000000000000', + proposal_period: '604800000000000', + bounty_bond: '100000000000000000000000', + bounty_forgiveness_period: '604800000000000' +} +``` + +

+
+ + + +## How You Can Use DAO Bot +This DAO bot contract you just made has been deployed to the account `keypom-dao-bot.testnet` and `dao-bot.keypom.near` and is open for you to use! You can create your own [FC drops](drop.md#final-code) to interface and experiment with it. + +:::caution +Prior to using the DAO Bot, ensure that it is given a role in your DAO capable of creating and approving `AddMemberToRole` proposals. For more info, see the [solution architecture](architecture.md#optimizing-the-approach) +::: + +If you wish to make modifications to the DAO bot, the source code is found [here](https://github.com/keypom/dao-bot). You can modify to your liking and deploy the contract as you see fit. + +:::note +The following functions have been included in the DAO bot in case you created a drop using older versions of the Keypom contract, such as `v1-4.keypom.near`. Note that you will need to deploy the DAO bot and modify these values yourself. +``` rust +pub fn change_keypom_contract(&mut self, new_contract: AccountId) +pub fn view_keypom_contract(&self) -> AccountId +``` +::: + +## Conclusion + +In this tutorial, you learned how you can use a [Keypom FC drop](drop.md) and a newly created [DAO bot](daobot.md) to automatically register new users into your DAO and get the onboarding process started right away. You also learned how to [use `keypom_args` to validate authenticity](security.md) of incoming calls from Keypom drops. + +This allows new members to focus on topics and discussions that are DAO specific rather than needing to worry about creating an account and learning the technical jargon of the NEAR blockchain. This onboarding flow also frees up the voting members to focus on the DAOs actual tasks rather than voting to approve new members. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/daos/introduction.md b/versioned_docs/version-2.0/Tutorials/Advanced/daos/introduction.md new file mode 100644 index 00000000..aba5f340 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/daos/introduction.md @@ -0,0 +1,77 @@ +--- +sidebar_label: 'Introduction' +--- +# Introduction +In this tutorial, you'll learn how to create a seamless DAO registration experience that allows you to onboard anyone directly into your DAO with the click of a link! + +--- + +## Background +DAOs are a popular topic in crypto and offer powerful on-chain governance features. They work very well in most cases but there are 2 key issues that Keypom will solve. + +1. There is a **high barrier to entry** for an everyday user who might not have a crypto wallet. +2. Being enrolled into the DAO is a **2 step process**. First, a proposal must be made and then it needs to be approved by an existing quorum of voting members. + +Both of these act as bottlenecks in attracting and onboarding new members. + +This is where Keypom can help. Using a [function call drop](../../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops.md), Keypom can automatically register users into your DAO **as part of the wallet creation process**. Not only does this eliminate the need for a wallet, but it also bypasses the 2 step approval process. + +> **NOTE** If someone has a wallet already, they can skip account creation and register their existing wallet into the DAO. + + +## Success Criteria + +This tutorial will cover the following requirements to achieve a seamless onboarding experience for new users. + +- Members don't need an existing wallet to join the DAO. +- The invitations do not require a 2 step process where a council votes and reaches a quorum for every single registration. +- The drop cannot be used for malicious purposes. + +With these requirements met, you will be able to seamlessly and automatically register new members into your DAO while maintaining the integrity of your DAO's members. + +:::info +This tutorial will have members registered into the MoonDAO, a [Sputnik V2](https://github.com/near-daos/sputnik-dao-contract) compatible DAO. + +

ticketing

+::: + +--- + +## Prerequisites + +For the this tutorial series, you can choose to follow along on your own machine. To do so, you must have the following: + +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [Keypom Core SDK](https://github.com/keypom/keypom-js/tree/main/packages/core#installation) + + +> **NOTE** If you want to reference the finished tutorial code, it can be found [here](https://github.com/keypom/keypom-docs-examples/tree/main/advanced-tutorials/dao-onboarding). + +--- + +## Creating your Project +In this section, you'll install the skeleton project and get familiar with the codebase. + +First, you'll want to clone the repo: + +```bash +git clone https://github.com/keypom/keypom-docs-examples.git && cd advanced-tutorials +``` + +Second, install all the dependencies + +``` +yarn install && cd advanced-tutorials/dao-onboarding-skeleton && yarn +``` + +At this point, all the dependencies should be installed and you should be in the `advanced-tutorials/dao-onboarding-skeleton` folder. Here you'll find the following files required to build out your app. + +```bash +/dao-onboarding-skeleton +โ””โ”€โ”€ configurations.js +โ””โ”€โ”€ createDaoOnboarding.js +โ””โ”€โ”€ package.json +โ””โ”€โ”€ view-roles.js +``` + +With this setup complete, you are ready to begin building the onboarding experience, starting by expanding upon the success criteria and breaking down the problem further. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/daos/security.md b/versioned_docs/version-2.0/Tutorials/Advanced/daos/security.md new file mode 100644 index 00000000..fa1bfb29 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/daos/security.md @@ -0,0 +1,331 @@ +--- +sidebar_label: 'DAO Bot Security Concerns' +--- +# DAO Bot Exploit Solution + +Up to this point, the DAO bot has a **major** security exploit. In this section, you'll learn about the exploit, how to fix it and how you can prevent similar exploits when writing Keypom compatible contracts in the future. + +--- + +## Breaking Down the Problem +To illustrate the exploit, a quick example can be analyzed: + +Min is a council member on MoonDAO. Since he has run onboarding campaigns through Keypom before, the DAO bot has its own role in MoonDAO. + +Ben is a malicious user and is jealous because he was never allowed to join MoonDAO. He intends on adding himself to MoonDAO without Min's consent. + +To do this, he creates an identical FunctionCall drop, exactly like the one Min used. This FunctionCall drop will invoke `new_auto_registration` on the DAO bot. + +[Recall](daobot.md#adding-the-proposal) that the DAO bot currently checks 2 things before performing the auto-registration: +1. The function call is coming from Keypom. +2. There is enough attached deposit to cover the proposal bond. + +Ben could create the an FC drop with the following method data, which would pass the first check. As part of the FC data, Ben would add an attached deposit of 0.1 $NEAR, which would pass the second check. + +At that point, when claimed, the checks would pass and the DAO bot would take the proposal object and pass it into the call to `add_proposal` on the MoonDAO contract. + +Since the DAO bot has the special role, it would automatically approve the proposal and Ben would be added to MoonDAO. + +In order to fix this, there needs to be a check in place to ensure that the FC drop originated from a trusted funder. + +
+Ben's Malicious Drop +

+ +```js +{ + receiverId: DAO_BOT_CONTRACT, + methodName: "new_auto_registration", + args: JSON.stringify({ + dao_contract: MOON_DAO, // Points to MOON DAO + proposal: { + description: "Auto-Registering New Member", + kind: { + AddMemberToRole:{ + member_id: BEN, // Ben is adding himself! + role: "new-onboardee-role" + } + } + } + }), + attachedDeposit: parseNearAmount("0.1") +} +``` + +

+
+ +:::warning +To summarize, since the DAO bot has the role to approve members *and* Keypom allows anyone to interact with the DAO bot through their own FC drops, a malicious drop could be created to add *anyone to any DAO*. + +To fix this, the DAO bot needs to check that the FC drop is coming from a trusted funder. +::: + +## Receiving the Drop Funder + +Since the DAO bot will need to check if the funder is trusted, the function interface for `new_auto_registration` should be updated to include a new argument, `funder`. + +```rs +new_auto_registration(dao_contract: AccountId, funder: AccountId, proposal: ProposalInput) +``` + +In order for this funder to be passed in, the FC drop will need to be modified. [Recall](drop.md#adding-proposal-and-injected-arguments) that Keypom can optionally inject important data into the outgoing arguments. This data can either be the: +- Drop ID +- Key ID +- Claiming account ID +- Drop funder ID + +In this case, the drop's funder ID can be injected into the `new_auto_registration` `funder` argument if the `funderIdField` is set to `funder`. Therefore, the FC drop should be modified accordingly: + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/3d2ebdfdfe601bc7471a62e859682abaf9afb7cf/advanced-tutorials/dao-onboarding/createDaoDrop.js#L57-L81 +``` + +This works great, but there is just one slight problem. Ben could hardcode the arguments to the method `new_auto_registration` and specify that the `funder` is Min, even though Ben created the drop. + +## Validating Keypom Args + +Validating what arguments came from Keypom, and what arguments were hardcoded by the funder is an extremely important topic to ensure the security of your smart contracts. Every time an FC drop is claimed, Keypom will *always* attach an extra parameter to the arguments of the function. This argument is `keypom_args` and is an object containing information about what was injected by Keypom. The `keypom_args` are created by Keypom and cannot be impersonated with any arguments. They are the canonical source of truth for what Keypom injected. + +```js +KeypomArgs { + account_id_field: String | undefined + drop_id_field: String | undefined + key_id_field: String | undefined + funder_id_field: String | undefined +} +``` + +This object is sent along any method call that Keypom makes and can be used to perform the validation. If the DAO bot contract took in the keypom args, and did an assertion that the `funder_id_field` was set to `funder`, then the exploit would be fixed. There would be *no* way for Ben to impersonate Min as the funder of the drop in order to gain access to MoonDAO. + +```rs +new_auto_registration(dao_contract: AccountId, funder: AccountId, proposal: ProposalInput, keypom_args: KeypomArgs) { + require!(keypom_args.funder_id_field == Some("funder".to_string()), "BEN IS MALICIOUS! Funder is not Min!"); +} +``` + +--- + + +## Checking If the Funder is Trusted +At this point, the DAO bot knows the funder's account ID and has validated that they created the drop. The next step is to check if the funder holds a trusted role within the DAO. + +While the definition of "trusted role" can change between DAOs, for this tutorial, this role will be `council`. + +![Example banner](./daobot-flow.svg) + +:::note +If your DAO wishes to change the definition of a "trusted role", you are free to modify and deploy your own DAO bot contract as you see fit. +::: + +### Approach + +If the DAO bot was able to query for the policy information, then it could filter through the roles and find `council`. At this point, it could simply check if the funder is a member of `council` and then initiate the auto-registration flow + +By looking at the [SputnikV2 contract](https://github.com/near-daos/sputnik-dao-contract/blob/main/sputnikdao2/src/policy.rs), you can see that each DAO's `Policy` has a `roles` vector. +```rust +pub struct Policy { + /// List of roles and permissions for them in the current policy. + pub roles: Vec, + ... +} +``` + +This vector contains each role their members. +```rust +pub struct RolePermission { + /// Name of the role to display to the user. + pub name: String, + /// Kind of the role: defines which users this permissions apply. + pub kind: RoleKind, + ... +} + +pub enum RoleKind { + /// Matches everyone, who is not matched by other roles. + Everyone, + /// Member greater or equal than given balance. Can use `1` as non-zero balance. + Member(U128), + /// Set of accounts. + Group(HashSet), +} +``` + +A sample DAO policy can be seen below: + +
+Sample DAO policy +

+ +``` bash +View call: moondao.sputnikv2.testnet.get_policy() +{ + roles: [ + { name: 'all', kind: 'Everyone', permissions: [], vote_policy: {} }, + { + name: 'council', + kind: { Group: [ 'minqi.testnet' ] }, + permissions: [ + 'add_member_to_role:VoteRemove', + 'upgrade_self:VoteRemove', + 'policy:VoteReject', + 'bounty_done:AddProposal', + 'policy:VoteRemove', + 'set_vote_token:VoteReject', + 'upgrade_remote:AddProposal', + 'remove_member_from_role:VoteApprove', + 'add_bounty:VoteRemove', + 'vote:VoteApprove', + '*:Finalize', + 'bounty_done:VoteApprove', + 'transfer:VoteRemove', + 'add_bounty:VoteReject', + 'add_member_to_role:VoteReject', + 'set_vote_token:VoteRemove', + 'transfer:VoteApprove', + 'transfer:VoteReject', + 'config:VoteReject', + 'call:VoteReject', + 'remove_member_from_role:VoteReject', + 'policy:AddProposal', + 'bounty_done:VoteRemove', + 'set_vote_token:AddProposal', + 'upgrade_self:AddProposal', + 'set_vote_token:VoteApprove', + 'config:VoteApprove', + 'policy:VoteApprove', + 'add_bounty:VoteApprove', + 'remove_member_from_role:VoteRemove', + 'transfer:AddProposal', + 'upgrade_remote:VoteReject', + 'call:VoteApprove', + 'add_member_to_role:AddProposal', + 'call:AddProposal', + 'call:VoteRemove', + 'config:AddProposal', + 'remove_member_from_role:AddProposal', + 'upgrade_remote:VoteApprove', + 'upgrade_remote:VoteRemove', + 'upgrade_self:VoteApprove', + 'upgrade_self:VoteReject', + 'vote:VoteReject', + 'vote:VoteRemove', + 'vote:AddProposal', + 'add_member_to_role:VoteApprove', + 'config:VoteRemove', + 'add_bounty:AddProposal', + 'bounty_done:VoteReject' + ], + vote_policy: { + add_member_to_role: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + policy: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + vote: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + set_vote_token: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + remove_member_from_role: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + transfer: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + add_bounty: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + upgrade_self: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + bounty_done: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + call: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + config: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + upgrade_remote: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] } + } + }, + { + name: 'Keypom DAO Bot', + kind: { Group: [ 'keypom-dao-bot.testnet' ] }, + permissions: [ + 'add_member_to_role:VoteApprove', + 'add_member_to_role:VoteRemove', + 'add_member_to_role:VoteReject', + 'add_member_to_role:AddProposal' + ], + vote_policy: { + transfer: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 1 ] }, + upgrade_self: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 1 ] }, + remove_member_from_role: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 1 ] }, + set_vote_token: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 1 ] }, + bounty_done: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 1 ] }, + policy: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 1 ] }, + add_member_to_role: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 1 ] }, + call: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 1 ] }, + config: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 1 ] }, + upgrade_remote: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 1 ] }, + vote: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 1 ] }, + add_bounty: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 1 ] } + } + } + ], + default_vote_policy: { weight_kind: 'RoleWeight', quorum: '0', threshold: [ 1, 2 ] }, + proposal_bond: '100000000000000000000000', + proposal_period: '604800000000000', + bounty_bond: '100000000000000000000000', + bounty_forgiveness_period: '604800000000000' +} +``` + +

+
+ +### Verifying Funder and Getting DAO Policy + +The first step is to call `get_policy` on the DAO contract. After `get_policy` is called, a callback function is invoked to receive and parse the policy. + +``` rust reference +https://github.com/keypom/dao-bot/blob/2c3a7bac8b18e1134483f0736e2ca9e2152f8509/src/lib.rs#L103-L119 +``` + +### Ensuring Funder is Council +After the policy is received, the council role is found using a filter. The role's hashset is then searched to see if the funder exists in that set. If yes, then the auto-registration continues and `add_proposal` is called. + +```rust reference +https://github.com/keypom/dao-bot/blob/2c3a7bac8b18e1134483f0736e2ca9e2152f8509/src/lib.rs#L122-L164 +``` + +--- + +## Human Gating the DAO Bot (Mainnet Only) +With the introduction of the [SoulBound Token Standard](https://github.com/robert-zaremba/NEPs/blob/robert/nep-sbt/neps/nep-0393.md), a proof-of-humanity protocol was implemented on NEAR, known as [I-Am-Human](https://i-am-human.app/). With this came the ability to human-gate certain actions, such as self-nominating or participating in governance. + +As DAOs are critical in governance and community, the need to human-gate these automatic DAO registrations became a high priority. By leveraging the I-Am-Human Registry's [`is_human`](https://github.com/near-ndc/i-am-human#additional-queries) human checker, you can open up the option for you DAO auto-registrations to be human-gated using the following code to parse the `is_human` response. + +``` rust reference +https://github.com/keypom/dao-bot/blob/a19a2d29b42514a1e9d5f11c993b79f207c4a00f/src/lib.rs#L158-L180 +``` + +:::info +This check will only be performed **if specified in the drop**! By default, human-gating is turned **off**. + +Below is an example of a drop that is human-gated. Notice the `human_only` parameter! +::: + +``` js reference +https://github.com/keypom/keypom-docs-examples/blob/290cbce2c939573dbc8cb2b03598c2b2af5f91c2/advanced-tutorials/dao-onboarding/createDaoDrop-mainnet.js#L48-L84 +``` + + +--- + +## Full Code +The code for this can be seen below: + +```rust reference +https://github.com/keypom/dao-bot/blob/2c3a7bac8b18e1134483f0736e2ca9e2152f8509/src/lib.rs#L103-L164 +``` + +:::info +The full code for the completed DAO bot can be found [here](https://github.com/keypom/dao-bot/blob/main/src/lib.rs). +::: + +--- + + +## Conclusion + +In this tutorial, you learned how people can use [malicious drops](#breaking-down-the-problem) to exploit your DAO. You then saw how you can protect yourself, by checking the incoming call's drop funder and their roles in your DAO. This started with [receiving the drop funder](#receiving-the-drop-funder) by using `keypom_args`, then [verifying injected arguments](#checking-the-drop-funder) and finally parsing the DAO policy and [checking the funder's roles](#ensuring-funder-is-council) in the DAO. + +All of this work ensures that only approved members (such as Council) can use Keypom FC drops to create auto-registration campaigns for your DAO. This helps ensure the integrity of your DAO as you bring on more new members. + +This concept and approach can be used any time where important assets or processes are gated only by arguments such as a DAO contract or NFT series ID. It is important to ensure that the incoming drop is coming from a trusted source and that the arguments are validated as having been injected by Keypom. This will protect you from malicious actors creating identical Keypom drops to exploit your products. + +In the next section, you'll be reviewing all of your work so far by testing the whole auto-registration system. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/homepage.md b/versioned_docs/version-2.0/Tutorials/Advanced/homepage.md new file mode 100644 index 00000000..4d8ecddb --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/homepage.md @@ -0,0 +1,6 @@ +--- +sidebar_label: 'Coming Soon...' +--- +# Advanced Tutorials + +Advanced Tutorials are in progress! \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/multi-sig/concept.md b/versioned_docs/version-2.0/Tutorials/Advanced/multi-sig/concept.md new file mode 100644 index 00000000..07faeccd --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/multi-sig/concept.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Concept' +--- +# Concept \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/multi-sig/final.md b/versioned_docs/version-2.0/Tutorials/Advanced/multi-sig/final.md new file mode 100644 index 00000000..d90001ba --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/multi-sig/final.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Final Product' +--- +# Final Product \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/multi-sig/skeleton.md b/versioned_docs/version-2.0/Tutorials/Advanced/multi-sig/skeleton.md new file mode 100644 index 00000000..d5e552ef --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/multi-sig/skeleton.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Skeleton Code' +--- +# Skeleton Code \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/subscriptions/final.md b/versioned_docs/version-2.0/Tutorials/Advanced/subscriptions/final.md new file mode 100644 index 00000000..d90001ba --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/subscriptions/final.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Final Product' +--- +# Final Product \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/subscriptions/introduction.md b/versioned_docs/version-2.0/Tutorials/Advanced/subscriptions/introduction.md new file mode 100644 index 00000000..a7982f0e --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/subscriptions/introduction.md @@ -0,0 +1,18 @@ +--- +sidebar_label: 'Introduction' +--- +# Introduction + +Recurring payments are quite a common situation. Letโ€™s say you need to send a contractor $50 USDC every week for 10 weeks. With Web2, you would need to provide a payment method and trust the end user with this sensitive information. + +Using Keypom, you can eliminate this risk by sending them a key with limited funds attached. Instead of exposing your private information, you could create a key with 10 uses, usable once a week. You can then pre-load $500 USDC for the 10 weeks, or $50 USDC for the first week and fund the rest as the work continues. At that point, you would simply hand over the key to the user and they can claim once a week. + +

+ ticketing +

+ +In this tutorial, you'll learn how to utilize Keypom to create Web3 recurring payments. + +:::info +๐Ÿšง Full tutorial coming soon... ๐Ÿšง +::: \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/subscriptions/skeleton.md b/versioned_docs/version-2.0/Tutorials/Advanced/subscriptions/skeleton.md new file mode 100644 index 00000000..d5e552ef --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/subscriptions/skeleton.md @@ -0,0 +1,4 @@ +--- +sidebar_label: 'Skeleton Code' +--- +# Skeleton Code \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/analytics.md b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/analytics.md new file mode 100644 index 00000000..ea0d32c3 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/analytics.md @@ -0,0 +1,80 @@ +--- +sidebar_label: 'View Event Analytics' +--- +# View Event Analytics +## Introduction +In this section you'll learn how to track your event's analytics, such as number of attendees that showed up, those that claimed POAPs and more! This can be broken down into two approaches: + +1) Creating a script. +2) Using existing BOS tools. + +The focus for now will be the script. The next tutorial section will showcase the existing BOS tools. + +Starting at the `keypom-docs-examples` directory, navigate to the `ticket-app-skeleton/others` folder and open the `event-analytics.js` file. + +```bash +cd advanced-tutorials/ticket-app-skeleton/others +``` + +There, you can see the following skeleton code in the file `event-analytics.js`. +``` js reference +https://github.com/keypom/keypom-docs-examples/blob/449992de80888934dcbccfadefd88601d9d6638d/advanced-tutorials/ticket-app-skeleton/others/event-analytics.js#L1-L31 +``` + +--- + +## Connecting to NEAR +Connecting to the NEAR network is done with `NEAR-API-JS` and consists of: + +* Selecting which network to connect to (testnet or mainnet). + +* Specifying the location where the keys are stored for the drop funder's account. This location is commonly in the `~/.near-credentials` folder on your local machine. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/449992de80888934dcbccfadefd88601d9d6638d/advanced-tutorials/ticket-app/others/event-analytics.js#L21-L38 +``` + +--- + +## Getting Drop and Keys +Here, you want to make sure you get the proper drop that represents your event. To do this, you want to use the drop's `dropId`. In order to include the keys in the returned data, ensure that `withKeys` is true. + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/449992de80888934dcbccfadefd88601d9d6638d/advanced-tutorials/ticket-app/others/event-analytics.js#L42-L55 +``` +:::note +If you don't have your `dropId`, you can use a key from the drop as well. This is done by passing in either `publicKey` or `secretKey` into `getDropInformation` +::: + +The total number of tickets can also be found by using the drop's `next_key_id`. This will be helpful to determine how many keys have been fully claimed + +--- + +## Compiling Data +From the original [design of the ticket drop](architecture.md#keypom-solution), you know the following. + +* The first key use indicates when an attendee is scanned into the event. +* The second key use sends the attendee a POAP, after which the key is deleted + +From this, you can derive the following about a key's [remaining uses](../../../keypom-sdk/Core/interfaces/ProtocolReturnedKeyInfo.md#remaining_uses). + +* `remaining_uses == 2`: the ticket has not yet been scanned, hence the ticket holder did not attend. +* `remaining_uses == 1`: the attendee was scanned in and thus attended + +Notice how there is no case for when `remaining_uses` = 0. This is because when keys are fully used, they are deleted. This is when collecting the total number of keys above becomes helpful. The number of fully used keys can be found by subtracting the number of found keys from the total. + +* `drop.next_key_id - keys.length` = number of fully used keys. + +All this can be put into the following code block. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/449992de80888934dcbccfadefd88601d9d6638d/advanced-tutorials/ticket-app/others/event-analytics.js#L57-L73 +``` + +--- + +## Conclusion +In this short bonus section, you saw how to get analytics for your events. This consisted of getting the keys from your drop and keeping track of the number of remaining uses for each key. + +In the following section, you'll see some pre-built BOS tooling for a no-code solution! \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/architecture.md b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/architecture.md new file mode 100644 index 00000000..590d1839 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/architecture.md @@ -0,0 +1,69 @@ +--- +sidebar_label: 'Solution Architecture' +--- +# Solution Architecture +In this section, you'll break down the requirements of the ticketing system in order to better understand how to create a solution architecture. This means translating the features from the [ticketing introduction](introduction.md) into tangible goals for the specific Keypom drop and its configurations. + +## Breaking Down the Problem +Recall from earlier, the following features are needed: + +### No wallet is needed to enter + +With traditional events, you would need to burn an NFT in order to gain entry to the event. This model requires the attendee to have a valid wallet with enough $NEAR to cover transaction costs. + +With a Keypom access key, all you need is the private key to gain entrance. This can be turned into a simple QR code that is scanned at the door to gain entrance. + +### Each ticket is unique and cannot be passed-back + +In order to satisfy the requirement that each ticket must be unique and can only be scanned once, the key should be used to sign a simple transaction when it's scanned. This will prevent ticket pass-backs since the host can check the on-chain status of each key. If it's been used already, the host can deny entry. + +When the host scans the QR code and signs the transaction using the key, it should simply modify some state on the contract reflecting that the key has been used. It shouldn't transfer $NEAR to anyone or create any accounts and should be a lightweight transaction on-chain. + +By default, every key has a counter of how many uses it has left before being deleted. In the above scenario, you could create a key with 1 use and once it has been scanned, it will be deleted. If the same QR code would be given to multiple people, the host would realize that the key no longer exists and deny entry. + +To make this transaction extremely lightweight, Keypom allows keys to have `null` function calls whose entire purpose is to decrement the key use counter to prove that the key has been used. These special types of function calls use up a very small amount of gas and are extremely cheap to execute. + +### Attendees are not required to have wifi at the door. + +If the ticket is just a private key in the form of a QR code, the attendee only needs to keep a screenshot or the webpage open on their phone to gain entry to the event. In addition, Apple users can add it to their Apple Wallets as well. This eliminates the need for everyone to have wifi as only the hosts that are scanning and making transactions need wifi to admit attendees. + +### Attendees can setup a new NEAR wallet + +Up until this point, tickets are single-use function calls that execute a `null` method on Keypom. In order for attendees to receive a NEAR wallet after the event for free, the key can be set with 2 uses instead of 1. The first is the `null` method and the second is pre-loaded with a small amount of $NEAR. This $NEAR will cover costs for account creation and sponsor their first couple transactions. + +### NFT POAP available for attendees + +In order to send the attendees a POAP, the second key use will need to not only contain a small amount of $NEAR but also mint an NFT to their new or existing NEAR wallet. This can be done by call a minting function on an existing NFT contract that will create an NFT and send it to the account. + +### Attendance required for POAP + +Currently, anyone with a ticket could manually claim the key (sign transactions) using the Keypom SDK. This means that people could first claim the `null` case and then claim the key again to receive the NFT without physically showing up. + +To solve this, the first key use can be protected with a [password](../../../Concepts/KeypomProtocol/GithubReadme/password-protect.md) that only the host knows. This password will be provided when the QR code is scanned. By password protected the uses, the only way to receive the NFT even if you have the ticket, is to be physically scanned by the host. + + +## Keypom Solution + +From above, the drop must have the following properties to function as intended: + +* A [Function Call drop](../../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops.md) must be used and configured so that each key has 2 uses. +* The first key use is password protected and `null` (for when the host scans attendees into the event). +* The second key use will have a small amount of $NEAR to cover account creation costs and sponsor the first few transactions. +* The second key use will also call `nft_mint` on an NFT contract which will send the new or existing account a POAP. + +:::tip +The first key use being `null` will allow for a lightweight transaction on-chain to reflect the key use decrement without needing to transfer any $NEAR to anyone or create any accounts. +::: + +A flow chart of this process can be seen below. + +

+ ticketing +

+ +--- + +## Conclusion +In this section, you learned the solutions that would help meet the required features outlined in the introduction. These included using an access key as a ticket to remove the need for attendees to have both a wallet and an internet connection at the door. You also saw how using a multi-use function call drop could allow you to add a Proof-of-Attendance NFT to gift attendees who show up to your event. + +In the next section, you'll be taking the Keypom drop architecture you just created and using it to create the drop. diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/bos-tool.md b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/bos-tool.md new file mode 100644 index 00000000..f64f87c3 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/bos-tool.md @@ -0,0 +1,61 @@ +--- +sidebar_label: '๐Ÿš€ BOS Version' +--- +# BOS Version +During the [ETHGlobal Waterloo Hackathon](https://ethglobal.com/showcase/keypom-x-bos-event-ticketing-pow2e), a chunk of this tutorial was ported over to BOS. This section is a quick guide on how to use it. + +> If you run into any bugs or issues, don't hesitate to reach out to [Min on Telegram](https://t.me/minlu00)! + +## Using the BOS Tool +The BOS version of the ticket app is located [here](https://near.org/mintlu.near/widget/kp-ticket-homepage). On this page, you can view your previous tickets, as well as create a new ticket drop. + +

+ BOS ticketing +

+ +:::note +**All** your drops will appear in the viewer, not just the ticket drops. +::: + +### Creating Ticket Drops +This section of the tool allows you to create a standard ticket drop. These drops use the following structure: +- 2 Key uses + - First is null and password protected. + - Second mints the POAP +- A customizable password and POAP. The POAP is minted as part of a series on `nft-v2.keypom.near` + +

+ create ticketing drop +

+ +When using the tool, there are a few tips to keep in mind: +- **Save your POAP information before creating the drop** + - This is **very** important, if you do not, the drop will be created without the POAP ๐Ÿ˜ข +- The name of the event will automatically be hyphenated and lowercased +- When creating the drop, the password will not appear in the transaction information. This will populate after you press "Confirm" +

+ bad ticketing password +

+ +--- + +## Using the Scanner +To open the scanner on your own machine, you can clone the code from the [Keypom Docs Examples](https://github.com/keypom/keypom-docs-examples) repository and run the following command in the root folder `keypom-docs-examples/`: + +``` bash +cd advanced-tutorials/ticket-app-mainnet && yarn && yarn start +``` + +This should bring you to the following page at `localhost:1234` + +

+ ticketing +

+ +From there, you can navigate to the following URL: +``` +http://localhost:1234/v2.keypom.near/scanner +``` + +It will immediately prompt you for a password. This is the password you set in the [creating tickets section](#creating-ticket-drops). If you enter it incorrectly, you can refresh the page and re-enter the password. From there, you can begin presenting tickets and allowing people into your event! + diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/drop-test.md b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/drop-test.md new file mode 100644 index 00000000..06cb9911 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/drop-test.md @@ -0,0 +1,266 @@ +--- +sidebar_label: 'Testing the Drop' +--- +# Testing the Drop + +## Introduction +In the last section you designed and created a drop according to the specifications you learned about in the [Solution Architecture](architecture.md#keypom-solution). + +In this tutorial, you'll create a generalized method that will determine whether or not to allow someone entry into the event. It will be used to both test the drop logic and power the core functionality of the ticketing app. + +Starting at the `keypom-docs-examples` directory, navigate to `advanced-tutorials/ticket-app-skeleton/utils` folder and open the `allowEntry.js` file. + +```bash +cd advanced-tutorials/ticket-app-skeleton/utils +``` + +This should show the following skeleton code. + +``` js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app-skeleton/utils/allowEntry.js#L1-L14 +``` + +--- + +## Host Claiming Code + +In order to test the drop logic, a utility function will be created to emulate the host scanning tickets at the door and will be used by the frontend. + +The primary purpose of this function is to ingest a private key and password, and determine whether or not a ticket is valid. This means it will check for a few conditions before returning a success value. + +* The ticket is valid and has not been scanned yet. +* The password entered by the host was correct and the claim was successful + +The `allowEntry` utility function takes in a private key, and a `basePassword`. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/utils/allowEntry.js#L9-L49 +``` + +## Testing Logic + +Now that the utility function has been created, it can be used to test the drop logic. This will be done in a new file called `testTickDrop.js` that will live in the same util directory. It will contain two different test functions: + +* `wrongPasswordCheck` - This will test the case where the wrong password is used to claim the ticket. +* `doubleClaimCheck` - This is meant to check for invalid tickets. In this case, it will try to claim the same ticket twice in a row. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app-skeleton/utils/testTickDrop.js#L1-L26 +``` + +With both the drop created utility function defined, some code can be written to test the actual logic to ensure that the ticket claiming process works as expected. This will be broken down into phases, similar to the actual ticketing experience. + +### Wrong Password Check + +The first phase of the ticketing experience can be labelled as `pre-entry`, when the attendee is looking to enter the event. Here, you want to ensure that only the host can allow them in, meaning the first key use must only be claimable with the correct password. + +The following code can be used to test this logic, following the drop creation. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/utils/testTickDrop.js#L5-L30 +``` + +It's expected that after claiming with the incorrect password, `allowEntry` will return `false` since the key use remains at 1. However, once the correct password is provided, the `allowEntry` function should return `true`. In the tests, an `assert` function is used to ensure the proper behavior. + +### Preventing Multiple Entries + +Once an attendee has been scanned into the event, they may try to give their ticket to someone else. To test and prevent this, `allowEntry` can be called multiple times on the same ticket. It is expected that the first call should return `true` but once it scans the same ticket again, `false` should be returned. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/utils/testTickDrop.js#L32-L57 +``` + +With the drop functionality tested, you can be confident in the logic behind the scenes and focus on the app behavior. + +--- + + +## Full Code +Now that everything has been put together, the final code can be seen below. + +
+Full Testing Code +

+ +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/utils/testTickDrop.js#L1-L75 +``` +

+
+ + +--- + +## Running the Script +Here, you'll learn how to run the code that was just covered, and what to expect. It's assumed that you have already cloned the code from the [Keypom Docs Examples](https://github.com/keypom/keypom-docs-examples) repo. + +:::caution +Prior to running these scripts, ensure you replace all instances of `minqi.testnet` with an account found in your `~/.near-credentials` folder +::: + +To run the script, run the following command inside the `keypom-docs-examples/advanced-tutorials/ticket-app-skeleton` directory: + +```bash +yarn test-ticket-drop +``` + +:::note +If you'd like to run the already completed code found in the `ticket-app` directory instead of the skeleton code, run the same `yarn test-ticket-drop` command but inside of the `keypom-docs-examples/advanced-tutorials/ticket-app` directory instead. +::: + +This should return a successful test after outputting logs: + +```bash +Password Test Responses: +Expected false, got: false +Expected true, got: true + +Double Claim Test Responses: +Expected true, got: true +Expected false, got: false +``` + +
+Full Script Output +

+ +```bash +Retrying transaction v2.keypom.testnet:2JdTtqWLNqLUjBL9CYJ1qkdUtYpDLXydvnCfHiW3LG3S with new nonce. +Receipts: DL3AwUHW22wqEvJ24Soh39Zgsa8iQhyNNKsqzfUggDCn, Dt1yEoGZ36avyKqwF82GL54emJkfmUx2AM3fUtkhC1Vv + Log [v2.keypom.testnet]: Current Block Timestamp: 1680294425065581261 + Log [v2.keypom.testnet]: 21 calls with 105000000000000 attached GAS. Pow outcome: 1.8602935. Required Allowance: 20248156910387200000000 + Log [v2.keypom.testnet]: Total required storage Yocto 16330000000000000000000 + Log [v2.keypom.testnet]: Current balance: 3.5921299, + Required Deposit: 0.2578263, + total_required_storage: 0.01633, + Drop Fee: 0, + Key Fee: 0 Total Key Fee: 0, + allowance: 0.0404963 total allowance: 0.0404963, + access key storage: 0.001 total access key storage: 0.001, + deposits less none FCs: 0.1 total deposits: 0.1 lazy registration: false, + deposits for FCs: 0.1 total deposits for FCs: 0.1, + uses per key: 2 + None FCs: 1, + length: 1 + GAS to attach: 100000000000000 + Log [v2.keypom.testnet]: New user balance 3.3343036 + Log [v2.keypom.testnet]: Fees collected 0 +Retrying transaction nft-v2.keypom.testnet:2iHrE9ooY2N4kUn9eqsScAyNjXkRkUBiQdzxYsXwFawm with new nonce. +Receipts: 6jzxKRXmGjrtSKP9V38puWLZPcDHaVYRrohtj29rsMxR, FCmjrSPxuyKEXdghJAkrz8H8AH3GaCPnceoZKuHazmrN + Log [v2.keypom.testnet]: Current Block Timestamp: 1680294427597789158 + Log [v2.keypom.testnet]: 21 calls with 105000000000000 attached GAS. Pow outcome: 1.8602935. Required Allowance: 20248156910387200000000 + Log [v2.keypom.testnet]: Total required storage Yocto 16330000000000000000000 + Log [v2.keypom.testnet]: Current balance: 3.6040689, + Required Deposit: 0.2578263, + total_required_storage: 0.01633, + Drop Fee: 0, + Key Fee: 0 Total Key Fee: 0, + allowance: 0.0404963 total allowance: 0.0404963, + access key storage: 0.001 total access key storage: 0.001, + deposits less none FCs: 0.1 total deposits: 0.1 lazy registration: false, + deposits for FCs: 0.1 total deposits for FCs: 0.1, + uses per key: 2 + None FCs: 1, + length: 1 + GAS to attach: 100000000000000 + Log [v2.keypom.testnet]: New user balance 3.3462426 + Log [v2.keypom.testnet]: Fees collected 0 +Retrying transaction nft-v2.keypom.testnet:CysD3CnodxvarnxUpQKKWWV1x9uhjEkCbWosy1DuDo7D with new nonce. + + + Ticket Links: + + http://localhost:1234/v2.keypom.testnet/3aJq6s8pNYFGbuUVG5fj7nJ9bpfKZD7iH4oak27yZnjQytcyCAFMioJEZrVJBf3itMgrs3gm8U1UszewfhXbfKUH + + + + + Ticket Links: + + http://localhost:1234/v2.keypom.testnet/2KxZarBh9hWy7JZGDvsJhdzP8Q3JtCy7ocZ4hvohHKEsSNjxTx3LWd8EDpHNfD2du8MQVftCNJKRCp99At1qigQU + + +Claiming with wrong password... +Receipt: BHH2ENLdWLpYDQDD8SmgbAXzVFGi9odnGwhgHxg6ifCR + Log [v2.keypom.testnet]: Beginning of process claim used gas: 479192976105 prepaid gas: 100000000000000 + Log [v2.keypom.testnet]: passed global check + Log [v2.keypom.testnet]: hashed password: [97, 68, 238, 197, 167, 108, 73, 163, 74, 105, 140, 127, 22, 87, 3, 98, 76, 179, 110, 208, 118, 51, 58, 3, 88, 44, 22, 240, 45, 89, 85, 65] + Log [v2.keypom.testnet]: actualPass password: [61, 214, 44, 95, 159, 234, 2, 185, 182, 48, 134, 31, 65, 88, 184, 51, 51, 13, 201, 173, 75, 158, 56, 59, 33, 46, 185, 178, 239, 3, 44, 94] cur use: 1 + Log [v2.keypom.testnet]: Incorrect password. Decrementing allowance by 1244250690277300000000. Used GAS: 2442506902773 + Log [v2.keypom.testnet]: Allowance is now 39252063130497100000000 + Log [v2.keypom.testnet]: Invalid claim. Returning. +Claim has failed, check password +claiming with correct password... +Receipt: 4gAycg2B1jVNoJtUT3snHWDA1Ffdkxt1oPu8vH1TwoSC + Log [v2.keypom.testnet]: Beginning of process claim used gas: 479192976105 prepaid gas: 100000000000000 + Log [v2.keypom.testnet]: passed global check + Log [v2.keypom.testnet]: hashed password: [61, 214, 44, 95, 159, 234, 2, 185, 182, 48, 134, 31, 65, 88, 184, 51, 51, 13, 201, 173, 75, 158, 56, 59, 33, 46, 185, 178, 239, 3, 44, 94] + Log [v2.keypom.testnet]: actualPass password: [61, 214, 44, 95, 159, 234, 2, 185, 182, 48, 134, 31, 65, 88, 184, 51, 51, 13, 201, 173, 75, 158, 56, 59, 33, 46, 185, 178, 239, 3, 44, 94] cur use: 1 + Log [v2.keypom.testnet]: passed local check + Log [v2.keypom.testnet]: Key usage last used: 0 Num uses: 2 (before) + Log [v2.keypom.testnet]: Key has 1 uses left. Decrementing allowance by 10000000000000000000000. Allowance left: 29252063130497100000000 + Log [v2.keypom.testnet]: Total storage freed: 0. Initial storage: 33083530. Final storage: 33083530 + Log [v2.keypom.testnet]: Empty function call. Returning. +Receipts: D2TGQDXYR4um28CgTt8Z1aU1LMSABMChW9MZJPfVBcpd, 7FKbgHx6eFnfMM15B1Tw7U8wpeQe2WKwYUQG7Hbqe69L + Log [v2.keypom.testnet]: Current Block Timestamp: 1680294442058016014 + Log [v2.keypom.testnet]: 21 calls with 105000000000000 attached GAS. Pow outcome: 1.8602935. Required Allowance: 20248156910387200000000 + Log [v2.keypom.testnet]: Total required storage Yocto 16330000000000000000000 + Log [v2.keypom.testnet]: Current balance: 3.6160078, + Required Deposit: 0.2578263, + total_required_storage: 0.01633, + Drop Fee: 0, + Key Fee: 0 Total Key Fee: 0, + allowance: 0.0404963 total allowance: 0.0404963, + access key storage: 0.001 total access key storage: 0.001, + deposits less none FCs: 0.1 total deposits: 0.1 lazy registration: false, + deposits for FCs: 0.1 total deposits for FCs: 0.1, + uses per key: 2 + None FCs: 1, + length: 1 + GAS to attach: 100000000000000 + Log [v2.keypom.testnet]: New user balance 3.3581815 + Log [v2.keypom.testnet]: Fees collected 0 + + + Ticket Links: + + http://localhost:1234/v2.keypom.testnet/2LNJU2adYHgvyuczoNFkvdL92vuunNCESaZiWYh6cQJXcwVSJpHqgQpGVUHsEDDee2oQrSELAkRGPeYroW6hoPaN + + +Claiming with correct password... +Receipt: G7y6MWapxNwCCmCPAQ6iRWdvT292dq8hWp8ZQAnTbXwQ + Log [v2.keypom.testnet]: Beginning of process claim used gas: 479192976105 prepaid gas: 100000000000000 + Log [v2.keypom.testnet]: passed global check + Log [v2.keypom.testnet]: hashed password: [105, 193, 27, 134, 73, 227, 30, 80, 12, 73, 201, 126, 217, 0, 80, 239, 38, 5, 216, 62, 44, 177, 19, 137, 73, 50, 159, 32, 38, 11, 59, 94] + Log [v2.keypom.testnet]: actualPass password: [105, 193, 27, 134, 73, 227, 30, 80, 12, 73, 201, 126, 217, 0, 80, 239, 38, 5, 216, 62, 44, 177, 19, 137, 73, 50, 159, 32, 38, 11, 59, 94] cur use: 1 + Log [v2.keypom.testnet]: passed local check + Log [v2.keypom.testnet]: Key usage last used: 0 Num uses: 2 (before) + Log [v2.keypom.testnet]: Key has 1 uses left. Decrementing allowance by 10000000000000000000000. Allowance left: 30496313820774400000000 + Log [v2.keypom.testnet]: Total storage freed: 0. Initial storage: 33085324. Final storage: 33085324 + Log [v2.keypom.testnet]: Empty function call. Returning. +claiming the same key twice... +Key has already been scanned. Admission denied + + Password Test Responses: + Expected false, got: false + Expected true, got: true + + Double Claim Test Responses: + Expected true, got: true + Expected false, got: false + +โœจ Done in 26.50s. +``` + +

+
+ +--- + +## Conclusion + +So far, you've learned how to set up your React app, as well as break down the ticketing system into functional requirements. You then took those requirements and wrote a script to create the drop. + +In the next tutorial, the ticketing process will be broken down into stages for both the user side and event organizer side. From there, the flow of the app, and the Keypom variables that control it, can be established. + + diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/drop.md b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/drop.md new file mode 100644 index 00000000..9b31a5fa --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/drop.md @@ -0,0 +1,320 @@ +--- +sidebar_label: 'Creating the Drop' +--- +# Creating the Drop + +## Introduction +In this section you'll take the first step to creating the ticketing experience by designing the drop. This drop will be tailored according to the functionality and specifications found in the [Solution Architecture](architecture.md#keypom-solution). + +Recall that the drop needs the following properties: + +* A [Function Call drop](../../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops.md) must be used and configured so that each key has 2 uses. +* The first key use is password protected and `null` (for when the host scans attendees into the event). +* The second key use will have a small amount of $NEAR to cover account creation costs and sponsor the first few transactions. +* The second key use will also call `nft_mint` on an NFT contract which will send the new or existing account a POAP. + +:::tip +The first key use being `null` will allow for a lightweight transaction on-chain to reflect the key use decrement without needing to transfer any $NEAR to anyone or create any accounts. +::: + + +With this in mind, the aim of this tutorial will be to write a node script that will create the drop matching the above properties. This process can be broken down into three stages: + +1) Connect to the NEAR blockchain. +2) Create the drop with function call data. +3) Create the NFT collection for the post attendance gift. + +Starting at the `keypom-docs-examples` directory, navigate to the `ticket-app-skeleton/utils` folder and open the `createTickDrop.js` file. + +```bash +cd advanced-tutorials/ticket-app-skeleton/utils +``` + +There, you can see the following skeleton code in the file `createTickDrop.js`. +``` js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app-skeleton/utils/createTickDrop.js#L1-L33 +``` + +--- + +## Connecting to NEAR +In this section, you'll be addressing the first step which is connecting to the NEAR network. + +This is done with `NEAR-API-JS` and consists of: + +* Selecting which network to connect to (testnet or mainnet). + +* Specifying the location where the keys are stored for the drop funder's account. This location is commonly in the `~/.near-credentials` folder on your local machine. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8b8e8bbf5fd89d8447e1b6b4533da3bb8673690c/advanced-tutorials/ticket-app/utils/createTickDrop.js#L22-L38 +``` + +--- + +## Creating the Drop +In this section, you'll create the function call drop to meet the functional requirements defined earlier. + +### Function Call Drop Basics + +#### Initializing the SDK + +This process starts with calling the `initKeypom` function and will always be the first function you call to interact with the Keypom SDK. + +`initKeypom` initializes the SDK to allow for interactions with the Keypom smart contracts. Without it, none of the other SDK functions would work as expected. + +After `initKeypom` is called, the FC Drop can be created by calling `createDrop` and adding an `fcData` parameter. + +```js +// Change this to your account ID +const FUNDER_ACCOUNT_ID = "minqi.testnet"; +const NETWORK_ID = "testnet" +async function createTickDrop() { + // Initiate connection to the NEAR blockchain. + const CREDENTIALS_DIR = ".near-credentials"; + const credentialsPath = path.join(homedir, CREDENTIALS_DIR); + ... + ... + let near = new Near(nearConfig); + const fundingAccount = new Account(near.connection, FUNDER_ACCOUNT_ID) + + await initKeypom({ + near, + network: NETWORK_ID + }); +} +``` + +#### Defining the Function Call Data + +One the SDK has been initialized and the NEAR connection established, it's time to create the function call drop. This is done by passing in `fcData` into create drop. It is an object that defines the methods that will be called for any given key use: + + +```bash +fcData +โ””โ”€โ”€ methods +``` + +For multi-use keys, each specific use can have a different set of methods that will be called. These methods are executed one by one. As an example, a key with 3 uses can be seen: + +1. `nft_mint` +2. `null` +3. `create_account_advanced` -> `setup` -> `nft_mint` + +The first time the key is used, an NFT will be minted. The second use will simply advance the key with nothing called. The third time the key is used, it will first call `create_account_advanced` followed by the `setup` method and then finally `nft_mint` all in the same transaction. + +This is represented with a 2D array, where the inner array is the set of methods per key use. The above example would be represented as: + +```js +methods: [ + [ + "nft_mint" + ], + null, + [ + "create_account_advanced", + "setup", + "nft_mint" + ] +] +``` + +In reality, each method is not simply a string as shown above. The methods require the following parameters: + +- `receiverId`: The contract receiving the function call. +- `methodName`: The function to be called on the receiver contract. +- `args`: A stringified JSON object of all the arguments to be passed into `methodName`. +- `attachedDeposit`: The yoctoNear deposit attached to the function call when the key is used. + +For more information on the `methods` parameter, please see the [TypeDocs](../../../keypom-sdk/Core/interfaces/Method.md) + +In summary, the `fcData` should look something like this, with a generic method for the POAP which you'll explore in the next section: + +```js +fcData: { + methods: [ + null, + [ + { + receiverId: SOME_NFT_CONTRACT, + methodName: "nft_mint", + args: SOME_ARGS, + attachedDeposit: SOME_DEPOSIT + } + ], + ] +} +``` + +#### POAP + +Now that the basics for creating an FC drop have been covered, it's time to define what the second key use method data should look like. + +Each NFT that is given out to participants will share the same artwork, title, description etc. They will be part of the same series and the only thing that differs between them is their unique ID. For a full tutorial about the series contract, see NEAR's [NFT tutorial.](https://docs.near.org/tutorials/nfts/series#nft-collections-and-series) + +To mint these NFTs, there is a contract deployed to `nft-v2.keypom.testnet`. When creating an FC drop, it is important to understand the interface of the receiver contract. In this case, the mint function has the following parameters: + +```rust +pub fn nft_mint( + &mut self, + mint_id: U64, + receiver_id: AccountId +) +``` +Here, the `mint_id` is needed to identify and tell the NFT contract which series an NFT should belong to. The `receiver_id` field is needed to identify which account should receive the minted NFT. + +The `mint_id` field should be set as the drop's `dropId` and the `receiver_id` should be the attendee's NEAR `accountId`. At first glance, this might seem impossible because you don't know the attendee's accounts ahead of time. To solve this, you can use what's known as Keypom Arguments which are important pieces of information that can be passed into specified fields when a key is used. + +The following optional Keypom arguments are exposed for each individual method in the `fcData` alongside the required receiverId, methodName, attachedDeposit etc. + +They tell Keypom where to inject certain parameters for each function call. + +- [`accountIdField`](../../../keypom-sdk/Core/interfaces/Method.md#accountidfield): The name of the account that is claiming the linkdrop. +- [`dropIdField`](../../../keypom-sdk/Core/interfaces/Method.md#dropidfield): The [`dropId`](../../../keypom-sdk/Core/interfaces/Drop.md#dropid) of the drop that the claim is being called on. +- [`keyIdField`](../../../keypom-sdk/Core/interfaces/Method.md#keyidfield) The unique identifier, [`keyId`](../../../keypom-sdk/Core/interfaces/KeyInfo.md#keyid), of the key that is being used to claim. +- [`funderIdField`](../../../keypom-sdk/Core/interfaces/Method.md#funderidfield) the `accountId` of the person funding the drop. + +In this case, the `dropIdField` should be set to `mint_id` and `accountIdField` set to `receiver_id`. This will result in the drop's ID being passed into the parameter `mint_id` and attendee's NEAR account passed into the `receiver_id` field. + +In summary, the final `fcData` should look as follows. + +```js +fcData: { + methods: [ + null, + [ + { + receiverId: `nft-v2.keypom.testnet`, + methodName: "nft_mint", + args: "", + dropIdField: "mint_id", + accountIdField: "receiver_id", + attachedDeposit: parseNearAmount("0.1") + } + ], + ] +} +``` +:::note +If you wish to use a different NFT contract for your POAP, ensure you know the contract's interface and tailor the `methods` arguments accordingly. +::: + +#### Password Protected Keys + +To ensure each key has two uses with a password protected first use, the following `config`, `basePassword` and `passwordProtectedUses` can be added to `createDrop`. + +```js +await createDrop( + // 2 Uses per key + config: { + usesPerKey: 2 + }, + // Create base password and ensure only first key use is password protected + basePassword: "event-password", + passwordProtectedUses: [1], + fcData: { + ... + } +) +``` +As the drop creator, you have the option of creating a password and applying it to the keys in your drop. This password is unique for each key use and comprises of a master password, the drop ID and the use (1st, 2nd, 3rd etc.) + +This behavior can be applied by providing the core component, a `basePassword`, into the `createDrop` arguments. In the ticketing case, only the first use should be protected which can be achieved by passing `[1]` into the `passwordProtectedUses` parameter. + +Once a key has been password protected, you must pass in `hash(basePassword + publicKey + current_key_use)` in order to successfully claim it. + +With this model, if the host were to simply know the `basePassword`, it could deterministically generate this hash for any given ticket link. Furthermore, if the host was the only person who knew the password, nobody could claim the key without going through them first. + +For an in-depth explanation around password protected keys, see the [Typedocs](../../../keypom-sdk/Core/modules.md#createdrop). + +### Final Drop Structure + +Putting it all together, the final drop structure should look something like this: + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8b8e8bbf5fd89d8447e1b6b4533da3bb8673690c/advanced-tutorials/ticket-app/utils/createTickDrop.js#L42-L73 +``` + +--- + +## Making NFT Series + +Up until now, the drop is pointing to an NFT series that doesn't exist yet. If a key were to be claimed, the function call would throw an error. In this section, you'll be creating the series of NFTs to be used as POAPs. + +The Keypom SDK provides a function to create an NFT series specifically for function call drops, called [`createNFTSeries`](../../../keypom-sdk/Core/modules.md#createnftseries). It requires the following parameters: + +- `dropId`: The drop ID for the drop that should have the NFT series associated with it. +- `metadata`: The metadata that all minted NFTs will have. + +`metadata` is an object with these properties: +* `title`: The title for the NFTs in the series. +* `description`: Description for all NFTs in the series. +* `media`: link to the artwork in the form of an IPFS CID. +* `copies`: Number of NFTs in the series. + +The code for creating the series is shown below. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8b8e8bbf5fd89d8447e1b6b4533da3bb8673690c/advanced-tutorials/ticket-app/utils/createTickDrop.js#L75-L84 +``` + +Once both the series and drop are created, the key can be used to mint on-demand POAPs to wallets. + +--- + +## Adding More Than 50 Tickets +Due to gas restriction, `createDrop` is limited to 50 password protected keys (tickets). Rather than create multiple drops for the same event, you can simply add more keys to a single drop. This allows you to track your event metrics using a single `dropId`. + +To do this, you can use the following code: + +```js +// Loop to add 200 keys +let numKeys = 200 +let keysAdded = 0; +let allSecretKeys = []; +while (keysAdded < numKeys) { + const keysToAdd = Math.min(50, numKeys - keysAdded); + const {secretKeys, publicKeys} = await generateKeys({ + numKeys: keysToAdd, + }); + await addKeys({ + account: fundingAccount, + dropId, + publicKeys + }); + keysAdded += keysToAdd; + allSecretKeys = allSecretKeys.concat(secretKeys); +} +``` + +For more, see [this example](../../../Cookbook/drops/NEAR.md#creating-a-large-drop) or + +--- + +## Creating Ticket Links +The last step in this process is to create the links themselves so that you can easily distribute the tickets to people. You can control the format of the URL, for now `localhost:1234` will be used. + +You can utilize the `formatLinkdropUrl` function for convenience. It can take a custom URL that contains `CONTRACT_ID` and `SECRET_KEY` and it will replace them with the contract ID and secret keys passed in. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8b8e8bbf5fd89d8447e1b6b4533da3bb8673690c/advanced-tutorials/ticket-app/utils/createTickDrop.js#L86-L91 +``` + +--- + +## Final Code + +Putting everything together, the final code for the drop should be: + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8b8e8bbf5fd89d8447e1b6b4533da3bb8673690c/advanced-tutorials/ticket-app/utils/createTickDrop.js#L1-L107 +``` + + +## Conclusion + +So far, you've broken down the ticketing system into functional requirements and used them to write a script to create the drop. + +In the next tutorial, you'll be testing the drop you just created, starting with creating a script to emulate the host scanning a ticket. + + diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/final.md b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/final.md new file mode 100644 index 00000000..ce7623d4 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/final.md @@ -0,0 +1,151 @@ +--- +sidebar_label: 'Final Product' +--- +# Final Product +Welcome to the last section of this ticketing app tutorial! Here, you'll be seeing the full app in action! + +:::note +To run this app on your local machine, you will need a computer with working camera. +::: + +## Getting Started +To follow along with the app on your own machine, you can clone the code from the [Keypom Docs Examples](https://github.com/keypom/keypom-docs-examples) repository and run the following command in the root folder `keypom-docs-examples/`: + +``` bash +cd advanced-tutorials/ticket-app-skeleton && yarn && yarn start +``` + +:::note +If you'd like to run the already completed code found in the `ticket-app` directory instead of the skeleton code, run: + +``` bash +cd advanced-tutorials/ticket-app && yarn && yarn start +``` +::: + +This should bring you to the following page at `localhost:1234` + +

+ ticketing +

+ +--- + +## Starting the Claim and Scanner Pages + +To begin the app, first you'll need to run the create drop script: + +```bash +yarn create-ticket-drop +``` + +This will return a link: + +```bash +Ticket Links: + +http://localhost:1234/v2.keypom.testnet/3pGPvPGiXUiMfW6TME1EPWGWHzx1FrLSLgu68UADpyjg6c9DPix1v2bxUWuY5K7ChWE5G5BNszMNTPmecTz7C15w +``` + +This should bring you to the following page. Feel free to take a picture of your QR code with another device, you will need to hold this QR code up to your computer's camera later. + +

+ ticketing +

+ +From there, you can duplicate this window and modify the URL to be: +``` +http://localhost:1234/v2.keypom.testnet/scanner +``` +It will immediately prompt you for a password. By default, the `createTickDrop` script you ran earlier has a password set to `event-password` but for now enter an incorrect password: +``` +wrong-password +``` + +Once you enter this password, the scanner should appear, shown below. + +

+ ticketing +

+ +--- + +## Scanning and Claiming +### Incorrect Password Claim + +Now, you can begin testing the scanner by holding the photo of the QR code up to the camera of your computer. Ensure it has a clear unobstructed view of the code. Once the data is read in, the scanner's frame should change to yellow as it tries to claim. + +

+ ticketing +

+ +This should promptly return a failed claim, shown below. + +

+ ticketing +

+ +If you right click and inspect the page and go to the console, you should see the following error indicating an incorrect password. + +

+ ticketing +

+ +### Correct Password Claim +To enter the correct password, simply refresh the scanner page. This should prompt you for the password again. You can now enter the correct password for your private key. By default, the `createTickDrop` script you ran earlier has a password of `event-password`. + +``` +event-password +``` + +Once the correct password has been entered, you can repeat the same steps as before and try to claim your ticket by holding the QR code up to the scanner. This time around after the yellow claiming frame, you will see the following successful claim page. + +

+ ticketing +

+ +### Double Scanning +Now that the ticket has been successfully scanned and claimed, you can try to double scan the ticket. Recall that, if the second scan succeeds the attendee loses the opportunity to claim their POAP. + +Same as before, hold up the QR code up to your computer camera. Once the scanner reads the data and tries to claim, you should see this resultant page. + +

+ ticketing +

+ +--- + +## Claiming POAP +Now, after the ticket has been claimed **once**, if you go back and refresh your ticket page the QR code should now disappear and in its place is a button to claim your POAP. + +

+ ticketing +

+ +Clicking this should bring you to a MyNearWallet claim page. Once you claim, either to a new or existing NEAR account, you should be able to see our mascot, Moon, as an NFT in your collectibles tab! + +

+ ticketing +

+ +--- + +## Claiming Deleted Keys +Now that you've claimed the POAP, the private key is now deleted. If you go back to the ticket page and refresh it again, you should see the following page; indicating your key is depleted. + +

+ ticketing +

+ +If you try to holding up the screenshot of your QR code up to the QR reader, you will be greeted with the following failed claim page. + +

+ ticketing +

+ +--- + +## Conclusion +In this tutorial, you learned how you can use Keypom to create a seamless and powerful ticketing experience. You started from a few simple goals, translated those to tangible customizations to make to your Keypom function call drop, and then built a React app around the drop leveraging Keypom values to make it all run. + +In the next advanced tutorial, you will learn how you can auto-register people into a DAO with a simple link. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/introduction.md b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/introduction.md new file mode 100644 index 00000000..983a82b6 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/introduction.md @@ -0,0 +1,87 @@ +--- +sidebar_label: 'Introduction' +--- +# Introduction +In this tutorial, you'll learn how to create a seamless ticketing experience that is cheaper than alternative methods and can also handle very large audiences. +## Background +The most popular ticketing solutions in Web3 utilize NFT technologies. This approach, however, requires attendees to own a crypto wallet and sign transactions. This is a massive barrier to entry, particularly for users that are new to Web3. + +Keypom aims to solve these problems by empowering you to create a seamless ticketing system that has the following features. + +* Users are not required to have a wallet to enter the event. +* Each ticket is unique and can only be used by one person. +* Attendees are not required to have wifi to gain entry to the event. +* Attendees that did not have a NEAR wallet can get one for free. +* Attendees can choose to receive an NFT proving their attendance at the event. This is commonly known as a [POAP](https://academy.binance.com/en/glossary/proof-of-attendance-protocol-poap). +* The post-attendance gifts can **only** be given to people that physically showed up to the event. You can't receive the NFT if you didn't show up. + +These features open the door to an entirely new class of non-technical attendees and create a smoother experience compared to existing NFT ticketing solutions. + +In this tutorial, you'll be creating a ticketing system with those features, and incorporating a POAP to further reward your community members that come out to your events. + +:::info note +The NFT POAP is optional to include as the event organizer. You can choose to keep it, or replace it with a different attendance gift such as Fungible Tokens. +::: + +--- + +## Prerequisites + +For the this tutorial, you can choose to run the scripts on your own machine. To do so, you must have the following: + +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [NEAR-API-JS](https://docs.near.org/tools/near-api-js/quick-reference#install) +3. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + +If you want to reference the finished code, that can be found [here](https://github.com/keypom/keypom-js/tree/min/ticketing-tutorial/docs-advanced-tutorials/ticket-app). To follow along and build out this ticketing app, see the steps below. + +--- + +## Creating your Project +In this section, you'll prepare to create the ticketing app using the skeleton code made available to you at the [Keypom Docs Examples](https://github.com/keypom/keypom-docs-examples) repo. + +First, you'll want to clone the repo: + +```bash +git clone https://github.com/keypom/keypom-docs-examples.git && cd keypom-docs-examples +``` + +Second, install all dependencies for the ticketing app skeleton code using the following: + +``` +yarn ticketing:init-skeleton && cd advanced-tutorials/ticket-app-skeleton +``` + +:::note +To install all dependencies for the completed ticketing app, run the following: +``` +yarn ticketing:init-complete && cd advanced-tutorials/ticket-app +``` +::: + + + +At this point, all the dependencies should be installed and you should be in the `advanced-tutorials/ticket-app-skeleton` folder. Here you'll find the following files required to build out your app. + +```bash +/ticket-app-skeleton +โ””โ”€โ”€ components +โ”‚ โ””โ”€โ”€ scanner.js +โ”‚ โ””โ”€โ”€ qrcode.js +โ””โ”€โ”€ state +โ”‚ โ””โ”€โ”€ App.js +โ”‚ โ””โ”€โ”€ keyInfo.js +โ””โ”€โ”€ utils +โ”‚ โ””โ”€โ”€ allowEntry.js +โ”‚ โ””โ”€โ”€ createTickDrop.js +โ”‚ โ””โ”€โ”€ testTickDrop.js +โ””โ”€โ”€ package.json +``` + +With this setup complete, you are ready to begin building out the ticket app, starting by breaking down the problem into its functional requirements. + + + + + + diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/react-outline.md b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/react-outline.md new file mode 100644 index 00000000..0746d765 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/react-outline.md @@ -0,0 +1,80 @@ +--- +sidebar_label: 'App Design' +--- +# App Design + +## Introduction +In the previous sections, you've created the foundation for the ticketing system by breaking it down to its functional requirements and designing a drop accordingly. Here, you'll be learning the flow and design of the React app, to create a seamless ticketing experience for *both* the organizers and the attendees. + +With this tutorial, a React app with separate scanner and claim pages will be created. Although the attendees can access the scanner, it will be useless to them unless they know the drop password. + +--- + +## Attendee Ticket Page Flow +This page is for the attendees and will only consist of 3 stages. + +

+ ticketing +

+ +* **Stage 1, Pre-entry:** Page showing a unique QR code, corresponding to the private key from their ticket. +* **Stage 2, Post-entry:** After the QR code has been scanned by the host, the user can choose to onboard to NEAR and receive a POAP. +* **Stage 3, Post-gift:** If the user chooses to claim their POAP, the third stage will show a page of **your** choice. You can choose to leave it empty or customize it with additional resources or a redirect to your own website. + +To trigger a transition from Pre-entry to Post-entry and Post-entry and Post-gift, the following events must occur: +1. **Pre-entry → Post-entry**: The host must scan the QR code and call `allowEntry` with the event password and private key. +2. **Post-entry → Post-gift**: The user chooses to `claim` their POAP. Once that `claim` is complete and the POAP is in their wallet, the page will transition to post-gift. + +--- + +## Host Scanner Page Flow + +The scanner page is for the host and consists of 3 stages that repeat in a loop. + +

+ ticketing +

+ +The event password will only be prompted once on app mount. If the host wishes to enter a different password once scanning starts, they can simply refresh the page and be prompted again. + +* **Stage 1, Pre-claim:** A page with the camera viewport open, constantly scanning for QR codes. +* **Stage 2, Claiming:** Once a QR code is detected and information is scanned in, the app attempts to derive the private key from the QR code and calls `allowEntry` using the event password. During this time, the app will indicate it is in the process of claiming. +* **Stage 3, Post-claim:** After the claim is processed, the page will indicate whether or not to admit the attendee depending on the return value of `allowEntry`. + +After post-claim, the entire cycle will loop back to pre-claim after three seconds. This time interval was set so the host could read any error messages that may appear. You can modify this time by changing the values passed into `timeout()`. + +--- + +## Keypom Information + +There are a few key pieces of information needed from Keypom in order to allow the pages to perform as expected. + +### Claim Page +The major parameter that controls what React will render is `cur_key_use` for the given private key. This value represents the key's current use number (1st use, 2nd use etc.) and will be stored in a React state variable called `curUse`. + +**Pre-entry → Post-entry:** To change between these two stages, the key's current use must be changed from 1 to 2. This is done when the QR code is scanned by the host. + +**Post-entry → Post-gift:** To change between these two stages, the key must be deleted and fully claimed. This happens when they claim the post attendance gifts. + +The following variables are needed to allow these state changes: + +* `curUse`, obtained from accessing the `cur_key_use` from calling [`getKeyInformation`](../../../keypom-sdk/Core/modules.md#getkeyinformation) with `pubKey`. +* `pubKey`, derived from `privKey` using the SDK's [`getPubFromSecret`](../../../keypom-sdk/Core/modules.md#getpubfromsecret) method. +* `privKey`, stored in the user's app link. + +### Scanner Page +As the scanner page exclusively scans QR codes and admits people using the `allowEntry` utility function, the app itself does not store any Keypom parameters apart from the event password, which the host will manually enter on app mount. + +The scanner app obtains the `privKey` by scanning the QR code and parsing the obtained string. It then calls `allowEntry` and passes in the event password and the `privKey`. + +The following list of variables are used in the scanner app: +* `privKey`, read in from the QR code. +* `password`, set by the host on app mount. + +--- + +## Conclusion +In this section, you broke down the app's flow of logic for both the user claim page, and the scanner page. You then took that information and found Keypom information that can be used to facilitate that flow. + +In the following sections, you'll be applying what you just learned by going through the actual code for the claim and scanner pages. + diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/scanner-code.md b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/scanner-code.md new file mode 100644 index 00000000..9ced629a --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/scanner-code.md @@ -0,0 +1,144 @@ +--- +sidebar_label: 'Scanner Code' +--- +# Scanner Code + +## Introduction +In the previous sections, you designed the structure and components needed to meet the requirements of the ticket app and saw the code to create the user claim page. Building on that, this tutorial will guide you through the code to create the scanner app for your seamless ticketing system. + +:::note +The focus of this section will be on the Keypom aspects of each script, such as getting key information and using it. + +The full code for each script will be shown, with highlights. For React resources, see [here](https://reactjs.org/docs/hello-world.html) as a starting point. +::: + +Recall, from the [introduction](introduction.md) that your code had the following outline. + +```bash +/ticket-app-skeleton +โ””โ”€โ”€ components +โ”‚ โ””โ”€โ”€ scanner.js +โ”‚ โ””โ”€โ”€ qrcode.js +โ””โ”€โ”€ state +โ”‚ โ””โ”€โ”€ App.js +โ”‚ โ””โ”€โ”€ keyInfo.js +โ””โ”€โ”€ utils +โ”‚ โ””โ”€โ”€ allowEntry.js +โ”‚ โ””โ”€โ”€ createTickDrop.js +โ”‚ โ””โ”€โ”€ testTickDrop.js +โ””โ”€โ”€ package.json +``` + +This tutorial will be covering the code in `scanner.js`. + +--- + +## Scanner App - `Scanner.js` +### Breaking Down the Problem +As a brief reminder, the host scanner page will have the following stages, best outlined with the diagram below. + +

+ ticketing +

+ +* **Stage 1, Pre-claim:** A page with the camera viewport open, constantly scanning for QR codes. +* **Stage 2, Claiming:** Once a QR code is detected and information is scanned in, the app attempts to derive the private key from the QR code and calls `allowEntry` using the event password. During this time, the app will indicate it is in the process of claiming. +* **Stage 3, Post-claim:** After the claim is processed, the page will indicate whether or not to admit the attendee depending on the return value of `allowEntry`. + +After post-claim, the entire cycle will loop back to pre-claim after three seconds. This time interval was set so the host could read any error messages that may appear. You can modify this time by changing the values passed into `timeout()`. + + +In post-claim, a `allowEntry` might have returned false for a few reasons. +* Incorrect password/key +* A ticket may already be fully claimed and not exist when the host attempts to claim it. +* The ticket has already been scanned by the host. This means the key's current use is 2. + +### `masterStatus` State Variable +In order to track all these stages and possible outcomes, a set of enums will be defined. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/components/scanner.js#L10-L22 +``` + +All these stages will be stored in a `masterStatus` state variable object. + + +|**`masterStatus.stage`**| **Description** | +|------------------------|-----------------------------------------------------------------------------------------| +| `Stages.preClaim` | *Pre-claim:* Host scanner page is scanning, waiting to read in data | +| `Stages.claiming` | *Claiming:* Data has been read, scanner is trying to claim | +| `Stages.sucessClaim` | *Post-claim:* Successful claim (`true` returned from `allowEntry`) | +| `Stages.failClaim` | *Post-claim:* Failed to claim (`false` returned from `allowEntry`) | +| `default` | *Unknow State:* Display error message | + + +| **`masterStatus.data`** | **Description** | +|-------------------------|---------------------------------------------------| +| `Data.empty` | No data has been read, cannot call `claim` | +| `Data.captured` | Data has been read, scanner can now try to claim | + +### Initialization and Scanning +Upon app mount, the host scanner page will immediately do the following. + +1) Prompt the host for the base password. +2) Begin scanning. + +These features can be seen in the code snippet below. +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/components/scanner.js#L9-L53 +``` + +### Claiming +The claiming process can be controlled using a React `useEffect` hook, that runs every time the data status, `masterStatus.data`, is updated, indicating that data was read by the scanner. + +The primary task of the claim process is to determine if a claim is: + +* Successful - `masterStatus.stage == Stages.successClaim` +* Unsuccessful - `masterStatus.stage == Stages.failClaim` + +This is accomplished using the `allowEntry` function that you created earlier. If it returns `true`, the master status stage should be set to `Stages.successClaim`. Otherwise, it should be set to `Stages.failClaim`. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/components/scanner.js#L55-L92 +``` + +### Rendering + +The rendering part of the scanner app is relatively simple, as all the logic for states was taken care of during the claim process. The following table outlines what the page should render based on the value of `masterStatus.stage`, as outlined [above](scanner-code.md#masterstatus-state-variable). + +The focus of the renders is on the scanner frame (coloured square) and the text below it. The QR code visible is a code on a phone screen held up to the camera. + +| **Condition and Description** | **Render** | +|----------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `masterStatus.stage` == `Stages.preClaim`, *Pre-claim:* Host scanner page is scanning, waiting to read in data |

ticketing

| +| `masterStatus.stage` == `Stages.claiming`, *Claiming:* Data has been read, scanner is trying to claim |

ticketing

| +| `masterStatus.stage` == `Stages.successClaim`, *Post-claim:* Successful `claim` |

ticketing

| +| `masterStatus.stage` == `Stages.failClaim`, *Post-claim:* Invalid password, key invalid/scanned already etc. |

ticketing

| +| `default`, *Unknown State:* Display error message |

ticketing

| + +The following expandable section contains code for rendering. + +
+Full scanner.js rendering code +

+ +```jsx reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/components/scanner.js#L94-L147 +``` + +

+
+ +### Full Code +The full code, including the set up, claiming, and the rendering, can be seen below. + +``` jsx reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/components/scanner.js#L1-L148 +``` + +--- + +## Conclusion +In this section, you learned about the `scanner.js` component. Its primary role is to handle the data read in from the QR code reader, and `claim` the private key embedded within the QR code. It is also designed to handle different kinds of errors, such as deleted keys, and tickets that have already been scanned. + +In the next section, you'll be seeing the final product of what you just built! \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/user-code.md b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/user-code.md new file mode 100644 index 00000000..5e1614af --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Advanced/ticketing/user-code.md @@ -0,0 +1,138 @@ +--- +sidebar_label: 'Attendee Ticket Page Code' +--- +# Attendee Ticket Page Code + +## Introduction +In the previous section, you broke down the flow and logic of the ticket app. You also learned what Keypom information is needed in order to render the pages properly. + +In this tutorial, you'll learn about the actual code needed to create the attendee ticket page for your seamless ticketing system. + +:::note +The focus of this section will be on the Keypom aspects of each script, such as getting key information and using it. + +The full code for each script will be shown, with highlights. For React resources, see [here](https://reactjs.org/docs/hello-world.html) as a starting point. +::: + +Recall, from the [introduction](introduction.md) that your code had the following outline. + +```bash +/ticket-app-skeleton +โ””โ”€โ”€ components +โ”‚ โ””โ”€โ”€ scanner.js +โ”‚ โ””โ”€โ”€ qrcode.js +โ””โ”€โ”€ state +โ”‚ โ””โ”€โ”€ App.js +โ”‚ โ””โ”€โ”€ keyInfo.js +โ””โ”€โ”€ utils +โ”‚ โ””โ”€โ”€ allowEntry.js +โ”‚ โ””โ”€โ”€ createTickDrop.js +โ”‚ โ””โ”€โ”€ testTickDrop.js +โ””โ”€โ”€ package.json +``` + +This tutorial will be covering the code in `App.js`, `KeyInfo.js`, and `qrcode.js`. + +--- + +## `App.js` +### Setting Up +The primary purpose of `App.js` is to display the different states of the attendee ticket page. This will involve getting the current key uses, and then rendering based on the value returned. + +The first step is to initialize a connection to NEAR and setup all the state variables that will be needed to render the page. + +```jsx reference showLineNumbers +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/state/App.js#L13-L57 +``` + +When the page is loaded, the function `setup` is called and the URL is parsed for `contractId` and `privateKey`. These will be stored in their own respective state variables for further use. + +Once the URL has been parsed and the resulting values stored, `connectNear` is called. This function handles the NEAR connection, as well as the Keypom connection. + +:::note +When connecting to NEAR, a `BrowserLocalStorageKeyStore` is used rather than an `UnencryptedFileSystemKeyStore`. This will create a key store in the user's browser for future use. For more on key stores, see [here](https://docs.near.org/tools/near-api-js/quick-reference#key-store) +::: + +With the NEAR connection established, your browser can now talk to the NEAR blockchain. The next step, is to call `initKeypom`. This initializes the SDK to allow for interactions with the Keypom smart contracts. + +After the Keypom initialization is complete, the QR code information can be created following the format `${contractId}/${privKey}`. + +### Rendering + +The process of rendering is simple: retrieve the key's current use number, and render the page differently based on the stages outlined in the [App Design](react-outline.md). + +The information is passed into both a QR code component and a KeyInfo component. The `KeyInfo` component takes in both the Keypom contract and private key. It then calls `getKeyInformation` and updates the `curUse` state variable accordingly. `QRCode` uses the `qrcode.react` library to display a QR code based on a string input. + +The following table outlines what the page should render based on a set of conditions including the current key use. + +| **Condition and Description** | **Render** | +|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **`curUse` is 1**: The attendee ticket page should show a QR code representing the ticket data (contract and secret key). The `QrCode` component is rendered by passing in the `link` state variable created earlier. |

ticketing

| +| **`curUse` is 2**: The first claim was done by the host, and thus should give the user the option to claim their POAP. This is done with the same linkdrop link. |

ticketing

| +| **`curUse` is 0**: The second claim was used, and thus the key was depleted and deleted. Here, the user will be given resources to continue learning about NEAR. You can choose to show anything here. |

ticketing

| +| This should act as a landing page for your event and will be shown if any URL is invalid. In this case, `curUse` is 0 **and** splitRes[3] is '' or undefined |

ticketing

| + +The code to render can be found in the exandable section below. + +
+app.js rendering code +

+ +```jsx reference showLineNumbers +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/state/App.js#L54-L134 +``` + +

+
+ + +### Full Code +The full code, including the set up and the rendering, can be seen below. +
+Full app.js code +

+ +``` jsx reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/state/App.js#L1-L136 +``` + +

+
+ +--- + +## `Qrcode.js` + +`Qrcode.js` is a simple component that returns a QR code based on the string passed in. On the attendee ticket page, this is the linkdrop URL for the host to scan. + +The full code can be seen below. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/components/qrcode.js#L1-L22 +``` + +--- + +## `Keyinfo.js` + +`Keyinfo.js` is responsible for updating Keypom related state variables, `pubKey`, and `curUse`. + +When `curUse` is 1 and the QR code is being rendered, the public key and use number is shown for educational purposes. + +A `useEffect` hook is used to update the needed Keypom state variables whenever the `KeyInfo` component is rendered. To do this, two SDK functions are used: [`getPubFromSecret`](../../../keypom-sdk/Core/modules.md#getpubfromsecret) to get the public key and [`getKeyInformation`](../../../keypom-sdk/Core/modules.md#getkeyinformation) to get the current key use. This can be seen below. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/4c8f86dab842c16e9c2bc6ad6f22e1eee2dced9e/advanced-tutorials/ticket-app/state/keyInfo.js#L6-L42 +``` + +--- + +## Conclusion +In this section, you learned about the 3 components that make up the attendee ticket page: `App.js`, `Qrcode.js`, and `KeyInfo.js`. + +In summary, `App.js` is the "homepage" of the attendee ticket page and takes care of setting up all the state variables based on the URL and then rendering the page. `Qrcode.js` simply renders a QR code based on an input string. `KeyInfo` is in charge of updating all Keypom state variables whenever `App.js` re-renders. + +You also went through the code for each of these components and saw the expected [render results](user-code.md#rendering). + +In the next section, you'll be going through a similar process with the scanner page. + diff --git a/versioned_docs/version-2.0/Tutorials/BOS/welcome.md b/versioned_docs/version-2.0/Tutorials/BOS/welcome.md new file mode 100644 index 00000000..500b82b2 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/BOS/welcome.md @@ -0,0 +1,42 @@ +--- +sidebar_label: 'Keypom BOS Components' +--- +# Keypom BOS Components +Welcome! This a collection of useful BOS components from both Keypom and the community! +- [Event Ticketing on BOS](https://test.near.social/#/minqi.testnet/widget/kp-ticket-homepage?tab=my-ticket-drops) + - Built for [ETHGlobal Waterloo](https://ethglobal.com/showcase/keypom-x-bos-event-ticketing-pow2e) by Min + - Special thanks to [Kent - cuongdcdev](https://near.org/near/widget/ProfilePage?accountId=cuongdcdev.near) for API support, [Elliot Bream](https://near.org/near/widget/ProfilePage?accountId=elliotbraem.near&tab=apps) for gateway support, and [Kiskesis](https://near.org/near/widget/ProfilePage?accountId=kiskesis.near) for drop-viewer frontend beautification +

+ BOS ticketing +

+ + +- [My Keypom Drops Info](https://near.org/kiskesis.near/widget/Keypom-Drop-Viewer-fork) by [Kiskesis](https://near.org/near/widget/ProfilePage?accountId=kiskesis.near). + - Forked from [here](https://near.org/mintlu.near/widget/Keypom-Drop-Viewer) +

+ ticketing +

+ +- [Number of Keypom Drops per User](https://near.org/mintlu.near/widget/view-number-of-keypom-drops) +

+ ticketing +

+ + +- [All my Drops](https://near.org/mintlu.near/widget/all-my-drops) +

+ ticketing +

+ +- [Linkdrop Plus](https://near.org/cuongdcdev.near/widget/linkdrop_plus) by [Kent - cuongdcdev](https://near.org/near/widget/ProfilePage?accountId=cuongdcdev.near) +-

+ ticketing +

+ +- [Linkdrop Viewer](https://near.org/cuongdcdev.near/widget/linkdrop-viewer) by [Kent - cuongdcdev](https://near.org/near/widget/ProfilePage?accountId=cuongdcdev.near) + + +- [DAO viewer](https://near.org/hack.near/widget/DAO.Profile?daoId=keypom-test.sputnik-dao.near) +

+ dao-viewer +

\ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Basics/fc-drops.md b/versioned_docs/version-2.0/Tutorials/Basics/fc-drops.md new file mode 100644 index 00000000..95bc583e --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Basics/fc-drops.md @@ -0,0 +1,425 @@ +--- +sidebar_label: 'Function Call Drop' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Function Call Drop + +## Introduction + +In this tutorial, you are going to learn how to create a Function Call Drop from scratch. Similar to how the other drops can be claimed by both new and existing users, FC drops are a great onboarding tool. The difference, is that FC drops can invoke methods on external smart contracts when the link is claimed. This allows for a ton of flexibility and use-cases such as [auto-registering users into a DAO](../../Tutorials/Advanced/daos/introduction.md) as part of the onboarding process. + +In this tutorial, the function call will be to Lazy Mint an NFT. + +

NFT collectibles claim

+ +To learn more about what the FC drop, see the [concepts page](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops.md) + + +--- + +## Prerequisites +For the basic tutorials, you can choose to run the scripts on your own machine. To do so, you must have the following: + +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [NEAR-API-JS](https://docs.near.org/tools/near-api-js/quick-reference#install) +3. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + +With this tutorial, you can either create your own script by following along, or view the completed script available in the [Keypom Documentation Examples](https://github.com/keypom/keypom-docs-examples) repo. + +### Creating your Project +In this section, you're going to create your project and install the SDK to prepare for the tutorial. If you have a completed script and have installed the SDK, you can skip [forward](simple-drops.md#breaking-down-the-problem). + +First, you need to give your project a home. + +```bash +mkdir my-keypom-project && cd my-keypom-project +``` + +Next, you'll want to create a default `package.json` file using the following command. You can accept all default values. +```bash +npm init +``` + +At this point, your project structure should look like this. +```bash +/my-keypom-project +โ”œโ”€โ”€ package.json +``` + +If you open `package.json`, you should see this. + +
+Default package.json +

+ +``` bash +{ + "name": "my-keypom-project", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC" +} +``` + +

+
+ +The next step is to create an empty JavaScript file. + + + +```bash +touch fc-keypom.js +``` + + + + +```bash +fsutil file createnew fc-keypom.js 0 +``` + + + + +Finally, the last step is to install the Keypom JS SDK. +```bash +npm install @keypom/core +``` + +After installing the SDK, your `package.json` file should now look slightly different. + +
+package.json after installing the SDK +

+ +```bash +{ + "name": "my-keypom-project", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC", + # highlight-start + "dependencies": { + "@keypom/core": "^1.0.0" + } + # highlight-end +} +``` + +

+
+ +With these steps complete, your project folder should look like this. + +```bash +/my-keypom-project +โ”œโ”€โ”€ fc-keypom.js +โ”œโ”€โ”€ package.json +โ”œโ”€โ”€ package-lock.json +โ”œโ”€โ”€ node_modules +โ”‚ โ””โ”€โ”€ keypom-js +โ”‚ โ””โ”€โ”€ ... +``` + +You are now ready to begin creating your drop! + +--- + + +## Breaking Down the Problem + +A Function Call Drop is Keypom's most powerful drop type. A brief breakdown of how an FC drop works is as follows: + +For every key-use, a set of functions is called in the order that they are defined. For multi-use keys, this set can vary across different key uses. + +An example scenario for a multi-use key can be seen below. + + +| Key Use | Functions called during nth Key Use | +| -----------| ---------------------------------------------- | +| Key Use 1 | `nft_mint` | +| Key Use 2 | `sign_message`, `update_message` | +| Key Use 3 | `mint_fungible_tokens` | + +:::note +In this tutorial, the key will be single use and only call `nft_mint`. +::: + +The process of creating an FC drop is similar to the other drop types: + +1) Connect to the NEAR blockchain +2) Create drop with function call data + +The following skeleton code can be used as a starting point: +``` js +// Each of the two methods to create this drop will have their own unique set of imports + +// Imports used in the Keypom SDK method: +const { initKeypom, createDrop, getEnv, formatLinkdropUrl } = require("@keypom/core"); +const { parseNearAmount } = require("@near-js/utils"); +const { UnencryptedFileSystemKeyStore } = require("@near-js/keystores-node"); +const { Near } = require("@near-js/wallet-account"); +const { Account } = require("@near-js/accounts"); +const path = require("path"); +const homedir = require("os").homedir(); + +// Imports used in the NEAR-API-JS method: +const { parseNearAmount } = require("@near-js/utils"); +const { KeyPair } = require("@near-js/crypto") +const { UnencryptedFileSystemKeyStore } = require("@near-js/keystores-node"); +const { Near } = require("@near-js/wallet-account"); +const { Account } = require("@near-js/accounts"); +const path = require("path"); +const homedir = require("os").homedir(); + + +async function fcDropKeypom(){ +// STEP 1: Initiate a NEAR connection. + +// STEP 2: Create the drop with function call data. +} + +fcDropKeypom() + +``` +## Getting Started +In this section, you'll be addressing the first step: connecting to NEAR. + +This is done with `NEAR-API-JS` and consists of: + +1) Create a Keystore, which stores your access keys used to sign transactions + * select a network, either `testnet` or `mainnet` + * choose a location where the keypairs live, either a folder on your local machine, or in-memory + +2) Define a NEAR configuration using the Keystore +3) Use the configuration to initialize a connection to NEAR + +More information about this process can be found [here](https://docs.near.org/tools/near-api-js/quick-reference#key-store). + +:::note +For simplicity, this tutorial will choose a file-based keystore and point to the `~/.near-credentials` folder on your local machine since this is where most of your keys are stored. For more information about KeyStores, visit NEAR's [official docs](https://docs.near.org/tools/near-api-js/quick-reference#key-store). +::: + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/function-call-drop/fc-example.js#L10-L30 +``` + +## Creating Drop with Function Call Data +In this section, you'll learn about the process of creating an FC drop using the SDK. + +This process starts with calling the `initKeypom` function and will always be the first function you call to interact with the Keypom SDK. + +`initKeypom` initializes the SDK to allow for interactions with the Keypom smart contracts. Without it, none of the other SDK functions would work as expected. If a NEAR connection is not already present, it will initialize a new one for you. More info on the `initKeypom` function can be found [here](../../keypom-sdk/Core/modules.md#initkeypom). + +After `initKeypom` is called, the FC Drop can be created by calling `createDrop` and adding an `fcData` parameter. + +:::tip +Recall that the private keys being generated using `createDrop` are used to store the assets. These keys are then embedded within a link. + +In an FC Drop, the assets consist of a set of invokable methods and optional $NEAR. +::: + +The primary task in creating the Function Call Drop is to define fcData. It is an object containing a methods field that outlines what methods should be called for a given key use: + + +```bash +fcData +โ””โ”€โ”€ methods +``` + +For multi-use keys, each specific use can have a different set of methods that will be called. These methods are executed sequentially and not in parallel. As an example, a key with 3 uses can be seen: + +1. `nft_mint` +2. `null` +3. `create_account_advanced`, `setup`, `nft_mint` + +The first time the key is used, an NFT will be minted. The second use will simply advance the key and nothing will be called. The third time the key is used, it will first call `create_account_advanced`. Once that's finished it will call the `setup` method and then finally `nft_mint`. + +This is represented with a 2D array, where each inner is the set of methods per key use. The above example would be represented as: + +```js +methods: [ + [ + "nft_mint" + ], + null, + [ + "create_account_advanced", + "setup", + "nft_mint" + ] +] +``` + +Every method listed represents a function call and requires the following parameters: + +- `receiverId`: The contract receiving the function call. +- `methodName`: The function to be called on the receiver contract. +- `args`: A stringified JSON object of all the arguments to be passed into `methodName`. +- `attachedDeposit`: The yoctoNear deposit attached to the function call when the key is used. + +In this tutorial only one function call will be made: `nft_mint` in order to lazy mint an NFT. + +Including the `fcData` parameter categorizes this as an FC drop. Without it, the Keypom Protocol would treat this drop as a Simple Drop. More information on the `fcData` parameter can be found [here](../../keypom-sdk/Core/interfaces/FCData.md). + +To see what the SDK is doing behind the scenes, a `NEAR-API-JS` equivalent NodeJS script has been provided. + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/function-call-drop/fc-example.js#L32-L71 +``` + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/function-call-drop/fc-near-example.js#L33-L82 +``` + + + + +--- + +## Creating Linkdrops +The last step in this process is to create the links themselves so that you can easily distribute the assets to people. This is done by embedding the private key, containing the $NEAR, into the link along with the Keypom contract ID. + +With the Keypom SDK, this is all neatly wrapped up in the function [`formatLinkdropUrl`](../../keypom-sdk/Core/modules.md#formatlinkdropurl). You just need to provide the base URL format and the private key you wish to embed. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/function-call-drop/fc-example.js#L73-L79 +``` + +--- + +## Complete Code +Now that everything has been put together, the final code can be seen below. + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/function-call-drop/fc-example.js#L1-L86 +``` + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/function-call-drop/fc-near-example.js#L1-L95 +``` + + + + +--- + +## Testing +### Running the Script +Here, you'll learn how to run the code that was just covered, and what to expect. + +To view the completed code, clone the [Keypom Docs Examples](https://github.com/keypom/keypom-docs-examples) repository and navigate to the `basic-tutorials/fc-drop`. +``` bash +git clone https://github.com/keypom/keypom-docs-examples.git && cd keypom-docs-examples/basic-tutorials/fc-drop +``` +From there, you can and open the `fc-example.js` file. + +To run the code you just cloned, return to the `keypom-docs-examples` directory and install all the necessary packages. +```bash +cd .. && cd .. && yarn +``` + +:::caution +Prior to running these scripts, ensure you replace all instances of `keypom-docs-demo.testnet` in the script with the credentials of your account found in your `~/.near-credentials` folder +::: + +From there, you can run this FC Drop script that was made in this tutorial using the following command: +``` bash +yarn basic:fc:keypom +``` +:::note +The SDK script is being tested here; use `yarn basic:fc:naj` to test the `NEAR-API-JS` script instead. +::: +This should return a successful drop creation and console log a Public Key and Linkdrop +``` bash +Public Keys: [ 'ed25519:55FkiRc4J3c1zLgzuTYxJMebVrpraXU3P7zPymDtbssN' ] +Linkdrops: [ + 'https://testnet.mynearwallet.com/linkdrop/v2.keypom.testnet/2BB8cx2xaKzY1ENBCoVz7bTFUgq8Gx6Ar27D5PbCv39NnZLfWxw3XqWr37HZ1xm3KdQ5uCt8hvt6ztF1eGBQC1Hi' +] +Keypom Contract Explorer Link: explorer.testnet.near.org/accounts/v2.keypom.testnet.com +``` +To see the full console log from this drop creation, see the expandable section below. + +
+Console Log of Test +

+ +``` bash +Receipts: 4MTrVP1cvemzA1XhmX4hHErYvmcgMCgfrXydwNTeez3Y, 8LDCtYSsN5ccFY5udxbYqoVzmxyubqZBRLvMR33FUREN + Log [v2.keypom.testnet]: Current Block Timestamp: 1682352446955649219 + Log [v2.keypom.testnet]: 21 calls with 105000000000000 attached GAS. Pow outcome: 1.8602935. Required Allowance: 20248156910387200000000 + Log [v2.keypom.testnet]: Total required storage Yocto 14230000000000000000000 + Log [v2.keypom.testnet]: Current balance: 9.3089748, + Required Deposit: 2.0354781, + total_required_storage: 0.01423, + Drop Fee: 0, + Key Fee: 0 Total Key Fee: 0, + allowance: 0.0202481 total allowance: 0.0202481, + access key storage: 0.001 total access key storage: 0.001, + deposits less none FCs: 1 total deposits: 1 lazy registration: false, + deposits for FCs: 1 total deposits for FCs: 1, + uses per key: 1 + None FCs: 0, + length: 1 + GAS to attach: 100000000000000 + Log [v2.keypom.testnet]: New user balance 7.2734966 + Log [v2.keypom.testnet]: Fees collected 0 +Public Keys: [ 'ed25519:55FkiRc4J3c1zLgzuTYxJMebVrpraXU3P7zPymDtbssN' ] +Linkdrops: [ + 'https://testnet.mynearwallet.com/linkdrop/v2.keypom.testnet/2BB8cx2xaKzY1ENBCoVz7bTFUgq8Gx6Ar27D5PbCv39NnZLfWxw3XqWr37HZ1xm3KdQ5uCt8hvt6ztF1eGBQC1Hi' +] +Keypom Contract Explorer Link: explorer.testnet.near.org/accounts/v2.keypom.testnet.com +``` + +

+
+ +### Claiming and Explorer Transactions +Once you click the link, it will take you to the following NEAR Wallet page, where you will have the choice to claim with an existing account or create a new one. +

NEAR Wallet claim

+ +To check the transactions, click the final link in the console log when you run the script. +```bash +Keypom Contract Explorer Link: https://explorer.testnet.near.org/accounts/v2.keypom.testnet +``` + +From there, you should be able to see the [`create_drop`](https://explorer.testnet.near.org/transactions/DF6awbmts4hhACBTA8oBSGdt1oJh7FNCBkv36wZboZXR) and [`claim`](https://explorer.testnet.near.org/transactions/m2LJE2Xv1TMwpbEm5SVj2VGqZxBybkQphXouupJKMg8) transactions. +

explorer transactions

+ +Within the [`claim`](https://explorer.testnet.near.org/transactions/Cgckyr9EEC3o9MDiL8E2mvs6JYPuCApYqWjpgZvy3z6U) transaction, you can also see that `nft_mint` was called on the `nft.examples.testnet` contract. +

explorer transactions

+ +This can be confirmed by visiting the "Collectibles" tab in your NEAR wallet. You should see the newly minted NFT in your wallet. +

NFT collectibles claim

+ +--- + +## Conclusion +In this tutorial, you learned the how to [create a function call drop](fc-drops.md#creating-drop-with-function-call-data) using the `fcData` parameter. Once the drop was created, you constructed a valid linkdrop using the private keys in order to claim the assets. + +Now that you've had a good introduction to creating all 4 Keypom drop types, feel free to modify the scripts created or move on to the [Advanced Tutorials](../Advanced/ticketing/introduction.md) for more challenging and practical examples. diff --git a/versioned_docs/version-2.0/Tutorials/Basics/ft-drops.md b/versioned_docs/version-2.0/Tutorials/Basics/ft-drops.md new file mode 100644 index 00000000..19197f2c --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Basics/ft-drops.md @@ -0,0 +1,447 @@ +--- +sidebar_label: 'Fungible Token Drop' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Fungible Token Drop + +## Introduction +In this tutorial, you will learn how to create a fungible token drop from scratch. This allows you onboard users both with $NEAR and a set of FTs with the click of a link. An excellent use case can be seamlessly offering in-game currency to players. + +

ft claim

+ +To learn more about the FT drop, see the [concepts page](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/ft-drops.md) + + +--- + +## Prerequisites +For the basic tutorials, you can choose to run the scripts on your own machine. To do so, you must have the following: + +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [NEAR-API-JS](https://docs.near.org/tools/near-api-js/quick-reference#install) +3. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + +With this tutorial, you can either create your own script by following along, or view the completed script available in the [Keypom Documentation Examples](https://github.com/keypom/keypom-docs-examples) repo. + +### Creating your Project +In this section, you're going to create your project and install the SDK to prepare for the tutorial. If you have a completed script and have installed the SDK, you can skip [forward](simple-drops.md#breaking-down-the-problem). + +First, you need to give your project a home. + +```bash +mkdir my-keypom-project && cd my-keypom-project +``` + +Next, you'll want to create a default `package.json` file using the following command. You can accept all default values. +```bash +npm init +``` + +At this point, your project structure should look like this. +```bash +/my-keypom-project +โ”œโ”€โ”€ package.json +``` + +If you open `package.json`, you should see this. + +
+Default package.json +

+ +``` bash +{ + "name": "my-keypom-project", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC" +} +``` + +

+
+ +The next step is to create an empty JavaScript file. + + + +```bash +touch ft-keypom.js +``` + + + + +```bash +fsutil file createnew ft-keypom.js 0 +``` + + + + +Finally, the last step is to install the Keypom JS SDK. +```bash +npm install @keypom/core +``` + +After installing the SDK, your `package.json` file should now look slightly different. + +
+package.json after installing the SDK +

+ +```bash +{ + "name": "my-keypom-project", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC", + # highlight-start + "dependencies": { + "@keypom/core": "^1.0.0" + } + # highlight-end +} +``` + +

+
+ +With these steps complete, your project folder should look like this. + +```bash +/my-keypom-project +โ”œโ”€โ”€ ft-keypom.js +โ”œโ”€โ”€ package.json +โ”œโ”€โ”€ package-lock.json +โ”œโ”€โ”€ node_modules +โ”‚ โ””โ”€โ”€ @keypom/core +โ”‚ โ””โ”€โ”€ ... +``` + +You are now ready to begin creating your drop! + +--- + + +## Breaking Down the Problem + +The process of creating an FT drop can be broken down into the following steps. + +1) Connect to the NEAR blockchain. +2) Ensure the funder has enough FTs to fund the drop. +3) Create the drop. +4) Transfer Keypom the necessary Fungible Tokens. +5) Create linkdrops. + +The following skeleton code can be used as a starting point: +```js +// Each of the two methods to create this drop will have their own unique set of imports + +// Imports used in the Keypom SDK method: +const { initKeypom, createDrop, getEnv, formatLinkdropUrl } = require("@keypom/core"); +const { parseNearAmount } = require("@near-js/utils"); +const { UnencryptedFileSystemKeyStore } = require("@near-js/keystores-node"); +const { Near } = require("@near-js/wallet-account"); +const { Account } = require("@near-js/accounts"); +const { BN } = require("bn.js"); +const path = require("path"); +const homedir = require("os").homedir(); + +// Imports used in the NEAR-API-JS method: +const { parseNearAmount } = require("@near-js/utils"); +const { KeyPair } = require("@near-js/crypto") +const { Near } = require("@near-js/wallet-account"); +const { Account } = require("@near-js/accounts"); +const { UnencryptedFileSystemKeyStore } = require("@near-js/keystores-node"); +const { getRecentDropId } = require("../utils/general.js") +const { BN } = require("bn.js"); +const path = require("path"); +const homedir = require("os").homedir(); + + +async function FTDropKeypom(){ +// GETTING STARTED + +// STEP 1 Initialize NEAR blockchain connection. + +// STEP 2 Ensure the funder has enough FTs to fund the drop. + +// CREATING DROP AND TRANSFERRING FTs + +// STEP 3 Create the drop. + +// STEP 4 Transfer Keypom the necessary Fungible Tokens. + +// CREATING LINKDROPS + +// STEP 5 Create Linkdrops +} + +FTDropKeypom() +``` +Steps 1 and 2 will be covered in "[Getting Started](ft-drops.md#getting-Started)" and Steps 3, 4, and 5 will be under "[Creating FT drop and Transferring FTs](ft-drops.md#creating-drop-and-transferring-fts)". Step 6 will have its own section called "[Creating Linkrops](ft-drops.md#creating-linkdrops)". + +--- + +## Getting Started +In this section, you'll be addressing the first two steps: connecting to NEAR and ensuring the funder has enough FTs for the drop. + +Connecting to the NEAR blockchain will be done using `NEAR-API-JS` and consists of the following steps: + +1) Create a Keystore, which stores your access keys used to sign transactions + * select a network, either `testnet` or `mainnet` + * choose a location where the keypairs live, either a folder on your local machine, or in-memory + +2) Define a NEAR configuration using the Keystore +3) Use the configuration to initialize a connection to NEAR + +More information about this process can be found [here](https://docs.near.org/tools/near-api-js/quick-reference#key-store). + +:::note +For simplicity, this tutorial will choose a file-based keystore and point to the `~/.near-credentials` folder on your local machine since this is where most of your keys are stored. For more information about KeyStores, visit NEAR's [official docs](https://docs.near.org/tools/near-api-js/quick-reference#key-store). +::: + +To ensure the funder has enough FTs to fund the drop, a new concept is to be defined. + +:::info +`amountToTransfer` = *FT per use* * *number of keys* * *uses per key*. +::: + +Using `NEAR-API-JS`, a `viewFunction` to the FT contract can be made to call `ft_balance_of`. This will return the funder's FT balance, which can be compared with `amountToTransfer` to ensure the funder has enough FTs to fund the drop. + + + +The code for setting up the NEAR connection and ensuring sufficient funder FT balance is shown below. In the skeleton code, these are steps 1 and 2. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/fungible-token-drop/ft-example.js#L11-L45 +``` +:::note +In the code, you may notice the balances defined using `BN`. These are simply *Big Numbers* and is a library built to handle numbers beyond JavaScript's [max safe integer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER). + +The FTs in this example have a `decimal` of 24. This is the same as 1 $NEAR -> 1024 YoctoNEAR, which allows the use of [`parseNearAmount`](https://docs.near.org/tools/near-api-js/utils) to convert between the two. Read more on the decimal parameter [here](https://docs.openzeppelin.com/contracts/3.x/erc20#a-note-on-decimals). +::: + +--- + +## Creating Drop and Transferring FTs +In this section of the tutorial, you'll be creating the drop and transferring the FTs to Keypom using the Keypom SDK. + +As outlined in to introduction, there are 2 tasks to complete in this section. + +- Create the drop +- Transfer the FTs to Keypom + + +This process starts with calling the `initKeypom` function and will always be the first function you call to interact with the SDK. + +`initKeypom` initializes the SDK to allow for interactions with the Keypom smart contracts. Without it, none of the other SDK functions would work as expected. If a NEAR connection is not already present, it will initialize a new one for you. More info on the `initKeypom` function can be found [here](../../keypom-sdk/Core/modules.md#initkeypom). + +Following the `initKeypom` call, the FT Drop is created. This is done by calling `createDrop` and adding an `ftData` parameter. + +:::tip +Recall that the private keys being generated using `createDrop` are used to store the assets. These keys are then embedded within a link. + +In an FT Drop, the assets consist of FTs and optional $NEAR. +::: + + +`ftData` is an object with the following properties. +```bash +ftData +โ”œโ”€โ”€ contractId +โ”œโ”€โ”€ senderId +โ”œโ”€โ”€ amount +``` + + +- `contractId`: The FT contract ID +- `senderId`: The account from which the FTs will be sent to Keypom. +- `amount`: This is the human readable amount of FT, based on the [decimals value](https://docs.openzeppelin.com/contracts/3.x/erc20#a-note-on-decimals) of the token + +Including the `ftData` parameter categorizes this as an FT drop. Without it, the Keypom Protocol would treat this drop as a Simple Drop. + +More information on the `ftData` parameter can be found [here](../../keypom-sdk/Core/interfaces/FTData.md). + +:::info +So long as the funder has an adequate FT balance, all you need to do is call `createDrop` with `ftData` to create the drop. + +The SDK will **automatically** register Keypom on the FT contract and transfer the FTs to Keypom for you. +::: + +To see what the SDK is doing behind the scenes, a `NEAR-API-JS` equivalent NodeJS script has been provided. + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/fungible-token-drop/ft-example.js#L47-L70 +``` + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/fungible-token-drop/ft-near-example.js#L50-L115 +``` + + + + +--- + +## Creating Linkdrops +The last step in this process is to create the links themselves so that you can easily distribute the assets to people. This is done by embedding the private key, containing the $NEAR, into the link along with the Keypom contract ID. + +With the Keypom SDK, this is all neatly wrapped up in the function [`formatLinkdropUrl`](../../keypom-sdk/Core/modules.md#formatlinkdropurl). You just need to provide the base URL format and the private key you wish to embed. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/fungible-token-drop/ft-example.js#L72-L78 +``` + +--- + +## Full Code +Now that everything has been put together, the final code can be seen below. + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/fungible-token-drop/ft-example.js#L1-L86 +``` + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/fungible-token-drop/ft-near-example.js#L1-L127 +``` + + + + +--- + +## Testing +### Running the Script +Here, you'll learn how to run the code that was just covered, and what to expect. + +To view the completed code, clone the [Keypom Docs Examples](https://github.com/keypom/keypom-docs-examples) repository and navigate to the `basic-tutorials/ft-drop`. +``` bash +git clone https://github.com/keypom/keypom-docs-examples.git && cd keypom-docs-examples/basic-tutorials/ft-drop +``` +From there, you can and open the `ft-example.js` file. + +To run the code you just cloned, return to the `keypom-docs-examples` directory and install all the necessary packages. +```bash +cd .. && cd .. && yarn +``` + +:::caution +Prior to running these scripts, ensure you replace all instances of `keypom-docs-demo.testnet` in the script with the credentials of your account found in your `~/.near-credentials` folder +::: + +From there, you can run this FT Drop script that was made in this tutorial using the following command: +``` bash +yarn basic:ft:keypom +``` +:::note +The SDK script is being tested here; use `yarn basic:ft:naj` to test the `NEAR-API-JS` script instead. +::: +This should return a successful drop creation and console log a Public Key and Linkdrop + +```bash +Public Keys: [ 'ed25519:DkvGVA8UuBRKtsXvBxnKkHs2aHzd221QSquinokfJ71a' ] +Linkdrops: [ + 'https://testnet.mynearwallet.com/linkdrop/v2.keypom.testnet/2H8i9Snk4v3wBBHeTxBFuzzi1SF5DL4nFHvMUp1nDz4ARSW3tB5b8z2Xxm6Y5rMzzVS3sDppPxM4jtRhyYkHfF2Y' +] +Keypom Contract Explorer Link: explorer.testnet.near.org/accounts/v2.keypom.testnet.com +``` + +To see the full console log from this drop creation, see the expandable section below. + +
+Console Log of Test +

+ +``` bash +Receipts: AxiAwWNkKQsyvdcAhwBr2B2Qqc5gVCBw2MLrbL7dLq6d, 6QCHm8YtpfreHYQvw9VAHU7rJXGgfVv4T1TDcuXHEtvC, 5CTcWfQ1BC1nensRK6NhcNSv5NjxdSaVSwti4j34fCa3 + Log [v2.keypom.testnet]: Current Block Timestamp: 1682352345716601116 + Log [v2.keypom.testnet]: 21 calls with 105000000000000 attached GAS. Pow outcome: 1.8602935. Required Allowance: 20248156910387200000000 + Log [v2.keypom.testnet]: was_ft_registered: true + Log [v2.keypom.testnet]: Total required storage Yocto 11980000000000000000000 + Log [v2.keypom.testnet]: Current balance: 8.2955772, + Required Deposit: 1.0332281, + total_required_storage: 0.01198, + Drop Fee: 0, + Key Fee: 0 Total Key Fee: 0, + allowance: 0.0202481 total allowance: 0.0202481, + access key storage: 0.001 total access key storage: 0.001, + deposits less none FCs: 1 total deposits: 1 lazy registration: false, + deposits for FCs: 0 total deposits for FCs: 0, + uses per key: 1 + None FCs: 0, + length: 1 + GAS to attach: 100000000000000 + Log [v2.keypom.testnet]: New user balance 7.262349 + Log [v2.keypom.testnet]: Fees collected 0 + Log [v2.keypom.testnet]: Performing CCC to get storage from FT contract +Receipts: 4PPt4W1C9xYP2yc67CLVX6vvYshf1oCoDr9hBiZUniTZ, 8iSu5McdW8rvPApvYjbPhew6wGZ9raAPiR8SEA43tV86 + Log [v2.keypom.testnet]: User has enough balance to cover FT storage. Subtracting 0.0025 from user balance. User balance is now 7.259849 + Log [v2.keypom.testnet]: 21 calls with 105000000000000 attached GAS. Pow outcome: 1.8602935. Required Allowance: 20248156910387200000000 + Log [v2.keypom.testnet]: FT contract already registered. Refunding user balance for 0.00125. Balance is now 7.261099 +Receipts: 9FEiXh19PMMRirF4CGDTEfopWxf6eLWxNvJmUMnrrVX8, AwJ362Sj4PZ3EbusnwLo4qoyExXRRZPAyqUUT1uZ64oi, 8KquU3a2BA3AWb9keYfwYvYpD6iD5CQG1Vn78efBex9B + Log [ft.keypom.testnet]: EVENT_JSON:{"standard":"nep141","version":"1.0.0","event":"ft_transfer","data":[{"old_owner_id":"keypom-docs-demo.testnet","new_owner_id":"v2.keypom.testnet","amount":"1"}]} +Receipt: 9Ls4K4vm8pW7HcjD6PMBbJoWSsjwN16YEq3GdCqnahPx + Log [ft.keypom.testnet]: New uses registered 1 +Public Keys: [ 'ed25519:DkvGVA8UuBRKtsXvBxnKkHs2aHzd221QSquinokfJ71a' ] +Linkdrops: [ + 'https://testnet.mynearwallet.com/linkdrop/v2.keypom.testnet/2H8i9Snk4v3wBBHeTxBFuzzi1SF5DL4nFHvMUp1nDz4ARSW3tB5b8z2Xxm6Y5rMzzVS3sDppPxM4jtRhyYkHfF2Y' +] +Keypom Contract Explorer Link: explorer.testnet.near.org/accounts/v2.keypom.testnet.com +``` + +

+
+ +### Claiming and Explorer Transactions +Once you click the link, it will take you to the following NEAR Wallet page, where you will have the choice to claim with an existing account or create a new one. +

NEAR Wallet claim

+ +In your NEAR wallet, you should now be able to see the FT tokens that were transferred to you. +

ft claim

+ +To check the transactions, click the final link in the console log when you run the script. +```bash +Keypom Contract Explorer Link: https://explorer.testnet.near.org/accounts/v2.keypom.testnet +``` + +From there, you should be able to see the [`create_drop`](https://explorer.testnet.near.org/transactions/6HkwpwWVA7m1tAGj75JGpF975toStWRF1y8FSRDMPPfT), [`ft_transfer_call`](https://explorer.testnet.near.org/transactions/47HmGKAHx4TDp6vNbnBAb9ifS1gTXrC58o7svFmZDYzk) and [`claim`](https://explorer.testnet.near.org/transactions/62gQiyQjx9z9WJsVQNaaa4fje9PeeTpCuHun2PZ8WjNm) transactions. +

explorer transactions

+ + +:::note +Recall that `ft_transfer_call` is never explicitly called but rather `createDrop` calls it for you; this can be seen in the explorer shown above. + +This is the SDK in action! +::: + +--- + +## Conclusion +In this tutorial, you've learned to ensure the funder has a [sufficient FT balance](ft-drops.md#getting-started) for the drop, [create an FT drop](ft-drops.md#creating-drop-and-transferring-fts) with the SDK, and to [transfer FTs](ft-drops.md#creating-drop-and-transferring-fts) to Keypom. Once the drop was created, you constructed a valid linkdrop using the private keys in order to claim the assets. + +In the next tutorial, you will learn to create a function call drop. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Basics/getting-started.md b/versioned_docs/version-2.0/Tutorials/Basics/getting-started.md new file mode 100644 index 00000000..9d0ffd2f --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Basics/getting-started.md @@ -0,0 +1,43 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Getting Started +The primary goal of a Keypom drop is to send assets to users with the click of a link regardless of whether they have a wallet or not. These assets can come in many forms which will be broken down below. + +The basic tutorials are meant as introductory guides that will help you create your first Keypom drops and understand the differences between the [types](/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/introduction.md) of Keypom drops and the assets they contain. + +There are **four** types of drops, each with different types of assets. These drops can be claimed either with a brand new NEAR account or an existing one. + + +| Drop Type | Assets | +| -------------------------------------------------------------------------------------------------- | -------------------------------------------| +| [Simple Drop](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/simple-drops.md) | $NEAR | +| [Non-Fungible Token Drop](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/nft-drops.md) | NFT and optionally $NEAR | +| [Fungible Token Drop](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/ft-drops.md) | Fungible Tokens and optionally $NEAR | +| [Function Call Drop](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops.md) | Set of function-calls and optionally $NEAR | + + +The [Simple Drop](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/simple-drops.md) is the most basic type of drop, it allows you to send $NEAR via a link to new or existing users. + +[NFT Drops](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/nft-drops.md) and [FT Drops](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/ft-drops.md) are extensions of the Simple drop, they allow you to send NFTs and FTs in addition to $NEAR. + +The [Function Call Drop](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops.md) is Keypom's most powerful type of drop. It allows you send a link that is capable of calling almost any function on any smart contract that you predefine. A simple example of this is auto-registering users into a DAO as part of the onboarding process. + +While there are many [drop configurations](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/customization-homepage.md) available to developers such as multi-use keys or time-based restrictions, in these basic tutorials, a single use key with no additional configurations will be created. + +Throughout each tutorial, two simple NodeJS scripts will be created that use both NEAR's native [NEAR-API-JS](https://docs.near.org/tools/near-api-js/reference) library, and Keypom's [JS-SDK](https://github.com/keypom/keypom-js). + +--- + +## Prerequisites +For the basic tutorials, you can choose to run the scripts on your own machine. To do so, you must have the following: + +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [NEAR-API-JS](https://docs.near.org/tools/near-api-js/quick-reference#install) +3. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + +At this point, you are ready to start the tutorials. + +Alternatively, if you wish to use ready-to-use scripts that can be customized to your liking in order to quickly create Keypom drops, visit the [Keypom Protocol](https://github.com/keypom/keypom#deploy-scripts). + + diff --git a/versioned_docs/version-2.0/Tutorials/Basics/nft-drops.md b/versioned_docs/version-2.0/Tutorials/Basics/nft-drops.md new file mode 100644 index 00000000..0d7bee2b --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Basics/nft-drops.md @@ -0,0 +1,429 @@ +--- +sidebar_label: 'Non Fungible Token Drop' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Non Fungible Token Drop + +## Introduction +In this tutorial, you will learn how to create a non-fungible token drop from scratch. This allows you onboard users both with $NEAR and an existing NFT with the click of a link. This is great for sending an NFT that you own to your friends without needing to worry about whether or not they have a NEAR wallet. + + +

MyNearWallet claim

+ +To learn more about the NFT drop, see the [concepts page](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/nft-drops.md) + +--- + +## Prerequisites +For the basic tutorials, you can choose to run the scripts on your own machine. To do so, you must have the following: + +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [NEAR-API-JS](https://docs.near.org/tools/near-api-js/quick-reference#install) +3. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + +With this tutorial, you can either create your own script by following along, or view the completed script available in the [Keypom Documentation Examples](https://github.com/keypom/keypom-docs-examples) repo. + +### Creating your Project +In this section, you're going to create your project and install the SDK to prepare for the tutorial. If you have a completed script and have installed the SDK, you can skip [forward](simple-drops.md#breaking-down-the-problem). + +First, you need to give your project a home. + +```bash +mkdir my-keypom-project && cd my-keypom-project +``` + +Next, you'll want to create a default `package.json` file using the following command. You can accept all default values. +```bash +npm init +``` + +At this point, your project structure should look like this. +```bash +/my-keypom-project +โ”œโ”€โ”€ package.json +``` + +If you open `package.json`, you should see this. + +
+Default package.json +

+ +``` bash +{ + "name": "my-keypom-project", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC" +} +``` + +

+
+ +The next step is to create an empty JavaScript file. + + + +```bash +touch nft-keypom.js +``` + + + + +```bash +fsutil file createnew nft-keypom.js 0 +``` + + + + +Finally, the last step is to install the Keypom JS SDK. +```bash +npm install @keypom/core +``` + +After installing the SDK, your `package.json` file should now look slightly different. + +
+package.json after installing the SDK +

+ +```bash +{ + "name": "my-keypom-project", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC", + # highlight-start + "dependencies": { + "@keypom/core": "^1.0.0" + } + # highlight-end +} +``` + +

+
+ +With these steps complete, your project folder should look like this. + +```bash +/my-keypom-project +โ”œโ”€โ”€ nft-keypom.js +โ”œโ”€โ”€ package.json +โ”œโ”€โ”€ package-lock.json +โ”œโ”€โ”€ node_modules +โ”‚ โ””โ”€โ”€ @keypom/core +โ”‚ โ””โ”€โ”€ ... +``` + +You are now ready to begin creating your drop! + +--- + +## Breaking Down the Problem + +The process of creating an NFT drop can be broken down into the following steps. + +1) Establish a connection to the NEAR blockchain. +2) If you don't own the NFT, mint it using the `nft_mint` function. +3) Create the keys and the drop with the NFT information. +4) Transfer ownership of the NFTs to Keypom. +5) Create linkdrops. + +:::info +The NFT ownership must be transferred to Keypom so that it can send the NFT to the user when they claim their drop. +::: + +The following skeleton code can be used as a starting point: + +```js +// Each of the two methods to create this drop will have their own unique set of imports + +// Imports used in the Keypom SDK method: +const { initKeypom, createDrop, getEnv, formatLinkdropUrl } = require("@keypom/core"); +const { parseNearAmount } = require("@near-js/utils"); +const { UnencryptedFileSystemKeyStore } = require("@near-js/keystores-node"); +const { Near } = require("@near-js/wallet-account"); +const { Account } = require("@near-js/accounts"); +const path = require("path"); +const homedir = require("os").homedir(); + +// Imports used in the NEAR-API-JS method: +const { parseNearAmount } = require("@near-js/utils"); +const { KeyPair } = require("@near-js/crypto") +const { UnencryptedFileSystemKeyStore } = require("@near-js/keystores-node"); +const { Near } = require("@near-js/wallet-account"); +const { Account } = require("@near-js/accounts"); +const { getRecentDropId } = require("../utils/general.js") +const path = require("path"); +const homedir = require("os").homedir(); + + +async function NFTDropKeypom(){ +// GETTING STARTED + +// STEP 1: Initiate a NEAR connection. + +// STEP 2: Mint NFTs + +// CREATING DROP AND TRANSFERRING NFTs + +// STEP 3: Create NFT drop + +// STEP 4: Transfer NFTs to Keypom + +// CREATING LINKDROPS + +// STEP 5: Create Linkdrops +} + +NFTDropKeypom() +``` + +For this tutorial, steps 1 and 2 will be grouped under "[Getting Started](nft-drops.md#getting-started)", steps 3 and 4 will be grouped under "[Creating drop and transferring NFT](nft-drops.md#creating-drop-and-transferring-nft)", and step 5 will have its own section called "[Creating Linkrops](nft-drops.md#creating-linkdrops)". + +--- + +## Getting Started +In this section, the NEAR blockchain connection is set up and the NFTs will be minted to ensure you are transferring NFTs that *you* own. If you already own the NFTs you wish to add to the drop, there is no need to mint them here. + +Connecting to the NEAR blockchain will be done using `NEAR-API-JS` and consists of the following steps: + +1) Create a Keystore, which stores your access keys used to sign transactions + * select a network, either `testnet` or `mainnet` + * choose a location where the keypairs live, either a folder on your local machine, or in-memory + +2) Define a NEAR configuration using the Keystore +3) Use the configuration to initialize a connection to NEAR + +More information about this process can be found [here](https://docs.near.org/tools/near-api-js/quick-reference#key-store). + +:::note +For simplicity, this tutorial will choose a file-based keystore and point to the `~/.near-credentials` folder on your local machine since this is where most of your keys are stored. For more information about KeyStores, visit NEAR's [official docs](https://docs.near.org/tools/near-api-js/quick-reference#key-store). +::: + +The code for setting up the NEAR connection and minting the NFT is shown below. In the skeleton code, these are steps 1 and 2. + +``` js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/non-fungible-token-drop/nft-example.js#L11-L49 +``` + +:::note +The NFT must be minted with a `NEAR-API-JS` `functionCall` to the NFT contract. + +Function arguments for `functionCall` can be found [here](https://docs.near.org/tools/near-api-js/reference/modules/transaction#functioncall) +::: + +--- + +## Creating Drop and Transferring NFT + +In this section of the tutorial, you'll be creating the NFT drop and transferring the NFT to Keypom using the Keypom SDK. + +This process starts with calling the `initKeypom` function and will always be the first function you call to interact with the SDK. + +`initKeypom` initializes the SDK to allow for interactions with the Keypom smart contracts. Without it, none of the other SDK functions would work as expected. If a NEAR connection is not already present, it will initialize a new one for you. More info on the `initKeypom` function can be found [here](../../keypom-sdk/Core/modules.md#initkeypom). + +After calling `initKeypom`, the NFT Drop is created. This is done by calling `createDrop` and adding an `nftData` parameter. + +:::tip +Recall that the private keys being generated using `createDrop` are used to store the assets. These keys are then embedded within a link. + +In an NFT Drop, the assets consist of an NFT and optional $NEAR. +::: + +`nftData` is an object with the following properties. + +```bash +nftData +โ”œโ”€โ”€ contractId +โ”œโ”€โ”€ senderId +โ”œโ”€โ”€ tokenIds +``` + +- `contractId`: The contract ID where the NFTs for this drop are coming from +- `senderId`: The current owner of the NFTs that will be sent to Keypom +- `tokenIds`: A list of all the token IDs to be sent to Keypom during the NFT drop creation process. + +Including the `nftData` parameter categorizes this as an NFT drop. Without it, the Keypom Protocol would treat this drop as a Simple Drop. + +More information on the `nftData` parameter can be found [here](../../keypom-sdk/Core/interfaces/NFTData.md). + +To see what the SDK is doing behind the scenes, a `NEAR-API-JS` equivalent NodeJS script has been provided. + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/non-fungible-token-drop/nft-example.js#L51-L74 +``` + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/non-fungible-token-drop/nft-near-example.js#L52-L101 +``` + + + + +:::note +All function parameters and default values for the SDK and Keypom functions can be found in the [SDK Typedocs](../../keypom-sdk/Core/modules.md). For `NEAR-API-JS` functions, their arguments can be found [here](https://docs.near.org/tools/near-api-js/reference) +::: + +--- + +## Creating Linkdrops +The last step in this process is to create the links themselves so that you can easily distribute the assets to people. This is done by embedding the private key, containing the $NEAR, into the link along with the Keypom contract ID. + +With the Keypom SDK, this is all neatly wrapped up in the function [`formatLinkdropUrl`](../../keypom-sdk/Core/modules.md#formatlinkdropurl). You just need to provide the base URL format and the private key you wish to embed. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/non-fungible-token-drop/nft-example.js#L76-L82 +``` + +--- + +## Full Solution +Now that everything has been put together, the final code can be seen below. + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/non-fungible-token-drop/nft-example.js#L1-L89 +``` + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/non-fungible-token-drop/nft-near-example.js#L1-L114 +``` + + + + +--- + +## Testing +### Running the Script +Here, you'll learn how to run the code that was just covered, and what to expect. + +To view the completed code, clone the [Keypom Docs Examples](https://github.com/keypom/keypom-docs-examples) repository and navigate to the `basic-tutorials/nft-drop`. +``` bash +git clone https://github.com/keypom/keypom-docs-examples.git && cd keypom-docs-examples/basic-tutorials/nft-drop +``` +From there, you can and open the `nft-example.js` file. + +To run the code you just cloned, return to the `keypom-docs-examples` directory and install all the necessary packages. +```bash +cd .. && cd .. && yarn +``` + +:::caution +Prior to running these scripts, ensure you replace all instances of `keypom-docs-demo.testnet` in the script with the credentials of your account found in your `~/.near-credentials` folder +::: + +From there, you run this NFT Drop script that was made in this tutorial using the following command: +``` bash +yarn basic:nft:keypom +``` +:::note +The SDK script is being tested here; use `yarn basic:nft:naj` to test the `NEAR-API-JS` script instead. +::: +This should return a successful drop creation and console log a Public Key and Linkdrop: +```bash +Public Keys: [ 'ed25519:Cf48tjtLrRDm5qYN5fyNvPHBTNVkSsX2mP2mfw2W2f3N' ] +Linkdrops: [ + 'https://testnet.mynearwallet.com/linkdrop/v2.keypom.testnet/4iBKGBMhKo3BLi8wfc6qDPxUG3xrsXygDbzVwXBsh3tEvLVE2a4EGDtHreH89a7peAhC8yot1Zm5vd3nfnxxmzv4' +] +Keypom Contract Explorer Link: explorer.testnet.near.org/accounts/v2.keypom.testnet.com +``` + +To see the full console log from this drop creation, see the expandable section below. + +
+Console Log of Test +

+ +``` bash +Receipts: 94Hxiw6dy2VbgfWWuL8scyAKutgmZ6TnyaGLuSdw8bdw, EPBCevWD8jCmVmRhH4r7nEWY5P5mHNXBzxRs8FFmjh1s + Log [nft.examples.testnet]: EVENT_JSON:{"standard":"nep171","version":"nft-1.0.0","event":"nft_mint","data":[{"owner_id":"keypom-docs-demo.testnet","token_ids":["keypom-token-1682351707371"]}]} +Receipts: 8VKpVfRZkPBJzZR42aBiytbECXFYqAvLF72jRUgaccHt, AV5tmBbWuzkV7DLNX6o4LgkeBysShJ647VmdY3ye15s + Log [v2.keypom.testnet]: Current Block Timestamp: 1682351728091701553 + Log [v2.keypom.testnet]: 21 calls with 105000000000000 attached GAS. Pow outcome: 1.8602935. Required Allowance: 20248156910387200000000 + Log [v2.keypom.testnet]: Total required storage Yocto 12140000000000000000000 + Log [v2.keypom.testnet]: Current balance: 8.2333838, + Required Deposit: 1.0333881, + total_required_storage: 0.01214, + Drop Fee: 0, + Key Fee: 0 Total Key Fee: 0, + allowance: 0.0202481 total allowance: 0.0202481, + access key storage: 0.001 total access key storage: 0.001, + deposits less none FCs: 1 total deposits: 1 lazy registration: false, + deposits for FCs: 0 total deposits for FCs: 0, + uses per key: 1 + None FCs: 0, + length: 1 + GAS to attach: 100000000000000 + Log [v2.keypom.testnet]: New user balance 7.1999957 + Log [v2.keypom.testnet]: Fees collected 0 +Receipts: HwvpQcMKQdWczLsbBsvZD72UdJTpY6BTDPZBFwk7YZFy, DGs58AziaMcgkZbhki2caZBAFC6fYa83qXfziQmmwaeU, 3zs1apRpLhdfYpdRJUidgP8YJzkPr2YKaoVT8Hitau5p + Log [nft.examples.testnet]: EVENT_JSON:{"standard":"nep171","version":"nft-1.0.0","event":"nft_transfer","data":[{"old_owner_id":"keypom-docs-demo.testnet","new_owner_id":"v2.keypom.testnet","token_ids":["keypom-token-1682351707371"]}]} +Receipt: 4HJAWvH67JtsdDVQP1vsRTniFwkALWokPRpkPbMxqArY + Log [nft.examples.testnet]: drop.registered_uses 1 + Log [nft.examples.testnet]: Subtracting 1110000000000000000000 from funder to cover storage. New balance is 7198885721113380930000000 +Public Keys: [ 'ed25519:Cf48tjtLrRDm5qYN5fyNvPHBTNVkSsX2mP2mfw2W2f3N' ] +Linkdrops: [ + 'https://testnet.mynearwallet.com/linkdrop/v2.keypom.testnet/4iBKGBMhKo3BLi8wfc6qDPxUG3xrsXygDbzVwXBsh3tEvLVE2a4EGDtHreH89a7peAhC8yot1Zm5vd3nfnxxmzv4' +] +Keypom Contract Explorer Link: explorer.testnet.near.org/accounts/v2.keypom.testnet.com +``` + +

+
+ +### Claiming and Explorer Transactions +Once you click the link, it will take you to the following NEAR Wallet page, where you will have the choice to claim with an existing account or create a new one. +

Near Wallet claim

+ +After the claim transaction succeeds, you can view the NFT in your collectibles tab. +

NFT collectibles claim

+ +To check the transactions, click the final link in the console log when you run the script. +```bash +Keypom Contract Explorer Link: https://explorer.testnet.near.org/accounts/v2.keypom.testnet +``` + +From there, you should be able to see the [`create_drop`](https://explorer.testnet.near.org/transactions/9rR6mPjoQFKC2Euuvn5yh5e6hPv3WTrMYjwja3ppkjaD), [`nft_transfer_call`](https://explorer.testnet.near.org/transactions/A2hdnm6mHQNLupFLP1vMNZ1J8QHkxLqDLqocUnQxNC5F) and [`claim`](https://explorer.testnet.near.org/transactions/5Kx9F5nxjbWpq8qUr7rRuDun8zipvR7TFbVuPoP5qwBW) transactions. +

explorer transactions

+ +:::note +Recall that `nft_transfer_call` is never explicitly called but rather `createDrop` calls it for you; this can be seen in the explorer shown above. + +This is the SDK in action! +::: + +--- + +## Conclusion +In this NFT tutorial, you learned about the steps needed while [initializing an NFT drop](nft-drops.md#getting-started) and the process of [creating the NFT drop](nft-drops.md#creating-drop-and-transferring-nft). Once the drop was created, you constructed a valid linkdrop using the private keys in order to claim the assets. + +In the next tutorial, you will learn how to create a Fungible Token drop, which is similar to the NFT drop, but transfers FTs instead of NFTs. \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/Basics/simple-drops.md b/versioned_docs/version-2.0/Tutorials/Basics/simple-drops.md new file mode 100644 index 00000000..264624c4 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Basics/simple-drops.md @@ -0,0 +1,371 @@ +--- +sidebar_label: 'Simple Drop' +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Simple Drop + +## Introduction +In this tutorial, you will learn how to create a simple $NEAR drop from scratch. By embedding $NEAR in a Web2 style link, the simple drop allows you to onboard both existing and new users. + +Being the simplest Keypom drop type, it acts as the foundation for the other 3 kinds of Keypom drops. Despite this, the simple drop opens the door to more complex use cases such as [subscription services](../../Tutorials/Advanced/subscriptions/introduction.md). + +

Near Wallet claim

+ +To learn more about the Simple Drop, see the [concepts page](../../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/simple-drops.md) + +--- + +## Prerequisites +For the basic tutorials, you can choose to run the scripts on your own machine. To do so, you must have the following: + +1. [Node JS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +2. [NEAR-API-JS](https://docs.near.org/tools/near-api-js/quick-reference#install) +3. [Keypom JS SDK](https://github.com/keypom/keypom-js#getting-started) + +With this tutorial, you can either create your own script by following along, or view the completed script available in the [Keypom Documentation Examples](https://github.com/keypom/keypom-docs-examples) repo. + +### Creating your Project +In this section, you're going to create your project and install the SDK to prepare for the tutorial. If you have a completed script and have installed the SDK, you can skip [forward](simple-drops.md#breaking-down-the-problem). + +First, you need to give your project a home. + +```bash +mkdir my-keypom-project && cd my-keypom-project +``` + +Next, you'll want to create a default `package.json` file using the following command. You can accept all default values. +```bash +npm init +``` + +At this point, your project structure should look like this. +```bash +/my-keypom-project +โ”œโ”€โ”€ package.json +``` + +If you open `package.json`, you should see this. + +
+Default package.json +

+ +``` bash +{ + "name": "my-keypom-project", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC" +} +``` + +

+
+ +The next step is to create an empty JavaScript file. + + + +```bash +touch simple-keypom.js +``` + + + + +```bash +fsutil file createnew simple-keypom.js 0 +``` + + + + +Finally, the last step is to install the Keypom JS SDK. +```bash +npm install @keypom/core +``` + +After installing the SDK, your `package.json` file should now look slightly different. + +
+package.json after installing the SDK +

+ +```bash +{ + "name": "my-keypom-project", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC", + # highlight-start + "dependencies": { + "@keypom/core": "^1.0.0" + } + # highlight-end +} +``` + +

+
+ +With these steps complete, your project folder should look like this. + +```bash +/my-keypom-project +โ”œโ”€โ”€ simple-keypom.js +โ”œโ”€โ”€ package.json +โ”œโ”€โ”€ package-lock.json +โ”œโ”€โ”€ node_modules +โ”‚ โ””โ”€โ”€ @keypom/core +โ”‚ โ””โ”€โ”€ ... +``` + +You are now ready to begin creating your drop! + +--- + +## Breaking Down the Problem + +Creating a simple drop is a four step process: + +1) Establish a connection to the NEAR blockchain. +2) Create a set of access keys where the assets will be stored. +3) Use the Keypom SDK to create the drop. +4) Create linkdrops. + +The following skeleton code can be used as a starting point: +``` js +// Each of the two methods to create this drop will have their own unique set of imports + +// Imports used in the Keypom SDK method: +const { initKeypom, createDrop, getEnv, formatLinkdropUrl } = require("@keypom/core"); +const { UnencryptedFileSystemKeyStore } = require("@near-js/keystores-node"); +const { connect, Near } = require("@near-js/wallet-account"); +const path = require("path"); +const homedir = require("os").homedir(); + +// Imports used in the NEAR-API-JS method: +const { parseNearAmount } = require("@near-js/utils"); +const { KeyPair } = require("@near-js/crypto") +const { Near } = require("@near-js/wallet-account"); +const { Account } = require("@near-js/accounts"); +const { UnencryptedFileSystemKeyStore } = require("@near-js/keystores-node"); +const path = require("path"); +const homedir = require("os").homedir(); + + +async function simpleDropKeypom(){ +// STEP 1: Initiate a NEAR connection. + +// STEP 2: Create a set of access keys + +// STEP 3: Create the drop. + +// STEP 4: Create linkdrops +} + +simpleDropKeypom() + +``` + +--- + +## Getting Started - Connecting to NEAR +The first step to create a Keypom drop is connecting to the NEAR blockchain. + +This is done with `NEAR-API-JS` and consists of the following steps: + +1) Create a Keystore, which stores your access keys used to sign transactions + * select a network, either `testnet` or `mainnet` + * choose a location where the keypairs live, either a folder on your local machine, or in-memory + +2) Define a NEAR configuration using the Keystore +3) Use the configuration to initialize a connection to NEAR + +More information about this process can be found [here](https://docs.near.org/tools/near-api-js/quick-reference#key-store). + +:::note +For simplicity, this tutorial will choose a file-based keystore and point to the `~/.near-credentials` folder on your local machine since this is where most of your keys are stored. For more information about KeyStores, visit NEAR's [official docs](https://docs.near.org/tools/near-api-js/quick-reference#key-store). +::: + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/simple-drop/simple-example.js#L10-L28 +``` + +--- + +## Creating the Simple Drop +Now that the connection to the NEAR blockchain is set up, the next step is to create the Keypairs and the drop using the Keypom SDK. + + + +`initKeypom` initializes the SDK to allow for interactions with the Keypom smart contracts. Without it, none of the other SDK functions would work as expected. If a NEAR connection is not already present, it will initialize a new one for you. More info on the `initKeypom` function can be found [here](../../keypom-sdk/Core/modules.md#initkeypom). + +After `initKeypom` is called, the key generation and drop creation can be done. These two tasks are combined into one function, `createDrop`. This function can be either given a set of pre-created keypairs, **or** it can generate them automatically based on the `numKeys` parameter. + +:::tip +Recall that the private keys being generated are used to store the assets. These keys are then embedded within a link. + +In a Simple Drop, the assest is $NEAR. +::: + +To see what the SDK is doing behind the scenes, a `NEAR-API-JS` equivalent NodeJS script has been provided. + + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/simple-drop/simple-example.js#L30-L45 +``` + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/simple-drop/simple-near-example.js#L34-L59 +``` + + + + +:::note +All function parameters and default values for the SDK and Keypom functions can be found in the [SDK Typedocs](../../keypom-sdk/Core/modules.md). For `NEAR-API-JS` functions, their arguments can be found [here](https://docs.near.org/tools/near-api-js/reference) +::: + +--- + +## Creating Linkdrops +The last step in this process is to create the links themselves so that you can easily distribute the assets to people. This is done by embedding the private key, containing the $NEAR, into the link along with the Keypom contract ID. + +With the Keypom SDK, this is all neatly wrapped up in the function [`formatLinkdropUrl`](../../keypom-sdk/Core/modules.md#formatlinkdropurl). You just need to provide the base URL format and the private key you wish to embed. + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/simple-drop/simple-example.js#L47-L53 +``` + +--- + +## Full Solution +Now that everything has been put together, the final code can be seen below. + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/simple-drop/simple-example.js#L1-L61 +``` + + + + +```js reference +https://github.com/keypom/keypom-docs-examples/blob/8202f0ef88205bfca644ccf5d4d3cfb460f88f15/basic-tutorials/simple-drop/simple-near-example.js#L1-L71 +``` + + + + +--- + +## Testing +### Running the Script +Here, you'll learn how to run the code that was just covered, and what to expect. + +To view the completed code, clone the [Keypom Docs Examples](https://github.com/keypom/keypom-docs-examples) repository and navigate to the `basic-tutorials/simple-drop`. +``` bash +git clone https://github.com/keypom/keypom-docs-examples.git && cd keypom-docs-examples/basic-tutorials/simple-drop +``` +From there, you can and open the `simple-example.js` file. + +To run the code you just cloned, return to the `keypom-docs-examples` directory and install all the necessary packages. +```bash +cd .. && cd .. && yarn +``` + +:::caution +Prior to running these scripts, ensure you replace all instances of `keypom-docs-demo.testnet` in the script with the credentials of your account found in your `~/.near-credentials` folder +::: + +From there, you can run this Simple Drop script that was made in this tutorial using the following command: +``` bash +yarn basic:simple:keypom +``` +:::note +The SDK script is being tested here; use `yarn basic:simple:naj` to test the `NEAR-API-JS` script instead. +::: +This should return a successful drop creation and console log a Public Key and Linkdrop: +```bash +Public Keys: [ 'ed25519:CsTpJ3pSZUkkcfVEsA6Fqkgz6BFgmhNfCGzPuqdj24wc' ] +Linkdrops: [ + 'https://testnet.mynearwallet.com/linkdrop/v2.keypom.testnet/CNbTQgJ83dLPvg4ibCQGH9Wi1sJhSQkh4YDXKxibXU3cn66oZP5eqLE83m5z5eTqBKxSvJzmDXH7gYTMXzMEfdk' +] +Keypom Contract Explorer Link: explorer.testnet.near.org/accounts/v2.keypom.testnet.com +``` +To see the full console log from this drop creation, see the expandable section below. + +
+Console Log of Test +

+ +``` bash +Receipts: GZegewWCTMfpKWZ8ffpVkRb3fLYjyfnyCvqRRmwRkKSt, 3tueZ12bwu86EYEgPVaMjQJuSUNfWcwnDENQGk6jGzmo + Log [v2.keypom.testnet]: Current Block Timestamp: 1682352132162930850 + Log [v2.keypom.testnet]: 21 calls with 105000000000000 attached GAS. Pow outcome: 1.8602935. Required Allowance: 20248156910387200000000 + Log [v2.keypom.testnet]: Total required storage Yocto 11170000000000000000000 + Log [v2.keypom.testnet]: Current balance: 8.2496314, + Required Deposit: 1.0324181, + total_required_storage: 0.01117, + Drop Fee: 0, + Key Fee: 0 Total Key Fee: 0, + allowance: 0.0202481 total allowance: 0.0202481, + access key storage: 0.001 total access key storage: 0.001, + deposits less none FCs: 1 total deposits: 1 lazy registration: false, + deposits for FCs: 0 total deposits for FCs: 0, + uses per key: 1 + None FCs: 0, + length: 1 + GAS to attach: 100000000000000 + Log [v2.keypom.testnet]: New user balance 7.2172133 + Log [v2.keypom.testnet]: Fees collected 0 +Public Keys: [ 'ed25519:CsTpJ3pSZUkkcfVEsA6Fqkgz6BFgmhNfCGzPuqdj24wc' ] +Linkdrops: [ + 'https://testnet.mynearwallet.com/linkdrop/v2.keypom.testnet/CNbTQgJ83dLPvg4ibCQGH9Wi1sJhSQkh4YDXKxibXU3cn66oZP5eqLE83m5z5eTqBKxSvJzmDXH7gYTMXzMEfdk' +] +Keypom Contract Explorer Link: explorer.testnet.near.org/accounts/v2.keypom.testnet.com +``` + +

+
+ +### Claiming and Explorer Transactions +Once you click the link, it will take you to the following NEAR Wallet page, where you will have the choice to claim with an existing account or create a new one. +

Near Wallet claim

+ +To check the transactions, click the final link in the console log when you run the script. +``` md +Keypom Contract Explorer Link: explorer.testnet.near.org/accounts/v2.keypom.testnet.com +``` + +From there, you should be able to see the [`create_drop`](https://explorer.testnet.near.org/transactions/6cQGRMJhmn16LCEDLKWYnFJrz3cAP7zSW36jhFwwk5sT) and [`claim`](https://explorer.testnet.near.org/transactions/BkNe1Dwzer22WW6vVBbCY75qHbkDitYYca7e4cjPTBsJ) transactions. +

explorer transactions

+ +--- + +## Conclusion +In this tutorial, you learned the basic steps of [creating a simple drop](simple-drops.md#introduction), steps to [initialize](simple-drops.md#getting-started---connecting-to-near) a NEAR blockchain connection, and how to [create](simple-drops.md#creating-the-simple-drop) the keys and drop. You also learned the purpose of the `initKeypom` function and when to use it. Once the drop was created, you constructed a valid linkdrop using the private keys in order to claim the assets. + +In the next tutorial, you'll be learning how to create and fund an NFT drop using the Keypom SDK. diff --git a/versioned_docs/version-2.0/Tutorials/Misc/sign-txn.md b/versioned_docs/version-2.0/Tutorials/Misc/sign-txn.md new file mode 100644 index 00000000..2875c55b --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/Misc/sign-txn.md @@ -0,0 +1,6 @@ +# Methods of Signing Transactions +Place holder page to discuss different methods of signing transactions. +1. Using funder object -> Unencrypted local keystore +2. Wallet object +3. Account object +4. Parsing/Exposing private key \ No newline at end of file diff --git a/versioned_docs/version-2.0/Tutorials/welcome.md b/versioned_docs/version-2.0/Tutorials/welcome.md new file mode 100644 index 00000000..c8be6cd5 --- /dev/null +++ b/versioned_docs/version-2.0/Tutorials/welcome.md @@ -0,0 +1,94 @@ +--- +sidebar_label: 'Home' +--- +# Examples and Tutorials +Welcome to the examples and tutorials section of Keypom's developer documentation. Here you'll learn how to use the power of Keypom to creating some awesome user onboarding experiences. + +There are several ways to get started using Keypom. + +## Basic Tutorials + +The basic tutorials are meant as introductory guides that will help you create your first Keypom drops and understand the differences between the [types](/Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/introduction.md) of drops and the assets they contain. All drops created in these tutorials skip [drop configurations](../Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/customization-homepage.md) to keep it simple.` + + +It is recommended you read through the [Getting Started](Basics/getting-started.md) guide before going into the tutorials. + +
+
+
+ +
+
+

Simple Drop

+

Onboarding with $NEAR.

+
+
+ +
+
+ +
+
+

Non-Fungible Token Drops

+

Share an NFT with a link

+
+
+ +
+
+
+
+ +
+
+

Fungible Token Drop

+

Send users FTs

+
+
+ +
+
+ +
+
+

Function Call Drops

+

Keypom's most customizable drop

+
+
+ +
+
+
+

+ +## Advanced Tutorials + +These tutorials are meant to provide examples of real world use cases. These can range from ticketing, to seamless DAO onboarding experiences. + +
+
+
+ +
+
+

Ticketing

+

Supercharge your next event with Keypom.

+
+
+ +
+
+ +
+
+

DAO Onboarding

+

Single-click onboarding into your DAO.

+
+
+ +
+
+
+

+ +Other use cases can range from subscriptions to DAO voting. These other advanced tutorials are currently in progress, stay tuned! diff --git a/versioned_docs/version-2.0/exec-summary.md b/versioned_docs/version-2.0/exec-summary.md new file mode 100644 index 00000000..a448aa93 --- /dev/null +++ b/versioned_docs/version-2.0/exec-summary.md @@ -0,0 +1,119 @@ +# Keypom Executive Summary + +> To discover the features and details of Keypom, begin your journey [here](Concepts/welcome.md). + +Keypom provides **zero friction onboarding** and transactions for NEAR. We allow people to **experience** the value of blockchain technology *regardless of if they have a wallet or not*. + +All of the complications such as seed-phrases, private keys, transactions and other crypto jargon can be abstracted away from the end-user. We provide a means for people to use decentralized applications **without knowing theyโ€™re on-chain**. + +Our goal is to be a community driven, public good that aims to show the world what is possible when you push NEARโ€™s technology to its limits. For the foreseeable future, our APIs (the Keypom Protocol) will be completely **fee-free**. Our entire solution is on-chain. There are no centralized databases and everything is run using NEAR smart contracts. + +Our debut talk at NEARCON can be found [here](https://www.youtube.com/watch?v=J-BOnfhHV50&ab_channel=MattLockyer). + +## The Blockchain Problem +Blockchain technology comes with many benefits such as sovereign ownership, digital rights, privacy, freedom, peer to peer coordination and much more. The problem with this technology, however, is that there is an *extremely high barrier to entry for an everyday individual*. None of it matters if nobody can onboard. + +*Itโ€™s confusing to create and fund a crypto wallet*. People are unfamiliar with the process, technical jargon, general flow, and need to go through barriers such as KYC. *Why go through such hurdles just to experience an app?* In Web2, users can accrue value from applications without being forced to onboard first. Why canโ€™t Web3 be the same? + +## The Keypom Solution +On other chains, a common approach to onboarding users is to send them a pre-created, pre-loaded wallet. Keypom operates on the basis of NEARโ€™s unique [access key model](https://docs.near.org/concepts/basics/accounts/access-keys) which allows for much more flexibility in the end user-experience. With Keypom, you give the user a special type of access key that can be turned into a wallet. This key can be embedded within a simple Web2 style link that, once clicked, will allow them to input a desired account ID to be created. + +The immediate benefit of this approach is that it allows the end-user to *customize their wallet with a name of their choosing* as opposed to being given a pre-created account. + +### Sending Assets with Keypom +One of the simplest ways to onboard a user into the NEAR ecosystem is to use the Keypom protocol to create a link and load it with $NEAR and other assets. Behind the scenes, the protocol will associate the access key (embedded within the link) to the specified amount of $NEAR. Anyone who has the link can then gain access to the funds. + +These funds can be used to either create an entirely new named account, or can be sent to an existing wallet if the user already has one. + +The concept of sending NEAR can then be expanded to allow someone to not only load a link with native $NEAR, but also with Fungible Tokens and Non-Fungible Tokens as well. + +The end user journey would be that an organization or funder deposits assets (either fungible or non-fungible) into the Keypom contract and generates a unique link. This link is then given to the user that wishes to onboard onto NEAR. When the link is clicked, the user either creates a new account or uses an existing one for the assets to be automatically sent to. + +In the NEAR ecosystem, this process is known as a linkdrop. With Keypom, a series of identical linkdrops can be created at once and is referred to as **a drop**. + +### Customizable Linkdrops +The Keypom Protocol allows for a huge variety of customizations that can be embedded into the onboarding experience. For example, as the funder, you can specify the amount of times a link can be used before itโ€™s invalidated. Rather than someone using a link once, they can potentially use it many times and receive assets over a long period of time. + +### Function Calls with Keypom +The Keypom Protocol can also be used to execute predefined function calls on smart contracts when a link is used. For example, you could create a link that, when claimed, will automatically call a function to register the user into a DAO. This simple idea carries many powerful use-cases that, when paired with the customizable configurations and multi-use links, can create truly immersive and amazing onboarding experiences. + +Learn more about Keypom's Drop types below + +
+
+
+ +
+
+

Simple Drop

+

Onboarding with $NEAR.

+
+
+ +
+
+ +
+
+

Non-Fungible Token Drops

+

Share an NFT with a link

+
+
+ +
+
+
+
+ +
+
+

Fungible Token Drop

+

Send users FTs

+
+
+ +
+
+ +
+
+

Function Call Drops

+

Onboard with Keypom's most powerful drop

+
+
+ +
+
+
+ +## Use Cases + +Here are just a few of the possibilities with Keypom + +### NFT Ticketing +The problem with current NFT ticketing systems is that they require users to have a wallet. This is a huge barrier to entry for people that are attending events but donโ€™t have wallets. In addition, there is often no proof of attendance for the event as the NFT is burned in order to get into the event which requires an internet connection. + +Keypom aims to solve these problems by having a ticketing system that has the following features. + +* Users are not required to have a wallet to enter the event. +* Each ticket is unique and can only be used by one person. +* Attendees are not required to have wifi to gain entry to the event. +* Attendees that did not have a NEAR wallet can get one for free. +* Attendees can choose to receive an NFT proving their attendance at the event. This is commonly known as a [POAP](https://academy.binance.com/en/glossary/proof-of-attendance-protocol-poap). + + +In addition, some way to provide analytics to event organizers that contains information such as links that were: +* Given out but not clicked at all. +* Clicked but not attended. +* Partially claimed indicating the number of people that attended but did not onboard or receive a POAP. +* Fully claimed indicating the number of people that attended and received a POAP. + +### Recurring Payments/Subscriptions +Recurring payments are quite a common situation. Letโ€™s say you need to send someone $50 USDC every week. You could create a key with 5 claims that has a throttle_timestamp of 1 week. You would then pre-load maybe the first weekโ€™s deposit of $50 USDC and register 1 use or you could send $500 USDC for the first 10 weeks. At that point, you would simply hand over the key to the user and they can claim once a week. + + +### Auto-Registration in to DAOs +DAOs are a raging topic in crypto. The problem with DAOs, however, is there is a barrier to entry for users that arenโ€™t familiar with the specific chain theyโ€™re built on top of. Users might not have wallets or understand how to interact with contracts. On the contrary, they might be very well versed or immersed in the DAOโ€™s topics. They shouldnโ€™t be required to create a wallet and learn the onboarding process. + +With Keypom, you can create a function call drop with the main purpose of registering users into a DAO. For people that have a wallet, this will act as an easy way of registering them with the click of a link. For users that donโ€™t have a wallet and are unfamiliar with NEAR, they can be onboarded and registered into the DAO with the same click of a link. + diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/_category_.yml b/versioned_docs/version-2.0/keypom-sdk/Core/_category_.yml new file mode 100644 index 00000000..5893a319 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/_category_.yml @@ -0,0 +1,3 @@ +label: "Core TypeDocs" +position: 0 +collapsed: false \ No newline at end of file diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/BasicTransaction.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/BasicTransaction.md new file mode 100644 index 00000000..b537263c --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/BasicTransaction.md @@ -0,0 +1,37 @@ +--- +id: "BasicTransaction" +title: "Interface: BasicTransaction" +sidebar_label: "BasicTransaction" +sidebar_position: 0 +custom_edit_url: null +--- + +## Properties + +### actions + + **actions**: `Action`[] + +#### Defined in + +[lib/types/general.ts:108](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L108) + +___ + +### receiverId + + **receiverId**: `string` + +#### Defined in + +[lib/types/general.ts:106](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L106) + +___ + +### signerId + + **signerId**: `string` + +#### Defined in + +[lib/types/general.ts:107](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L107) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ContractSourceMetadata.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ContractSourceMetadata.md new file mode 100644 index 00000000..0656191a --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ContractSourceMetadata.md @@ -0,0 +1,34 @@ +--- +id: "ContractSourceMetadata" +title: "Interface: ContractSourceMetadata" +sidebar_label: "ContractSourceMetadata" +sidebar_position: 0 +custom_edit_url: null +--- + +Information returned from `getContractSourceMetadata` about the deployed Keypom contract. This is part of [NEP-330](https://nomicon.io/Standards/SourceMetadata) and +can allow you to view exactly what code is deployed to the contract. + +## Properties + +### link + + **link**: `string` + +Link to the specific commit and code on GitHub that is deployed to the Keypom account + +#### Defined in + +[lib/types/general.ts:102](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L102) + +___ + +### version + + **version**: `string` + +Versioning used by the Keypom developers to indicate which version of the contract is deployed. + +#### Defined in + +[lib/types/general.ts:100](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L100) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/CreateDropProtocolArgs.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/CreateDropProtocolArgs.md new file mode 100644 index 00000000..46659a70 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/CreateDropProtocolArgs.md @@ -0,0 +1,117 @@ +--- +id: "CreateDropProtocolArgs" +title: "Interface: CreateDropProtocolArgs" +sidebar_label: "CreateDropProtocolArgs" +sidebar_position: 0 +custom_edit_url: null +--- + +## Properties + +### config + + `Optional` **config**: [`ProtocolReturnedDropConfig`](ProtocolReturnedDropConfig.md) + +#### Defined in + +[lib/types/params.ts:54](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L54) + +___ + +### deposit\_per\_use + + **deposit\_per\_use**: `string` + +#### Defined in + +[lib/types/params.ts:51](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L51) + +___ + +### drop\_id + + `Optional` **drop\_id**: `string` + +#### Defined in + +[lib/types/params.ts:53](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L53) + +___ + +### fc + + `Optional` **fc**: [`ProtocolReturnedFCData`](ProtocolReturnedFCData.md) + +#### Defined in + +[lib/types/params.ts:60](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L60) + +___ + +### ft + + `Optional` **ft**: [`ProtocolReturnedFTData`](ProtocolReturnedFTData.md) + +#### Defined in + +[lib/types/params.ts:58](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L58) + +___ + +### metadata + + `Optional` **metadata**: `string` + +#### Defined in + +[lib/types/params.ts:55](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L55) + +___ + +### nft + + `Optional` **nft**: [`ProtocolReturnedNFTData`](ProtocolReturnedNFTData.md) + +#### Defined in + +[lib/types/params.ts:59](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L59) + +___ + +### passwords\_per\_use + + `Optional` **passwords\_per\_use**: [`PasswordPerUse`](PasswordPerUse.md)[][] + +#### Defined in + +[lib/types/params.ts:61](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L61) + +___ + +### public\_keys + + `Optional` **public\_keys**: `string`[] + +#### Defined in + +[lib/types/params.ts:50](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L50) + +___ + +### required\_gas + + `Optional` **required\_gas**: `string` + +#### Defined in + +[lib/types/params.ts:56](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L56) + +___ + +### simple + + `Optional` **simple**: [`ProtocolReturnedSimpleData`](ProtocolReturnedSimpleData.md) + +#### Defined in + +[lib/types/params.ts:57](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L57) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/CreateOrAddReturn.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/CreateOrAddReturn.md new file mode 100644 index 00000000..ae461116 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/CreateOrAddReturn.md @@ -0,0 +1,69 @@ +--- +id: "CreateOrAddReturn" +title: "Interface: CreateOrAddReturn" +sidebar_label: "CreateOrAddReturn" +sidebar_position: 0 +custom_edit_url: null +--- + +Information returned when creating a drop or adding keys via `createDrop` and `addKeys` respectively. + +## Properties + +### dropId + + **dropId**: `string` + +The drop ID for the drop that is being interacted with. + +#### Defined in + +[lib/types/params.ts:34](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L34) + +___ + +### keys + + `Optional` **keys**: [`GeneratedKeyPairs`](GeneratedKeyPairs.md) + +Any keys that were automatically generated. + +#### Defined in + +[lib/types/params.ts:32](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L32) + +___ + +### requiredDeposit + + `Optional` **requiredDeposit**: `string` + +The required deposit that should be attached to the transaction. + +#### Defined in + +[lib/types/params.ts:30](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L30) + +___ + +### responses + + `Optional` **responses**: `any` + +The responses to any transactions that were signed and sent to the network. + +#### Defined in + +[lib/types/params.ts:26](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L26) + +___ + +### transactions + + `Optional` **transactions**: `Transaction`[] + +Information about the transactions if `returnTransactions` is specified in the arguments. This will result in the information being returned instead of signed and sent. + +#### Defined in + +[lib/types/params.ts:28](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L28) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/Drop.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/Drop.md new file mode 100644 index 00000000..c1547b53 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/Drop.md @@ -0,0 +1,153 @@ +--- +id: "Drop" +title: "Interface: Drop" +sidebar_label: "Drop" +sidebar_position: 0 +custom_edit_url: null +--- + +Information related to a specific drop. + +## Properties + +### config + + `Optional` **config**: [`DropConfig`](DropConfig.md) + +All drops regardless of their type can have a suite of configurations such as how many uses each key has or how often a key can be used. + +#### Defined in + +[lib/types/drops.ts:50](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L50) + +___ + +### depositPerUse + + **depositPerUse**: `string` + +How much $yoctoNEAR will be transferred anytime a key is used that is part of this drop. + +#### Defined in + +[lib/types/drops.ts:40](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L40) + +___ + +### dropId + + **dropId**: `string` + +Drop ID for this specific drop. + +#### Defined in + +[lib/types/drops.ts:36](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L36) + +___ + +### fc + + `Optional` **fc**: [`FCData`](FCData.md) + +For Function-Call drops, important information needs to be stored such as which methods, the attached deposit, args etc. + +#### Defined in + +[lib/types/drops.ts:48](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L48) + +___ + +### ft + + `Optional` **ft**: [`FTData`](FTData.md) + +For Fungible Token drops, important information such as the amount of tokens to transfer, or contract need to be stored. + +#### Defined in + +[lib/types/drops.ts:46](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L46) + +___ + +### metadata + + `Optional` **metadata**: `string` + +Any extra information about the drop can be stored as metadata. This is up to the drop creator and can be stringified JSON, or any other string. + +#### Defined in + +[lib/types/drops.ts:52](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L52) + +___ + +### nextKeyId + + **nextKeyId**: `number` + +What is the next unique ID that will be given to the next access key added to this drop. + +#### Defined in + +[lib/types/drops.ts:58](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L58) + +___ + +### nft + + `Optional` **nft**: [`NFTData`](NFTData.md) + +For NFT drops, important information such as the token IDs, or contract need to be stored. + +#### Defined in + +[lib/types/drops.ts:44](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L44) + +___ + +### ownerId + + **ownerId**: `string` + +Which account created this drop. + +#### Defined in + +[lib/types/drops.ts:38](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L38) + +___ + +### registeredUses + + **registeredUses**: `number` + +How many key uses are registered for this drop? This is only applicable to simple drops with lazy registrations, FT drops, and NFT drops. + +#### Defined in + +[lib/types/drops.ts:54](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L54) + +___ + +### requiredGas + + **requiredGas**: `string` + +In order to use an access key that's part of this drop, how much Gas *needs* to be attached to the call? + +#### Defined in + +[lib/types/drops.ts:56](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L56) + +___ + +### simple + + `Optional` **simple**: [`SimpleData`](SimpleData.md) + +For simple drops, there are specific, optional configurations. + +#### Defined in + +[lib/types/drops.ts:42](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L42) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/DropConfig.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/DropConfig.md new file mode 100644 index 00000000..99aad8cd --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/DropConfig.md @@ -0,0 +1,71 @@ +--- +id: "DropConfig" +title: "Interface: DropConfig" +sidebar_label: "DropConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Configurable options for any drop regardless of type. + +## Properties + +### dropRoot + + `Optional` **dropRoot**: `string` + +Override the global root account that all created sub-accounts will have (currently `near` or `testnet`). This allows users to drops that have a custom root. +For example, Fayyr could specify a root of `fayyr.near` By which all sub-accounts will then be `ACCOUNT.fayyr.near`. +It's important to note that this root account *MUST* have a smart contract deployed that has a method `create_account`. + +#### Defined in + +[lib/types/drops.ts:81](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L81) + +___ + +### sale + + `Optional` **sale**: [`PublicSaleConfig`](PublicSaleConfig.md) + +Any information related to primary market sales for access keys added to this drop. + +#### Defined in + +[lib/types/drops.ts:75](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L75) + +___ + +### time + + `Optional` **time**: [`TimeConfig`](TimeConfig.md) + +Any information related to time-based configurations such as a starting date for keys etc. + +#### Defined in + +[lib/types/drops.ts:69](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L69) + +___ + +### usage + + `Optional` **usage**: [`UsageConfig`](UsageConfig.md) + +Any information related to how access keys are used such as which methods they can call or whether an empty drop should be automatically deleted etc. + +#### Defined in + +[lib/types/drops.ts:72](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L72) + +___ + +### usesPerKey + + `Optional` **usesPerKey**: `number` + +How many uses can each key have before it's deleted. If this isn't specified, it defaults to 1 use per key. + +#### Defined in + +[lib/types/drops.ts:66](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L66) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/EnvVars.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/EnvVars.md new file mode 100644 index 00000000..5a17a087 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/EnvVars.md @@ -0,0 +1,223 @@ +--- +id: "EnvVars" +title: "Interface: EnvVars" +sidebar_label: "EnvVars" +sidebar_position: 0 +custom_edit_url: null +--- + +Important context that is used throughout the SDK. This is generated when `initKeypom` is called and can be retrieved by calling `useKeypom`. +All parameters will start off as undefined until the Keypom SDK is initialized. + +## Properties + +### attachedGas + + `Optional` **attachedGas**: `string` + +The amount of Gas that will be attached to the `claim` and `create_account_and_claim` functions for claiming linkdrops (100 TGas). + +#### Defined in + +[lib/types/general.ts:77](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L77) + +___ + +### connection + + `Optional` **connection**: `Connection` + +The connection instance that is part of the NEAR object + +#### Defined in + +[lib/types/general.ts:59](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L59) + +___ + +### contractAccount + + `Optional` **contractAccount**: `Account` + +The NEAR Account object for the Keypom contract being used. This lets you know the account ID for the contract and can be used to sign transactions for claiming linkdrops. + +#### Defined in + +[lib/types/general.ts:69](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L69) + +___ + +### contractId + + `Optional` **contractId**: `string` + +The account ID where the Keypom contract is deployed to. + +#### Defined in + +[lib/types/general.ts:79](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L79) + +___ + +### error + + `Optional` **error**: `string` + +#### Defined in + +[lib/types/general.ts:83](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L83) + +___ + +### execute + + `Optional` **execute**: `any` + +#### Defined in + +[lib/types/general.ts:87](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L87) + +___ + +### fundingAccount + + `Optional` **fundingAccount**: `Account` + +The NEAR Account object for the Funder + +#### Defined in + +[lib/types/general.ts:65](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L65) + +___ + +### fundingAccountDetails + + `Optional` **fundingAccountDetails**: [`Funder`](Funder.md) + +The details for the funder such as any `rootEntropy` or their `secretKey` etc. + +#### Defined in + +[lib/types/general.ts:67](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L67) + +___ + +### gas + + `Optional` **gas**: `string` + +The default amount of Gas that will be attached to transactions (200 TGas). + +#### Defined in + +[lib/types/general.ts:73](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L73) + +___ + +### gas300 + + `Optional` **gas300**: `string` + +The max amount of Gas that will be attached to transactions (300 TGas). + +#### Defined in + +[lib/types/general.ts:75](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L75) + +___ + +### getAccount + + `Optional` **getAccount**: `any` + +#### Defined in + +[lib/types/general.ts:85](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L85) + +___ + +### keyStore + + `Optional` **keyStore**: `KeyStore` + +Which type of KeyStore is used when locating keys and signing transactions throughout the SDK (In Memory, Unencrypted FileStore etc.) + +#### Defined in + +[lib/types/general.ts:61](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L61) + +___ + +### near + + `Optional` **near**: `Near` + +The specific NEAR object that contains important information such as the KeyStore and connection. This is used to interact with the chain and can either be manually passed in or will be automatically created during `initKeypom` + +#### Defined in + +[lib/types/general.ts:57](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L57) + +___ + +### networkId + + `Optional` **networkId**: `string` + +What network is the SDK using (`testnet` or `mainnet`) + +#### Defined in + +[lib/types/general.ts:63](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L63) + +___ + +### receiverId + + `Optional` **receiverId**: `string` + +#### Defined in + +[lib/types/general.ts:81](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L81) + +___ + +### supportedKeypomContracts + + `Optional` **supportedKeypomContracts**: `Object` + +Object containing the supported Keypom contracts for both mainnet and testnet + +#### Type declaration + +| Name | Type | +| :------ | :------ | +| `mainnet` | {} | +| `testnet` | {} | + +#### Defined in + +[lib/types/general.ts:89](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L89) + +___ + +### viewAccount + + `Optional` **viewAccount**: `any` + +#### Defined in + +[lib/types/general.ts:71](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L71) + +___ + +### viewCall + + `Optional` **viewCall**: `any` + +Function that allows you to invoke a view method. This takes in a `receiverId`, `methodName`, and `args`. + +#### Defined in + +[lib/types/general.ts:91](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L91) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/FCData.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/FCData.md new file mode 100644 index 00000000..82846117 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/FCData.md @@ -0,0 +1,22 @@ +--- +id: "FCData" +title: "Interface: FCData" +sidebar_label: "FCData" +sidebar_position: 0 +custom_edit_url: null +--- + +Information pertaining to all Function-Call drops. This should be passed in if the drop will be a Function-Call drop. + +## Properties + +### methods + + **methods**: [`Method`](Method.md)[][] + +The top level array indicates a different set of methods that can be called for every key use. It is possible that for a given key use, no methods are called thus acting as a "free" key use whereby the use is reflected on-chain but no assets are transferred. +If a given key use does not have an undefined set of methods, when it is used, all the methods in the set will be called. + +#### Defined in + +[lib/types/fc.ts:73](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/fc.ts#L73) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/FTData.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/FTData.md new file mode 100644 index 00000000..e38ebbaa --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/FTData.md @@ -0,0 +1,59 @@ +--- +id: "FTData" +title: "Interface: FTData" +sidebar_label: "FTData" +sidebar_position: 0 +custom_edit_url: null +--- + +Information pertaining to all Fungible-Token drops. This should be passed in if the drop will be used to transfer any fungible tokens. + +## Properties + +### absoluteAmount + + `Optional` **absoluteAmount**: `string` + +Amount of tokens to transfer but considering the decimal amount. +Example: transferring one wNEAR should be passed in as "1000000000000000000000000" and NOT "1" + +#### Defined in + +[lib/types/ft.ts:22](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/ft.ts#L22) + +___ + +### amount + + `Optional` **amount**: `string` + +Human readable format for the amount of tokens to transfer every time the FT key is used. +Example: transferring one wNEAR should be passed in as "1" and NOT "1000000000000000000000000" + +#### Defined in + +[lib/types/ft.ts:17](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/ft.ts#L17) + +___ + +### contractId + + **contractId**: `string` + +Which contract do the FTs belong to? + +#### Defined in + +[lib/types/ft.ts:8](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/ft.ts#L8) + +___ + +### senderId + + `Optional` **senderId**: `string` + +By default, anyone can fund your drop with FTs. This field allows you to set a specific account ID that will be locked into sending the FTs. + +#### Defined in + +[lib/types/ft.ts:12](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/ft.ts#L12) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/Funder.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/Funder.md new file mode 100644 index 00000000..a3cb4015 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/Funder.md @@ -0,0 +1,75 @@ +--- +id: "Funder" +title: "Interface: Funder" +sidebar_label: "Funder" +sidebar_position: 0 +custom_edit_url: null +--- + +Outlines how the structure of the *funder* object should be passed into `initKeypom` or `updateFunder`. This contains important information such as the +secret key, account ID and any root entropy associated with the account. + +**`Throws`** + +if neither `secretKey` or `seedPhrase` are provided. One of these need to be passed in. + +## Properties + +### accountId + + **accountId**: `string` + +The account ID of the funder that will be used to sign transactions. + +#### Defined in + +[lib/types/general.ts:35](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L35) + +___ + +### fundingKeyPair + + `Optional` **fundingKeyPair**: `KeyPair` + +#### Defined in + +[lib/types/general.ts:48](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L48) + +___ + +### rootEntropy + + `Optional` **rootEntropy**: `string` + +When interacting with the SDK, there are several places where KeyPairs can be generated automatically rather than you having to pass them in. +For example, during `createDrop` and `addKeys`, if `publicKeys` isn't passed in, the SDK will generate `numKeys` number of keys automatically. +These generated keys can either be completely random or deterministically generated based off some entropy. If `rootEntropy` is provided, all the +keys that are auto-generated will be based off this entropy. + +#### Defined in + +[lib/types/general.ts:46](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L46) + +___ + +### secretKey + + `Optional` **secretKey**: `string` + +A valid private key associated with the funder's account. This can be function-call or full access (depending on what limitations and security measures are in place). + +#### Defined in + +[lib/types/general.ts:37](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L37) + +___ + +### seedPhrase + + `Optional` **seedPhrase**: `string` + +12 word seedphrase that can be used to derive the `secretKey`. If this is present, it will override the passed in `secretKey`. + +#### Defined in + +[lib/types/general.ts:39](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L39) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/FungibleTokenMetadata.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/FungibleTokenMetadata.md new file mode 100644 index 00000000..c69b3456 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/FungibleTokenMetadata.md @@ -0,0 +1,96 @@ +--- +id: "FungibleTokenMetadata" +title: "Interface: FungibleTokenMetadata" +sidebar_label: "FungibleTokenMetadata" +sidebar_position: 0 +custom_edit_url: null +--- + +General structure of Fungible Token Metadata as per official NEP-148 standard (https://github.com/near/NEPs/blob/master/neps/nep-0148.md). + +## Properties + +### decimals + + **decimals**: `number` + +Used in frontends to show the proper significant digits of a token. This concept is explained well in this OpenZeppelin post (https://docs.openzeppelin.com/contracts/3.x/erc20#a-note-on-decimals). + +#### Defined in + +[lib/types/ft.ts:36](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/ft.ts#L36) + +___ + +### icon + + `Optional` **icon**: `string` + +A small image associated with this token. Must be a data URL, to help consumers display it quickly while protecting user data. +Recommendation: use optimized SVG, which can result in high-resolution images with only 100s of bytes of storage cost. +(Note that these storage costs are incurred to the token owner/deployer, but that querying these icons is a very cheap & cacheable read operation for all consumers of the contract and the RPC nodes that serve the data.) +Recommendation: create icons that will work well with both light-mode and dark-mode websites by either using middle-tone color schemes, or by embedding media queries in the SVG. + +#### Defined in + +[lib/types/ft.ts:43](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/ft.ts#L43) + +___ + +### name + + **name**: `string` + +The human-readable name of the token. + +#### Defined in + +[lib/types/ft.ts:32](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/ft.ts#L32) + +___ + +### reference + + `Optional` **reference**: `string` + +A link to a valid JSON file containing various keys offering supplementary details on the token. Example: /ipfs/QmdmQXB2mzChmMeKY47C43LxUdg1NDJ5MWcKMKxDu7RgQm, https://example.com/token.json, etc. If the information given in this document conflicts with the on-chain attributes, the values in reference shall be considered the source of truth. + +#### Defined in + +[lib/types/ft.ts:45](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/ft.ts#L45) + +___ + +### reference\_hash + + `Optional` **reference\_hash**: `string` + +The base64-encoded sha256 hash of the JSON file contained in the reference field. This is to guard against off-chain tampering. + +#### Defined in + +[lib/types/ft.ts:47](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/ft.ts#L47) + +___ + +### spec + + **spec**: `string` + +A string. Should be ft-1.0.0 to indicate that a Fungible Token contract adheres to the current versions of this Metadata and the Fungible Token Core specs. This will allow consumers of the Fungible Token to know if they support the features of a given contract. + +#### Defined in + +[lib/types/ft.ts:30](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/ft.ts#L30) + +___ + +### symbol + + **symbol**: `string` + +The abbreviation, like wETH or AMPL. + +#### Defined in + +[lib/types/ft.ts:34](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/ft.ts#L34) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/GeneratedKeyPairs.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/GeneratedKeyPairs.md new file mode 100644 index 00000000..505479f3 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/GeneratedKeyPairs.md @@ -0,0 +1,46 @@ +--- +id: "GeneratedKeyPairs" +title: "Interface: GeneratedKeyPairs" +sidebar_label: "GeneratedKeyPairs" +sidebar_position: 0 +custom_edit_url: null +--- + +For each generated KeyPair (either through `createDrop`, `addKeys` or `generateKeys`), the public and private keys are returned. +In addition, the actual KeyPair objects are returned as well. + +## Properties + +### keyPairs + + **keyPairs**: `KeyPair`[] + +Actual KeyPair objects that can be used to sign messages, verify signatures, and get the public and private keys + +#### Defined in + +[lib/types/general.ts:20](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L20) + +___ + +### publicKeys + + **publicKeys**: `string`[] + +Set of public keys that were generated + +#### Defined in + +[lib/types/general.ts:22](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L22) + +___ + +### secretKeys + + **secretKeys**: `string`[] + +Set of private keys that were generated + +#### Defined in + +[lib/types/general.ts:24](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L24) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/KeyInfo.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/KeyInfo.md new file mode 100644 index 00000000..a84ca835 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/KeyInfo.md @@ -0,0 +1,93 @@ +--- +id: "KeyInfo" +title: "Interface: KeyInfo" +sidebar_label: "KeyInfo" +sidebar_position: 0 +custom_edit_url: null +--- + +Important information returned in many view calls regarding a specific access key. + +## Properties + +### allowance + + **allowance**: `number` + +How much allowance does the key have left (measured in $yoctoNEAR). When the key is deleted, this is refunded to the funder's balance. + +#### Defined in + +[lib/types/drops.ts:25](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L25) + +___ + +### curKeyUse + + **curKeyUse**: `number` + +Which use is the key currently on? For single-use keys, this is always 1. + +#### Defined in + +[lib/types/drops.ts:16](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L16) + +___ + +### dropId + + **dropId**: `string` + +Drop ID for the specific drop that the key belongs to. + +#### Defined in + +[lib/types/drops.ts:11](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L11) + +___ + +### keyId + + **keyId**: `number` + +The unique ID associated to this key. IDs are *not* unique across drops but they are unique for any key in the drop. + +#### Defined in + +[lib/types/drops.ts:28](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L28) + +___ + +### lastUsed + + **lastUsed**: `number` + +At what timestamp was the key last used? Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:22](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L22) + +___ + +### publicKey + + **publicKey**: `string` + +Public key for this access key. + +#### Defined in + +[lib/types/drops.ts:13](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L13) + +___ + +### remainingUses + + **remainingUses**: `number` + +How many uses this key has left before it's deleted. + +#### Defined in + +[lib/types/drops.ts:19](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L19) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/Method.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/Method.md new file mode 100644 index 00000000..bd31581d --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/Method.md @@ -0,0 +1,153 @@ +--- +id: "Method" +title: "Interface: Method" +sidebar_label: "Method" +sidebar_position: 0 +custom_edit_url: null +--- + +Outlines the information needed for any given method as part of a Function-Call drop. +Each individual key use can have an array of Methods that can be called. + +## Properties + +### accountIdField + + `Optional` **accountIdField**: `string` + +Specifies what field Keypom should auto-inject the account that claimed the drop's ID into when calling the function. +As an example, if the methodName was `nft_mint` and it expected a field `receiver_id` to be passed in, indicating who should receive the token, then the `accountIdField` would be `receiver_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/fc.ts:34](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/fc.ts#L34) + +___ + +### args + + **args**: `string` + +What arguments should be passed to the method. This should be in stringified JSON. + +#### Defined in + +[lib/types/fc.ts:19](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/fc.ts#L19) + +___ + +### attachedDeposit + + **attachedDeposit**: `string` + +How much yoctoNEAR should be attached to the call. + +#### Defined in + +[lib/types/fc.ts:23](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/fc.ts#L23) + +___ + +### attachedGas + + `Optional` **attachedGas**: `string` + +How much gas to attach to this method call. If none, all the gas is split between the parallel method calls in a given claim. +If this is specified, the key can ONLY be used to call `claim` and no `deposit_per_use` can be specified. This leads the key to act like a method calling proxy instead of a linkdrop. + +#### Defined in + +[lib/types/fc.ts:28](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/fc.ts#L28) + +___ + +### dropIdField + + `Optional` **dropIdField**: `string` + +Specifies what field Keypom should auto-inject the drops ID into when calling the function. +As an example, if an NFT contract expected the Keypom drop ID to be passed in as the field `keypom_drop_id` in order to gate access to who can mint NFTs, then the `dropIdField` would be `keypom_drop_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/fc.ts:40](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/fc.ts#L40) + +___ + +### funderIdField + + `Optional` **funderIdField**: `string` + +Specifies what field Keypom should auto-inject the drop funder's account ID into when calling the function. +As an example, if an NFT contract wanted to gate only users that had a key coming from a specific funder's drops, it could expect a field called `keypom_funder_id` and the `funderIdField` would be `keypom_funder_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/fc.ts:52](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/fc.ts#L52) + +___ + +### keyIdField + + `Optional` **keyIdField**: `string` + +Specifies what field Keypom should auto-inject the key's ID into when calling the function. +As an example, if an NFT contract wanted to gate only users with an odd key ID to be able to mint an NFT and their parameter was called `keypom_key_id`, then the `keyIdField` would be `keypom_key_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/fc.ts:46](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/fc.ts#L46) + +___ + +### methodName + + **methodName**: `string` + +The method that should be invoked on the `receiverId`'s contract. + +#### Defined in + +[lib/types/fc.ts:15](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/fc.ts#L15) + +___ + +### receiverId + + **receiverId**: `string` + +The account ID that the contract is deployed to that the method will be called on. + +#### Defined in + +[lib/types/fc.ts:11](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/fc.ts#L11) + +___ + +### receiverToClaimer + + `Optional` **receiverToClaimer**: `boolean` + +If set to true, the claiming account ID will be the receiver ID of the method call. +This receiver must be a valid account and non-malicious (cannot be set to the keypom contract) + +#### Defined in + +[lib/types/fc.ts:57](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/fc.ts#L57) + +___ + +### userArgsRule + + `Optional` **userArgsRule**: ``"AllUser"`` \| ``"FunderPreferred"`` \| ``"UserPreferred"`` + +What permissions does the user have when providing custom arguments to the function call? +By default, the user cannot provide any custom arguments + +#### Defined in + +[lib/types/fc.ts:62](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/fc.ts#L62) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/NFTData.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/NFTData.md new file mode 100644 index 00000000..61f9000c --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/NFTData.md @@ -0,0 +1,47 @@ +--- +id: "NFTData" +title: "Interface: NFTData" +sidebar_label: "NFTData" +sidebar_position: 0 +custom_edit_url: null +--- + +General structure of a Non-Fungible Token drop. This should be passed into `createDrop` if you wish to have an NFT drop. + +## Properties + +### contractId + + **contractId**: `string` + +The account ID that the NFT contract is deployed to. This contract is where all the NFTs for the specific drop must come from. + +#### Defined in + +[lib/types/nft.ts:6](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L6) + +___ + +### senderId + + `Optional` **senderId**: `string` + +By default, anyone can fund your drop with NFTs. This field allows you to set a specific account ID that will be locked into sending the NFTs. + +#### Defined in + +[lib/types/nft.ts:8](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L8) + +___ + +### tokenIds + + `Optional` **tokenIds**: `string`[] + +If there are any token IDs that you wish to be automatically sent to the Keypom contract in order to register keys as part of `createDrop`, specify them here. +A maximum of 2 token IDs can be sent as part of the transaction. If you wish to register more keys by sending more NFTs, you must do this in a separate call by invoking +the `nftTransferCall` method separately. + +#### Defined in + +[lib/types/nft.ts:14](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L14) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/NonFungibleTokenMetadata.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/NonFungibleTokenMetadata.md new file mode 100644 index 00000000..fdd4d598 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/NonFungibleTokenMetadata.md @@ -0,0 +1,153 @@ +--- +id: "NonFungibleTokenMetadata" +title: "Interface: NonFungibleTokenMetadata" +sidebar_label: "NonFungibleTokenMetadata" +sidebar_position: 0 +custom_edit_url: null +--- + +General structure of Non-Fungible Token Metadata (in camelCase) as per official NEP-177 standard (https://github.com/near/NEPs/blob/master/neps/nep-0177.md). + +## Properties + +### copies + + `Optional` **copies**: `number` + +number of copies of this set of metadata in existence when token was minted. + +#### Defined in + +[lib/types/nft.ts:76](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L76) + +___ + +### description + + `Optional` **description**: `string` + +free-form description + +#### Defined in + +[lib/types/nft.ts:70](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L70) + +___ + +### expiresAt + + `Optional` **expiresAt**: `number` + +When token expires, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:80](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L80) + +___ + +### extra + + `Optional` **extra**: `string` + +anything extra the NFT wants to store on-chain. Can be stringified JSON. + +#### Defined in + +[lib/types/nft.ts:86](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L86) + +___ + +### issuedAt + + `Optional` **issuedAt**: `number` + +When token was issued or minted, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:78](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L78) + +___ + +### media + + `Optional` **media**: `string` + +URL to associated media, preferably to decentralized, content-addressed storage + +#### Defined in + +[lib/types/nft.ts:72](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L72) + +___ + +### mediaHash + + `Optional` **mediaHash**: `string` + +Base64-encoded sha256 hash of content referenced by the `media` field. Required if `media` is included. + +#### Defined in + +[lib/types/nft.ts:74](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L74) + +___ + +### reference + + `Optional` **reference**: `string` + +URL to an off-chain JSON file with more info. + +#### Defined in + +[lib/types/nft.ts:88](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L88) + +___ + +### referenceHash + + `Optional` **referenceHash**: `string` + +Base64-encoded sha256 hash of JSON from reference field. Required if `reference` is included. + +#### Defined in + +[lib/types/nft.ts:90](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L90) + +___ + +### startsAt + + `Optional` **startsAt**: `number` + +When token starts being valid, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:82](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L82) + +___ + +### title + + `Optional` **title**: `string` + +ex. "Arch Nemesis: Mail Carrier" or "Parcel #5055" + +#### Defined in + +[lib/types/nft.ts:68](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L68) + +___ + +### updatedAt + + `Optional` **updatedAt**: `number` + +When token was last updated, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:84](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L84) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/PasswordPerUse.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/PasswordPerUse.md new file mode 100644 index 00000000..ea683acb --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/PasswordPerUse.md @@ -0,0 +1,33 @@ +--- +id: "PasswordPerUse" +title: "Interface: PasswordPerUse" +sidebar_label: "PasswordPerUse" +sidebar_position: 0 +custom_edit_url: null +--- + +Keeps track of the password for a given key use. This should be passed in as an array for each key that has passwords. + +## Properties + +### key\_use + + **key\_use**: `number` + +Which use does the password belong to? These uses are *NOT* zero-indexed so the first use corresponds to `1` not `0`. + +#### Defined in + +[lib/types/drops.ts:196](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L196) + +___ + +### pw + + **pw**: `string` + +The password for this given use + +#### Defined in + +[lib/types/drops.ts:194](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L194) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedDrop.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedDrop.md new file mode 100644 index 00000000..608829a3 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedDrop.md @@ -0,0 +1,166 @@ +--- +id: "ProtocolReturnedDrop" +title: "Interface: ProtocolReturnedDrop" +sidebar_label: "ProtocolReturnedDrop" +sidebar_position: 0 +custom_edit_url: null +--- + +Drop information returned from the Protocol. This interface is exactly the same as the `Drop`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### config + + `Optional` **config**: [`ProtocolReturnedDropConfig`](ProtocolReturnedDropConfig.md) + +All drops regardless of their type can have a suite of configurations such as how many uses each key has or how often a key can be used. + +#### Defined in + +[lib/types/protocol.ts:49](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L49) + +___ + +### deposit\_per\_use + + **deposit\_per\_use**: `string` + +How much $yoctoNEAR will be transferred anytime a key is used that is part of this drop. + +#### Defined in + +[lib/types/protocol.ts:39](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L39) + +___ + +### drop\_id + + **drop\_id**: `string` + +Drop ID for this specific drop. + +#### Defined in + +[lib/types/protocol.ts:35](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L35) + +___ + +### fc + + `Optional` **fc**: [`ProtocolReturnedFCData`](ProtocolReturnedFCData.md) + +For Function-Call drops, important information needs to be stored such as which methods, the attached deposit, args etc. + +#### Defined in + +[lib/types/protocol.ts:47](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L47) + +___ + +### ft + + `Optional` **ft**: [`ProtocolReturnedFTData`](ProtocolReturnedFTData.md) + +For Fungible Token drops, important information such as the amount of tokens to transfer, or contract need to be stored. + +#### Defined in + +[lib/types/protocol.ts:45](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L45) + +___ + +### keys + + `Optional` **keys**: [`ProtocolReturnedKeyInfo`](ProtocolReturnedKeyInfo.md)[] + +If calling `getDrops` or `getDropInformation` and `withKeys` is passed in as true, an extra view call will be done to get a set of keys that are currently on the drop. + +#### Defined in + +[lib/types/protocol.ts:59](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L59) + +___ + +### metadata + + `Optional` **metadata**: `string` + +Any extra information about the drop can be stored as metadata. This is up to the drop creator and can be stringified JSON, or any other string. + +#### Defined in + +[lib/types/protocol.ts:51](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L51) + +___ + +### next\_key\_id + + **next\_key\_id**: `number` + +What is the next unique ID that will be given to the next access key added to this drop. + +#### Defined in + +[lib/types/protocol.ts:57](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L57) + +___ + +### nft + + `Optional` **nft**: [`ProtocolReturnedNFTData`](ProtocolReturnedNFTData.md) + +For NFT drops, important information such as the token IDs, or contract need to be stored. + +#### Defined in + +[lib/types/protocol.ts:43](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L43) + +___ + +### owner\_id + + **owner\_id**: `string` + +Which account created this drop. + +#### Defined in + +[lib/types/protocol.ts:37](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L37) + +___ + +### registered\_uses + + **registered\_uses**: `number` + +How many key uses are registered for this drop? This is only applicable to simple drops with lazy registrations, FT drops, and NFT drops. + +#### Defined in + +[lib/types/protocol.ts:53](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L53) + +___ + +### required\_gas + + **required\_gas**: `string` + +In order to use an access key that's part of this drop, how much Gas *needs* to be attached to the call? + +#### Defined in + +[lib/types/protocol.ts:55](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L55) + +___ + +### simple + + `Optional` **simple**: [`ProtocolReturnedSimpleData`](ProtocolReturnedSimpleData.md) + +For simple drops, there are specific, optional configurations. + +#### Defined in + +[lib/types/protocol.ts:41](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L41) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedDropConfig.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedDropConfig.md new file mode 100644 index 00000000..a43cfbfb --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedDropConfig.md @@ -0,0 +1,70 @@ +--- +id: "ProtocolReturnedDropConfig" +title: "Interface: ProtocolReturnedDropConfig" +sidebar_label: "ProtocolReturnedDropConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Drop config returned from the Protocol. This interface is exactly the same as the `DropConfig`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### root\_account\_id + + `Optional` **root\_account\_id**: `string` + +Override the global root account that all created sub-accounts will have (currently `near` or `testnet`). This allows users to drops that have a custom root. +For example, Fayyr could specify a root of `fayyr.near` By which all sub-accounts will then be `ACCOUNT.fayyr.near`. +It's important to note that this root account *MUST* have a smart contract deployed that has a method `create_account`. + +#### Defined in + +[lib/types/protocol.ts:83](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L83) + +___ + +### sale + + `Optional` **sale**: [`ProtocolReturnedPublicSaleConfig`](ProtocolReturnedPublicSaleConfig.md) + +#### Defined in + +[lib/types/protocol.ts:76](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L76) + +___ + +### time + + `Optional` **time**: [`ProtocolReturnedTimeConfig`](ProtocolReturnedTimeConfig.md) + +Any information related to time-based configurations such as a starting date for keys etc. + +#### Defined in + +[lib/types/protocol.ts:71](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L71) + +___ + +### usage + + `Optional` **usage**: [`ProtocolReturnedUsageConfig`](ProtocolReturnedUsageConfig.md) + +Any information related to how access keys are used such as which methods they can call or whether an empty drop should be automatically deleted etc. + +#### Defined in + +[lib/types/protocol.ts:74](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L74) + +___ + +### uses\_per\_key + + `Optional` **uses\_per\_key**: `number` + +How many uses can each key have before it's deleted. If this isn't specified, it defaults to 1 use per key. + +#### Defined in + +[lib/types/protocol.ts:68](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L68) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedFCData.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedFCData.md new file mode 100644 index 00000000..196082b7 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedFCData.md @@ -0,0 +1,23 @@ +--- +id: "ProtocolReturnedFCData" +title: "Interface: ProtocolReturnedFCData" +sidebar_label: "ProtocolReturnedFCData" +sidebar_position: 0 +custom_edit_url: null +--- + +FC Data returned from the Protocol. This interface is exactly the same as the `FCData`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### methods + + **methods**: [`ProtocolReturnedMethod`](ProtocolReturnedMethod.md)[][] + +The top level array indicates a different set of methods that can be called for every key use. It is possible that for a given key use, no methods are called thus acting as a "free" key use whereby the use is reflected on-chain but no assets are transferred. +If a given key use does not have an undefined set of methods, when it is used, all the methods in the set will be called. + +#### Defined in + +[lib/types/protocol.ts:300](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L300) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedFTData.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedFTData.md new file mode 100644 index 00000000..a83e62de --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedFTData.md @@ -0,0 +1,47 @@ +--- +id: "ProtocolReturnedFTData" +title: "Interface: ProtocolReturnedFTData" +sidebar_label: "ProtocolReturnedFTData" +sidebar_position: 0 +custom_edit_url: null +--- + +FT Data returned from the Protocol. This interface is exactly the same as the `FTData`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### balance\_per\_use + + `Optional` **balance\_per\_use**: `string` + +Amount of tokens to transfer but considering the decimal amount. +Example: transferring one wNEAR should be passed in as "1000000000000000000000000" and NOT "1" + +#### Defined in + +[lib/types/protocol.ts:226](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L226) + +___ + +### contract\_id + + **contract\_id**: `string` + +Which contract do the FTs belong to? + +#### Defined in + +[lib/types/protocol.ts:217](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L217) + +___ + +### sender\_id + + `Optional` **sender\_id**: `string` + +By default, anyone can fund your drop with FTs. This field allows you to set a specific account ID that will be locked into sending the FTs. + +#### Defined in + +[lib/types/protocol.ts:221](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L221) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedKeyInfo.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedKeyInfo.md new file mode 100644 index 00000000..17abcf50 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedKeyInfo.md @@ -0,0 +1,94 @@ +--- +id: "ProtocolReturnedKeyInfo" +title: "Interface: ProtocolReturnedKeyInfo" +sidebar_label: "ProtocolReturnedKeyInfo" +sidebar_position: 0 +custom_edit_url: null +--- + +Key information returned from the Protocol. This interface is exactly the same as the `KeyInfo`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### allowance + + **allowance**: `number` + +How much allowance does the key have left (measured in $yoctoNEAR). When the key is deleted, this is refunded to the funder's balance. + +#### Defined in + +[lib/types/protocol.ts:23](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L23) + +___ + +### cur\_key\_use + + **cur\_key\_use**: `number` + +Which use is the key currently on? For single-use keys, this is always 1. + +#### Defined in + +[lib/types/protocol.ts:14](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L14) + +___ + +### drop\_id + + **drop\_id**: `string` + +Drop ID for the specific drop that the key belongs to. + +#### Defined in + +[lib/types/protocol.ts:9](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L9) + +___ + +### key\_id + + **key\_id**: `number` + +The unique ID associated to this key. IDs are *not* unique across drops but they are unique for any key in the drop. + +#### Defined in + +[lib/types/protocol.ts:26](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L26) + +___ + +### last\_used + + **last\_used**: `number` + +At what timestamp was the key last used? Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:20](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L20) + +___ + +### public\_key + + **public\_key**: `string` + +Public key for this access key. + +#### Defined in + +[lib/types/protocol.ts:11](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L11) + +___ + +### remaining\_uses + + **remaining\_uses**: `number` + +How many uses this key has left before it's deleted. + +#### Defined in + +[lib/types/protocol.ts:17](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L17) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedMethod.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedMethod.md new file mode 100644 index 00000000..bb5a0e98 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedMethod.md @@ -0,0 +1,153 @@ +--- +id: "ProtocolReturnedMethod" +title: "Interface: ProtocolReturnedMethod" +sidebar_label: "ProtocolReturnedMethod" +sidebar_position: 0 +custom_edit_url: null +--- + +Method information returned from the Protocol. This interface is exactly the same as the `Method`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### account\_id\_field + + `Optional` **account\_id\_field**: `string` + +Specifies what field Keypom should auto-inject the account that claimed the drop's ID into when calling the function. +As an example, if the methodName was `nft_mint` and it expected a field `receiver_id` to be passed in, indicating who should receive the token, then the `accountIdField` would be `receiver_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/protocol.ts:260](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L260) + +___ + +### args + + **args**: `string` + +What arguments should be passed to the method. This should be in stringified JSON. + +#### Defined in + +[lib/types/protocol.ts:245](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L245) + +___ + +### attached\_deposit + + **attached\_deposit**: `string` + +How much yoctoNEAR should be attached to the call. + +#### Defined in + +[lib/types/protocol.ts:249](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L249) + +___ + +### attached\_gas + + `Optional` **attached\_gas**: `string` + +How much gas to attach to this method call. If none, all the gas is split between the parallel method calls in a given claim. +If this is specified, the key can ONLY be used to call `claim` and no `deposit_per_use` can be specified. This leads the key to act like a method calling proxy instead of a linkdrop. + +#### Defined in + +[lib/types/protocol.ts:254](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L254) + +___ + +### drop\_id\_field + + `Optional` **drop\_id\_field**: `string` + +Specifies what field Keypom should auto-inject the drops ID into when calling the function. +As an example, if an NFT contract expected the Keypom drop ID to be passed in as the field `keypom_drop_id` in order to gate access to who can mint NFTs, then the `dropIdField` would be `keypom_drop_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/protocol.ts:266](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L266) + +___ + +### funder\_id\_field + + `Optional` **funder\_id\_field**: `string` + +Specifies what field Keypom should auto-inject the funder's account ID into when calling the function. +As an example, if an NFT contract wanted to gate only users with an odd key ID to be able to mint an NFT and their parameter was called `keypom_key_id`, then the `keyIdField` would be `keypom_key_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/protocol.ts:278](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L278) + +___ + +### key\_id\_field + + `Optional` **key\_id\_field**: `string` + +Specifies what field Keypom should auto-inject the key's ID into when calling the function. +As an example, if an NFT contract wanted to gate only users with an odd key ID to be able to mint an NFT and their parameter was called `keypom_key_id`, then the `keyIdField` would be `keypom_key_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/protocol.ts:272](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L272) + +___ + +### method\_name + + **method\_name**: `string` + +The method that should be invoked on the `receiverId`'s contract. + +#### Defined in + +[lib/types/protocol.ts:241](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L241) + +___ + +### receiver\_id + + **receiver\_id**: `string` + +The account ID that the contract is deployed to that the method will be called on. + +#### Defined in + +[lib/types/protocol.ts:237](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L237) + +___ + +### receiver\_to\_claimer + + `Optional` **receiver\_to\_claimer**: `boolean` + +If set to true, the claiming account ID will be the receiver ID of the method call. +This receiver must be a valid account and non-malicious (cannot be set to the keypom contract) + +#### Defined in + +[lib/types/protocol.ts:283](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L283) + +___ + +### user\_args\_rule + + `Optional` **user\_args\_rule**: ``"AllUser"`` \| ``"FunderPreferred"`` \| ``"UserPreferred"`` + +What permissions does the user have when providing custom arguments to the function call? +By default, the user cannot provide any custom arguments + +#### Defined in + +[lib/types/protocol.ts:288](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L288) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedNFTData.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedNFTData.md new file mode 100644 index 00000000..16051f15 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedNFTData.md @@ -0,0 +1,34 @@ +--- +id: "ProtocolReturnedNFTData" +title: "Interface: ProtocolReturnedNFTData" +sidebar_label: "ProtocolReturnedNFTData" +sidebar_position: 0 +custom_edit_url: null +--- + +NFT Data information returned from the Protocol. This interface is exactly the same as the `NFTData`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### contract\_id + + **contract\_id**: `string` + +The account ID that the NFT contract is deployed to. This contract is where all the NFTs for the specific drop must come from. + +#### Defined in + +[lib/types/protocol.ts:204](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L204) + +___ + +### sender\_id + + `Optional` **sender\_id**: `string` + +By default, anyone can fund your drop with NFTs. This field allows you to set a specific account ID that will be locked into sending the NFTs. + +#### Defined in + +[lib/types/protocol.ts:206](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L206) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedNonFungibleTokenMetadata.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedNonFungibleTokenMetadata.md new file mode 100644 index 00000000..5f65274c --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedNonFungibleTokenMetadata.md @@ -0,0 +1,153 @@ +--- +id: "ProtocolReturnedNonFungibleTokenMetadata" +title: "Interface: ProtocolReturnedNonFungibleTokenMetadata" +sidebar_label: "ProtocolReturnedNonFungibleTokenMetadata" +sidebar_position: 0 +custom_edit_url: null +--- + +General structure of Non-Fungible Token Metadata as per official NEP-177 standard (https://github.com/near/NEPs/blob/master/neps/nep-0177.md). + +## Properties + +### copies + + `Optional` **copies**: `number` + +number of copies of this set of metadata in existence when token was minted. + +#### Defined in + +[lib/types/nft.ts:46](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L46) + +___ + +### description + + `Optional` **description**: `string` + +free-form description + +#### Defined in + +[lib/types/nft.ts:40](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L40) + +___ + +### expires\_at + + `Optional` **expires\_at**: `number` + +When token expires, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:50](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L50) + +___ + +### extra + + `Optional` **extra**: `string` + +anything extra the NFT wants to store on-chain. Can be stringified JSON. + +#### Defined in + +[lib/types/nft.ts:56](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L56) + +___ + +### issued\_at + + `Optional` **issued\_at**: `number` + +When token was issued or minted, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:48](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L48) + +___ + +### media + + `Optional` **media**: `string` + +URL to associated media, preferably to decentralized, content-addressed storage + +#### Defined in + +[lib/types/nft.ts:42](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L42) + +___ + +### media\_hash + + `Optional` **media\_hash**: `string` + +Base64-encoded sha256 hash of content referenced by the `media` field. Required if `media` is included. + +#### Defined in + +[lib/types/nft.ts:44](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L44) + +___ + +### reference + + `Optional` **reference**: `string` + +URL to an off-chain JSON file with more info. + +#### Defined in + +[lib/types/nft.ts:58](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L58) + +___ + +### reference\_hash + + `Optional` **reference\_hash**: `string` + +Base64-encoded sha256 hash of JSON from reference field. Required if `reference` is included. + +#### Defined in + +[lib/types/nft.ts:60](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L60) + +___ + +### starts\_at + + `Optional` **starts\_at**: `number` + +When token starts being valid, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:52](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L52) + +___ + +### title + + `Optional` **title**: `string` + +ex. "Arch Nemesis: Mail Carrier" or "Parcel #5055" + +#### Defined in + +[lib/types/nft.ts:38](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L38) + +___ + +### updated\_at + + `Optional` **updated\_at**: `number` + +When token was last updated, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:54](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L54) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedNonFungibleTokenObject.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedNonFungibleTokenObject.md new file mode 100644 index 00000000..029b8f45 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedNonFungibleTokenObject.md @@ -0,0 +1,69 @@ +--- +id: "ProtocolReturnedNonFungibleTokenObject" +title: "Interface: ProtocolReturnedNonFungibleTokenObject" +sidebar_label: "ProtocolReturnedNonFungibleTokenObject" +sidebar_position: 0 +custom_edit_url: null +--- + +General structure of a Non-Fungible Token object as per official NEP-171 standard (https://github.com/near/NEPs/blob/master/neps/nep-0171.md). + +## Properties + +### approved\_account\_ids + + `Optional` **approved\_account\_ids**: `Map`<`string`, `number`\> + +Map of account IDs to approval IDs as per official NEP-178 standard (https://github.com/near/NEPs/blob/master/neps/nep-0178.md). + +#### Defined in + +[lib/types/nft.ts:28](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L28) + +___ + +### metadata + + `Optional` **metadata**: [`ProtocolReturnedNonFungibleTokenMetadata`](ProtocolReturnedNonFungibleTokenMetadata.md) + +Metadata for the token + +#### Defined in + +[lib/types/nft.ts:26](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L26) + +___ + +### owner\_id + + **owner\_id**: `string` + +Account ID of the owner + +#### Defined in + +[lib/types/nft.ts:24](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L24) + +___ + +### royalty + + `Optional` **royalty**: `Map`<`string`, `number`\> + +A mapping of NEAR accounts to the amount each should be paid out as per official NEP-199 standard (https://github.com/near/NEPs/blob/master/neps/nep-0199.md). + +#### Defined in + +[lib/types/nft.ts:30](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L30) + +___ + +### token\_id + + **token\_id**: `string` + +String ID for the token + +#### Defined in + +[lib/types/nft.ts:22](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/nft.ts#L22) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedPublicSaleConfig.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedPublicSaleConfig.md new file mode 100644 index 00000000..74dfde00 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedPublicSaleConfig.md @@ -0,0 +1,97 @@ +--- +id: "ProtocolReturnedPublicSaleConfig" +title: "Interface: ProtocolReturnedPublicSaleConfig" +sidebar_label: "ProtocolReturnedPublicSaleConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Within the config, there are configurable options related to how keys can be sold and a funder can potentially make a profit. + +## Properties + +### allowlist + + `Optional` **allowlist**: `string`[] + +Which accounts are allowed to add keys? If the allowlist is empty, anyone that is not in the blocklist can add keys. + +#### Defined in + +[lib/types/protocol.ts:173](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L173) + +___ + +### auto\_withdraw\_funds + + `Optional` **auto\_withdraw\_funds**: `boolean` + +Should the revenue generated be sent to the funder's account balance or +automatically withdrawn and sent to their NEAR wallet? + +#### Defined in + +[lib/types/protocol.ts:180](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L180) + +___ + +### blocklist + + `Optional` **blocklist**: `string`[] + +Which accounts are NOT allowed to add keys? + +#### Defined in + +[lib/types/protocol.ts:175](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L175) + +___ + +### end + + `Optional` **end**: `number` + +Block timestamp dictating the end of the public sale. If None, keys can be added indefinitely +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:190](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L190) + +___ + +### max\_num\_keys + + `Optional` **max\_num\_keys**: `number` + +Maximum number of keys that can be added to this drop. If None, there is no max. + +#### Defined in + +[lib/types/protocol.ts:166](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L166) + +___ + +### price\_per\_key + + `Optional` **price\_per\_key**: `string` + +Amount of $NEAR that the user needs to attach (if they are not the funder) on top of costs. This amount will be +Automatically sent to the funder's balance. If None, the keys are free to the public. + +#### Defined in + +[lib/types/protocol.ts:171](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L171) + +___ + +### start + + `Optional` **start**: `number` + +Minimum block timestamp before the public sale starts. If None, keys can be added immediately +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:185](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L185) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedSimpleData.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedSimpleData.md new file mode 100644 index 00000000..92ea9441 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedSimpleData.md @@ -0,0 +1,17 @@ +--- +id: "ProtocolReturnedSimpleData" +title: "Interface: ProtocolReturnedSimpleData" +sidebar_label: "ProtocolReturnedSimpleData" +sidebar_position: 0 +custom_edit_url: null +--- + +## Properties + +### lazy\_register + + `Optional` **lazy\_register**: `boolean` + +#### Defined in + +[lib/types/protocol.ts:195](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L195) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedTimeConfig.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedTimeConfig.md new file mode 100644 index 00000000..c9da47ff --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedTimeConfig.md @@ -0,0 +1,63 @@ +--- +id: "ProtocolReturnedTimeConfig" +title: "Interface: ProtocolReturnedTimeConfig" +sidebar_label: "ProtocolReturnedTimeConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Time Config information returned from the Protocol. This interface is exactly the same as the `TimeConfig`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### end + + `Optional` **end**: `number` + +Block timestamp that keys must be used before. If this isn't specified, keys can be used indefinitely. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:101](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L101) + +___ + +### interval + + `Optional` **interval**: `number` + +Interval of time after the `start_timestamp` that must pass before a key can be used. If multiple intervals pass, the key can be used multiple times. +This has nothing to do With the throttle timestamp. It only pertains to the start timestamp and the current timestamp. The last_used timestamp is not taken into account. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:114](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L114) + +___ + +### start + + `Optional` **start**: `number` + +Minimum block timestamp before keys can be used. If this isn't specified, keys can be used immediately. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:95](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L95) + +___ + +### throttle + + `Optional` **throttle**: `number` + +Amount of time that *must* pass in between each key use. If this isn't specified, there is no delay between key uses. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:107](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L107) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedUsageConfig.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedUsageConfig.md new file mode 100644 index 00000000..80dbe93a --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/ProtocolReturnedUsageConfig.md @@ -0,0 +1,80 @@ +--- +id: "ProtocolReturnedUsageConfig" +title: "Interface: ProtocolReturnedUsageConfig" +sidebar_label: "ProtocolReturnedUsageConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Usage Config information returned from the Protocol. This interface is exactly the same as the `UsageConfig`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### account\_creation\_fields + + `Optional` **account\_creation\_fields**: `Object` + +When calling `create_account` on the root account, which keypom args should be attached to the payload. + +#### Type declaration + +| Name | Type | Description | +| :------ | :------ | :------ | +| `account_id_field?` | `string` | Specifies what field Keypom should auto-inject the account that claimed the drop's ID into when calling the `create_account` function. | +| `drop_id_field?` | `string` | Specifies what field Keypom should auto-inject the drop's ID into when calling the `create_account` function. | +| `funder_id_field?` | `string` | Specifies what field Keypom should auto-inject the drop funder's account ID into when calling the `create_account` function. | +| `key_id_field?` | `string` | Specifies what field Keypom should auto-inject the key's ID into when calling the `create_account` function. | + +#### Defined in + +[lib/types/protocol.ts:141](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L141) + +___ + +### auto\_delete\_drop + + `Optional` **auto\_delete\_drop**: `boolean` + +When a key is used and deleted, if it results in the drop being empty, should the drop automatically be deleted? If this isn't specified, it defaults to false. + +#### Defined in + +[lib/types/protocol.ts:134](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L134) + +___ + +### auto\_withdraw + + `Optional` **auto\_withdraw**: `boolean` + +In the case where `autoDeleteDrop` is set to true and the drop is the owner's last, should their balance be automatically withdrawn? If this isn't specified, it defaults to false. + +#### Defined in + +[lib/types/protocol.ts:138](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L138) + +___ + +### permissions + + `Optional` **permissions**: `string` + +Specify which methods can be called by the access key (either `claim` or `create_account_and_claim`). If this isn't specified, both methods can be called. + +#### Defined in + +[lib/types/protocol.ts:125](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L125) + +___ + +### refund\_deposit + + `Optional` **refund\_deposit**: `boolean` + +If the method `claim` is called rather than `create_account_and_claim`, should the `deposit_per_use` be refunded to the owner's balance? +If this isn't specified, it defaults to false. + +#### Defined in + +[lib/types/protocol.ts:130](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/protocol.ts#L130) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/PublicSaleConfig.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/PublicSaleConfig.md new file mode 100644 index 00000000..6b4d3617 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/PublicSaleConfig.md @@ -0,0 +1,107 @@ +--- +id: "PublicSaleConfig" +title: "Interface: PublicSaleConfig" +sidebar_label: "PublicSaleConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Within the config, there are configurable options related to how keys can be sold and a funder can potentially make a profit. + +## Properties + +### allowlist + + `Optional` **allowlist**: `string`[] + +Which accounts are allowed to add keys? If the allowlist is empty, anyone that is not in the blocklist can add keys. + +#### Defined in + +[lib/types/drops.ts:169](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L169) + +___ + +### autoWithdrawFunds + + `Optional` **autoWithdrawFunds**: `boolean` + +Should the revenue generated be sent to the funder's account balance or +automatically withdrawn and sent to their NEAR wallet? + +#### Defined in + +[lib/types/drops.ts:176](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L176) + +___ + +### blocklist + + `Optional` **blocklist**: `string`[] + +Which accounts are NOT allowed to add keys? + +#### Defined in + +[lib/types/drops.ts:171](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L171) + +___ + +### end + + `Optional` **end**: `number` + +Block timestamp dictating the end of the public sale. If None, keys can be added indefinitely +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:186](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L186) + +___ + +### maxNumKeys + + `Optional` **maxNumKeys**: `number` + +Maximum number of keys that can be added to this drop. If None, there is no max. + +#### Defined in + +[lib/types/drops.ts:161](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L161) + +___ + +### pricePerKeyNEAR + + `Optional` **pricePerKeyNEAR**: `number` + +Amount of $NEAR that the user needs to attach (if they are not the funder) on top of costs. This amount will be +Automatically sent to the funder's balance. If None, the keys are free to the public. + +#### Defined in + +[lib/types/drops.ts:166](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L166) + +___ + +### pricePerKeyYocto + + `Optional` **pricePerKeyYocto**: `string` + +#### Defined in + +[lib/types/drops.ts:167](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L167) + +___ + +### start + + `Optional` **start**: `number` + +Minimum block timestamp before the public sale starts. If None, keys can be added immediately +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:181](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L181) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/SimpleData.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/SimpleData.md new file mode 100644 index 00000000..fefc4f35 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/SimpleData.md @@ -0,0 +1,21 @@ +--- +id: "SimpleData" +title: "Interface: SimpleData" +sidebar_label: "SimpleData" +sidebar_position: 0 +custom_edit_url: null +--- + +Specific configurable information for Simple drops. + +## Properties + +### lazyRegister + + `Optional` **lazyRegister**: `boolean` + +If this is set to true, keys can be created and registered AFTER they've been created (for simple and FC drops only). + +#### Defined in + +[lib/types/simple.ts:6](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/simple.ts#L6) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/TimeConfig.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/TimeConfig.md new file mode 100644 index 00000000..40fc7152 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/TimeConfig.md @@ -0,0 +1,62 @@ +--- +id: "TimeConfig" +title: "Interface: TimeConfig" +sidebar_label: "TimeConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Within the config, there are configurable options related to timing such as how often a key can be used. + +## Properties + +### end + + `Optional` **end**: `number` + +Block timestamp that keys must be used before. If this isn't specified, keys can be used indefinitely. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:98](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L98) + +___ + +### interval + + `Optional` **interval**: `number` + +Interval of time after the `start_timestamp` that must pass before a key can be used. If multiple intervals pass, the key can be used multiple times. +This has nothing to do With the throttle timestamp. It only pertains to the start timestamp and the current timestamp. The last_used timestamp is not taken into account. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:111](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L111) + +___ + +### start + + `Optional` **start**: `number` + +Minimum block timestamp before keys can be used. If this isn't specified, keys can be used immediately. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:92](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L92) + +___ + +### throttle + + `Optional` **throttle**: `number` + +Amount of time that *must* pass in between each key use. If this isn't specified, there is no delay between key uses. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:104](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L104) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/UsageConfig.md b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/UsageConfig.md new file mode 100644 index 00000000..ceb10cf7 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/UsageConfig.md @@ -0,0 +1,79 @@ +--- +id: "UsageConfig" +title: "Interface: UsageConfig" +sidebar_label: "UsageConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Within the config, there are configurable options related to how keys can be used. What permissions they have, whether an empty drop should be automatically deleted etc. + +## Properties + +### accountCreationFields + + `Optional` **accountCreationFields**: `Object` + +When calling `create_account` on the root account, which keypom args should be attached to the payload. + +#### Type declaration + +| Name | Type | Description | +| :------ | :------ | :------ | +| `accountIdField?` | `string` | Specifies what field Keypom should auto-inject the account that claimed the drop's ID into when calling the `create_account` function. | +| `dropIdField?` | `string` | Specifies what field Keypom should auto-inject the drop's ID into when calling the `create_account` function. | +| `funderIdField?` | `string` | Specifies what field Keypom should auto-inject the drop funder's account ID into when calling the `create_account` function. | +| `keyIdField?` | `string` | Specifies what field Keypom should auto-inject the key's ID into when calling the `create_account` function. | + +#### Defined in + +[lib/types/drops.ts:136](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L136) + +___ + +### autoDeleteDrop + + `Optional` **autoDeleteDrop**: `boolean` + +When a key is used and deleted, if it results in the drop being empty, should the drop automatically be deleted? If this isn't specified, it defaults to false. + +#### Defined in + +[lib/types/drops.ts:130](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L130) + +___ + +### autoWithdraw + + `Optional` **autoWithdraw**: `boolean` + +When the last key in this drop is used, in the case where `autoDeleteDrop` is set to true and the drop is the owner's last, should their balance be automatically withdrawn? If this isn't specified, it defaults to false. + +#### Defined in + +[lib/types/drops.ts:134](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L134) + +___ + +### permissions + + `Optional` **permissions**: `string` + +Specify which methods can be called by the access key (either `claim` or `create_account_and_claim`). If this isn't specified, both methods can be called. + +#### Defined in + +[lib/types/drops.ts:121](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L121) + +___ + +### refundDeposit + + `Optional` **refundDeposit**: `boolean` + +If the method `claim` is called rather than `create_account_and_claim`, should the `deposit_per_use` be refunded to the owner's balance? +If this isn't specified, it defaults to false. + +#### Defined in + +[lib/types/drops.ts:126](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/drops.ts#L126) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/_category_.yml b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/_category_.yml new file mode 100644 index 00000000..43bec88c --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/interfaces/_category_.yml @@ -0,0 +1,2 @@ +label: "Interfaces" +position: 4 \ No newline at end of file diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/modules.md b/versioned_docs/version-2.0/keypom-sdk/Core/modules.md new file mode 100644 index 00000000..a7b6445b --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/modules.md @@ -0,0 +1,3290 @@ +--- +id: "modules" +title: "@keypom/core - v1.0.2" +sidebar_label: "Exports" +sidebar_position: 0.5 +custom_edit_url: null +--- + +## Interfaces + +- [BasicTransaction](interfaces/BasicTransaction.md) +- [ContractSourceMetadata](interfaces/ContractSourceMetadata.md) +- [CreateDropProtocolArgs](interfaces/CreateDropProtocolArgs.md) +- [CreateOrAddReturn](interfaces/CreateOrAddReturn.md) +- [Drop](interfaces/Drop.md) +- [DropConfig](interfaces/DropConfig.md) +- [EnvVars](interfaces/EnvVars.md) +- [FCData](interfaces/FCData.md) +- [FTData](interfaces/FTData.md) +- [Funder](interfaces/Funder.md) +- [FungibleTokenMetadata](interfaces/FungibleTokenMetadata.md) +- [GeneratedKeyPairs](interfaces/GeneratedKeyPairs.md) +- [KeyInfo](interfaces/KeyInfo.md) +- [Method](interfaces/Method.md) +- [NFTData](interfaces/NFTData.md) +- [NonFungibleTokenMetadata](interfaces/NonFungibleTokenMetadata.md) +- [PasswordPerUse](interfaces/PasswordPerUse.md) +- [ProtocolReturnedDrop](interfaces/ProtocolReturnedDrop.md) +- [ProtocolReturnedDropConfig](interfaces/ProtocolReturnedDropConfig.md) +- [ProtocolReturnedFCData](interfaces/ProtocolReturnedFCData.md) +- [ProtocolReturnedFTData](interfaces/ProtocolReturnedFTData.md) +- [ProtocolReturnedKeyInfo](interfaces/ProtocolReturnedKeyInfo.md) +- [ProtocolReturnedMethod](interfaces/ProtocolReturnedMethod.md) +- [ProtocolReturnedNFTData](interfaces/ProtocolReturnedNFTData.md) +- [ProtocolReturnedNonFungibleTokenMetadata](interfaces/ProtocolReturnedNonFungibleTokenMetadata.md) +- [ProtocolReturnedNonFungibleTokenObject](interfaces/ProtocolReturnedNonFungibleTokenObject.md) +- [ProtocolReturnedPublicSaleConfig](interfaces/ProtocolReturnedPublicSaleConfig.md) +- [ProtocolReturnedSimpleData](interfaces/ProtocolReturnedSimpleData.md) +- [ProtocolReturnedTimeConfig](interfaces/ProtocolReturnedTimeConfig.md) +- [ProtocolReturnedUsageConfig](interfaces/ProtocolReturnedUsageConfig.md) +- [PublicSaleConfig](interfaces/PublicSaleConfig.md) +- [SimpleData](interfaces/SimpleData.md) +- [TimeConfig](interfaces/TimeConfig.md) +- [UsageConfig](interfaces/UsageConfig.md) + +## Type Aliases + +### AnyWallet + + **AnyWallet**: `BrowserWalletBehaviour` \| `Wallet` \| `Promise`<`Wallet`\> + +#### Defined in + +[lib/types/params.ts:19](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/params.ts#L19) + +___ + +### NearKeyPair + + **NearKeyPair**: `KeyPair` + +#### Defined in + +[lib/types/general.ts:12](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/types/general.ts#L12) + +## Variables + +### TRIAL\_ERRORS + + `Const` **TRIAL\_ERRORS**: `Object` + +#### Type declaration + +| Name | Type | +| :------ | :------ | +| `EXIT_EXPECTED` | `string` | +| `INSUFFICIENT_BALANCE` | `string` | +| `INVALID_ACTION` | `string` | + +#### Defined in + +[lib/trial-accounts/utils.ts:13](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/trial-accounts/utils.ts#L13) + +___ + +### networks + + `Const` **networks**: `Object` + +#### Type declaration + +| Name | Type | +| :------ | :------ | +| `localnet` | { `networkId`: `string` = 'localnet'; `viewAccountId`: `string` = 'test.near' } | +| `localnet.networkId` | `string` | +| `localnet.viewAccountId` | `string` | +| `mainnet` | { `helperUrl`: `string` = 'https://helper.mainnet.near.org'; `networkId`: `string` = 'mainnet'; `nodeUrl`: `string` = 'https://rpc.mainnet.near.org'; `viewAccountId`: `string` = 'near'; `walletUrl`: `string` = 'https://wallet.near.org' } | +| `mainnet.helperUrl` | `string` | +| `mainnet.networkId` | `string` | +| `mainnet.nodeUrl` | `string` | +| `mainnet.viewAccountId` | `string` | +| `mainnet.walletUrl` | `string` | +| `testnet` | { `helperUrl`: `string` = 'https://helper.testnet.near.org'; `networkId`: `string` = 'testnet'; `nodeUrl`: `string` = 'https://rpc.testnet.near.org'; `viewAccountId`: `string` = 'testnet'; `walletUrl`: `string` = 'https://wallet.testnet.near.org' } | +| `testnet.helperUrl` | `string` | +| `testnet.networkId` | `string` | +| `testnet.nodeUrl` | `string` | +| `testnet.viewAccountId` | `string` | +| `testnet.walletUrl` | `string` | + +#### Defined in + +[lib/keypom.ts:25](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom.ts#L25) + +## Keypom SDK Environment + +### accountMappingContract + + `Const` **accountMappingContract**: `Object` + +Recovery mapping contracts used to keep track of trial account IDs for given public keys. + +#### Type declaration + +| Name | Type | +| :------ | :------ | +| `mainnet` | `string` | +| `testnet` | `string` | + +#### Defined in + +[lib/keypom.ts:93](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom.ts#L93) + +___ + +### supportedKeypomContracts + + `Const` **supportedKeypomContracts**: `Object` + +List of supported Keypom contracts that can be used with the SDK. + +#### Type declaration + +| Name | Type | +| :------ | :------ | +| `localnet` | { `keypom.test.near`: `boolean` = true } | +| `localnet.keypom.test.near` | `boolean` | +| `mainnet` | { `v1-3.keypom.near`: `boolean` = false; `v1-4.keypom.near`: `boolean` = true; `v1.keypom.near`: `boolean` = false; `v2.keypom.near`: `boolean` = true } | +| `mainnet.v1-3.keypom.near` | `boolean` | +| `mainnet.v1-4.keypom.near` | `boolean` | +| `mainnet.v1.keypom.near` | `boolean` | +| `mainnet.v2.keypom.near` | `boolean` | +| `testnet` | { `v1-3.keypom.testnet`: `boolean` = false; `v1-4.keypom.testnet`: `boolean` = true; `v1.keypom.testnet`: `boolean` = false; `v2.keypom.testnet`: `boolean` = true } | +| `testnet.v1-3.keypom.testnet` | `boolean` | +| `testnet.v1-4.keypom.testnet` | `boolean` | +| `testnet.v1.keypom.testnet` | `boolean` | +| `testnet.v2.keypom.testnet` | `boolean` | + +#### Defined in + +[lib/keypom.ts:51](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom.ts#L51) + +___ + +### supportedLinkdropClaimPages + + `Const` **supportedLinkdropClaimPages**: `Object` + +Official linkdrop claim pages for wallets and other applications + +#### Type declaration + +| Name | Type | +| :------ | :------ | +| `mainnet` | { `keypom`: `string` = 'https://keypom.xyz/claim/CONTRACT\_ID#SECRET\_KEY'; `meteor`: `string` = 'https://wallet.meteorwallet.app/linkdrop/CONTRACT\_ID/SECRET\_KEY'; `mynearwallet`: `string` = 'https://app.mynearwallet.com/linkdrop/CONTRACT\_ID/SECRET\_KEY' } | +| `mainnet.keypom` | `string` | +| `mainnet.meteor` | `string` | +| `mainnet.mynearwallet` | `string` | +| `testnet` | { `keypom`: `string` = 'https://testnet.keypom.xyz/claim/CONTRACT\_ID#SECRET\_KEY'; `meteor`: `string` = 'https://wallet.meteorwallet.app/linkdrop/CONTRACT\_ID/SECRET\_KEY'; `mynearwallet`: `string` = 'https://testnet.mynearwallet.com/linkdrop/CONTRACT\_ID/SECRET\_KEY' } | +| `testnet.keypom` | `string` | +| `testnet.meteor` | `string` | +| `testnet.mynearwallet` | `string` | + +#### Defined in + +[lib/keypom.ts:74](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom.ts#L74) + +___ + +### getEnv + +**getEnv**(): [`EnvVars`](interfaces/EnvVars.md) + +#### Returns + +[`EnvVars`](interfaces/EnvVars.md) + +The environment variables used by the Keypom library. + +#### Defined in + +[lib/keypom.ts:119](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom.ts#L119) + +___ + +### initKeypom + +**initKeypom**(`ยซdestructuredยป`): `Promise`<`any`\> + +Initializes the SDK to allow for interactions with the Keypom Protocol. By default, a new NEAR connection will be established but this can be overloaded by +passing in an existing connection object. In either case, if a funder is passed in, the credentials will be added to the keystore to sign transactions. + +To update the funder account, refer to the `updateFunder` function. If you only wish to use view methods and not sign transactions, no funder account is needed. +If you wish to update the Keypom Contract ID being used, refer to the `updateKeypomContractId` function. + +**`Example`** + +Using a pre-created NEAR connection instance with an UnencryptedFileSystemKeyStore: +```js +const path = require("path"); +const homedir = require("os").homedir(); +const { KeyPair, keyStores, connect } = require("near-api-js"); +const { initKeypom, getDrops } = require("keypom-js"); + +// Establish the network we wish to work on +const network = "testnet"; +// Get the location where the credentials are stored for our KeyStore +const CREDENTIALS_DIR = ".near-credentials"; +const credentialsPath = (await path).join(homedir, CREDENTIALS_DIR); +(await path).join; +let keyStore = new keyStores.UnencryptedFileSystemKeyStore(credentialsPath); + +// Establish the configuration for the connection +let nearConfig = { + networkId: network, + keyStore, + nodeUrl: `https://rpc.${network}.near.org`, + walletUrl: `https://wallet.${network}.near.org`, + helperUrl: `https://helper.${network}.near.org`, + explorerUrl: `https://explorer.${network}.near.org`, +}; +// Connect to the NEAR blockchain and get the connection instance +let near = await connect(nearConfig); + +// Initialize the SDK for the given network and NEAR connection +await initKeypom({ + near, + network +}); + +// Get the drops for the given owner +const dropsForOwner = await getDrops({accountId: "benjiman.testnet"}); +``` + +**`Example`** + +Creating an entirely new NEAR connection instance by using initKeypom and passing in a funder account: +```js +const { initKeypom, getDrops } = require("keypom-js"); + +// Initialize the SDK for the given network and NEAR connection +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Get the drops for the given owner +const dropsForOwner = await getDrops({accountId: "benjiman.testnet"}); +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `funder?` | [`Funder`](interfaces/Funder.md) | The account that will sign transactions to create drops and interact with the Keypom contract. This account will be added to the KeyStore if provided. If rootEntropy is provided for the funder, all access keys will be derived deterministically based off this string. | +| โ€บย `keypomContractId?` | `string` | Instead of using the most up-to-date, default Keypom contract, you can specify a specific account ID to use. If an older version is specified, some features of the SDK might not be usable. | +| โ€บย `near?` | `Near` | The NEAR connection instance to use. If not passed in, it will create a new one. | +| โ€บย `network?` | `string` | The network to connect to either `mainnet` or `testnet`. If a near object is passed in, this field can be omitted | + +#### Returns + +`Promise`<`any`\> + +If a funder is passed in, its account object is returned. Otherwise, it null is returned. + +#### Defined in + +[lib/keypom.ts:239](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom.ts#L239) + +___ + +### updateFunder + +**updateFunder**(`funder`): `Promise`<`any`\> + +Once the SDK is initialized, this function allows the current funder account to be updated. Having a funder is only necessary if you wish to sign transactions on the Keypom Protocol. + +**`Example`** + +After initializing the SDK, the funder is updated. +```js +const path = require("path"); +const homedir = require("os").homedir(); +const { KeyPair, keyStores, connect } = require("near-api-js"); +const { initKeypom, updateFunder, getDrops } = require("keypom-js"); + + // Initialize the SDK for the given network and NEAR connection + await initKeypom({ + network: "testnet", + }); + + // Update the current funder account + await updateFunder({ + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } + }) + + // Get the drops for the given owner + const dropsForOwner = await getDrops({accountId: "benjiman.testnet"}); + console.log('dropsForOwner: ', dropsForOwner) + + return; +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `funder` | `Object` | The account that will sign transactions to create drops and interact with the Keypom contract. This account will be added to the KeyStore if provided. If rootEntropy is provided for the funder, all access keys will be derived deterministically based off this string. | +| `funder.funder` | [`Funder`](interfaces/Funder.md) | - | + +#### Returns + +`Promise`<`any`\> + +The funder's account object is returned. + +#### Defined in + +[lib/keypom.ts:369](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom.ts#L369) + +___ + +### updateKeypomContractId + +**updateKeypomContractId**(`keypomContractId`): `any` + +This allows the desired Keypom contract ID to be set. By default, the most up-to-date Keypom contract for the given network is set during initKeypom. + +**`Example`** + +After initializing the SDK, the Keypom contract ID is updated. +```js +const path = require("path"); +const homedir = require("os").homedir(); +const { KeyPair, keyStores, connect } = require("near-api-js"); +const { initKeypom, updateKeypomContractId, getDrops } = require("keypom-js"); + + // Initialize the SDK for the given network and NEAR connection + await initKeypom({ + network: "testnet", + }); + + // Update the current Keypom contract ID + updateKeypomContractId({ + keypomContractId: "v1.keypom.testnet" + }) + + //Get the drops for the given owner + const dropsForOwner = await getDrops({accountId: "benjiman.testnet"}); + console.log('dropsForOwner: ', dropsForOwner) + + return; +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `keypomContractId` | `Object` | The account ID that should be used for the Keypom contract. | +| `keypomContractId.keypomContractId` | `string` | - | + +#### Returns + +`any` + +#### Defined in + +[lib/keypom.ts:430](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom.ts#L430) + +## Utility + +### accountExists + +**accountExists**(`accountId`): `Promise`<`boolean`\> + +Check whether or not a given account ID exists on the network. + +**`Example`** + +```js +const accountExists = await accountExists("benji.near"); +console.log(accountExists); // true +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `accountId` | `any` | The account ID you wish to check | + +#### Returns + +`Promise`<`boolean`\> + +- A boolean indicating whether or not the account exists + +#### Defined in + +[lib/keypom-utils.ts:87](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L87) + +___ + +### createNFTSeries + +**createNFTSeries**(`ยซdestructuredยป`): `Promise`<`void` \| `FinalExecutionOutcome`[]\> + +Creates a new NFT series on the official Keypom Series contracts. This is for lazy minting NFTs as part of an FC drop. + +**`Example`** + +Send 3 NFTs using the funder account (not passing in any accounts into the call): +```js + await initKeypom({ + // near, + network: 'testnet', + funder: { + accountId, + secretKey, + } + }) + + const {keys, dropId} = await createDrop({ + numKeys: 1, + config: { + usesPerKey: 100 + }, + metadata: "My Cool Drop Title!", + depositPerUseNEAR: 0.5, + fcData: { + methods: [[ + { + receiverId: `nft-v2.keypom.testnet`, + methodName: "nft_mint", + args: "", + dropIdField: "mint_id", + accountIdField: "receiver_id", + attachedDeposit: parseNearAmount("0.1") + } + ]] + } + }) + + const res = await createNFTSeries({ + dropId, + metadata: { + title: "Moon NFT!", + description: "A cool NFT for the best dog in the world.", + media: "bafybeibwhlfvlytmttpcofahkukuzh24ckcamklia3vimzd4vkgnydy7nq", + copies: 500 + } + }); + console.log('res: ', res) + + const URLs = formatLinkdropUrl({ + baseUrl: "localhost:3000/claim", + secretKeys: keys.secretKeys + }) + console.log('URLs: ', URLs) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `dropId` | `string` | The drop ID for the drop that should have a series associated with it. | +| โ€บย `metadata` | [`NonFungibleTokenMetadata`](interfaces/NonFungibleTokenMetadata.md) | The metadata that all minted NFTs will have. | +| โ€บย `royalty?` | `Map`<`string`, `number`\> | Any royalties associated with the series (as per official NEP-199 standard: https://github.com/near/NEPs/blob/master/neps/nep-0199.md) | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<`void` \| `FinalExecutionOutcome`[]\> + +#### Defined in + +[lib/keypom-utils.ts:227](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L227) + +___ + +### estimateRequiredDeposit + +**estimateRequiredDeposit**(`ยซdestructuredยป`): `Promise`<`string`\> + +Initiate the connection to the NEAR blockchain. + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `attachedGas` | `number` | How much Gas will be attached to each key's use. | +| โ€บย `depositPerUse` | `string` | How much yoctoNEAR each key will transfer upon use. | +| โ€บย `fcData?` | [`FCData`](interfaces/FCData.md) | The FC data for the drop that is being created. | +| โ€บย `ftData?` | [`FTData`](interfaces/FTData.md) | The FT data for the drop that is being created. | +| โ€บย `keyStorage?` | `string` | How much storage an individual key uses. | +| โ€บย `near` | `Near` | The NEAR connection instance used to interact with the chain. This can either the connection that the SDK uses from `getEnv` or a separate connection. | +| โ€บย `numKeys` | `number` | How many keys are being added to the drop. | +| โ€บย `storage?` | `string` | The estimated storage costs (can be retrieved through `getStorageBase`). | +| โ€บย `usesPerKey` | `number` | How many uses each key has. | + +#### Returns + +`Promise`<`string`\> + +#### Defined in + +[lib/keypom-utils.ts:1162](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L1162) + +___ + +### execute + +**execute**(`args`): `Promise`<`void` \| `FinalExecutionOutcome`[] \| (`void` \| `FinalExecutionOutcome`)[]\> + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `args` | `any` | + +#### Returns + +`Promise`<`void` \| `FinalExecutionOutcome`[] \| (`void` \| `FinalExecutionOutcome`)[]\> + +#### Defined in + +[lib/keypom.ts:147](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom.ts#L147) + +___ + +### formatLinkdropUrl + +**formatLinkdropUrl**(`ยซdestructuredยป`): `string`[] + +Constructs a valid linkdrop URL for a given claim page or custom URL. To view the list of supported claim pages, see the exported `supportedLinkdropClaimPages` variable. + +**`Example`** + +Use the keypom claim page: +```js +await initKeypom({ + network: 'testnet', + funder: { + accountId, + secretKey, + } +}) + +const {keys} = await createDrop({ + numKeys: 1, + depositPerUseNEAR: 1 +}); + +const linkdropUrl = formatLinkdropUrl({ + claimPage: "keypom", + contractId: "v2.keypom.testnet", + secretKeys: keys.secretKeys[0] // Can be either the array or individual secret key string +}) + +console.log('linkdropUrl: ', linkdropUrl) +``` + +**`Example`** + +Use a custom claim page with ONLY the secret key +```js +await initKeypom({ + network: 'testnet', + funder: { + accountId, + secretKey, + } +}) + +const {keys} = await createDrop({ + numKeys: 1, + depositPerUseNEAR: 1 +}); + +const linkdropUrl = formatLinkdropUrl({ + customURL: "foobar/SECRET_KEY/barfoo", + contractId: "v2.keypom.testnet", + secretKeys: keys.secretKeys[0] // Can be either the array or individual secret key string +}) + +console.log('linkdropUrl: ', linkdropUrl) +``` + +**`Example`** + +Use a custom claim page with both the secret key and contract ID +```js +await initKeypom({ + network: 'testnet', + funder: { + accountId, + secretKey, + } +}) + +const {keys} = await createDrop({ + numKeys: 1, + depositPerUseNEAR: 1 +}); + +const linkdropUrl = formatLinkdropUrl({ + customURL: "foobar/SECRET_KEY/barfoo/CONTRACT_ID", + contractId: "v2.keypom.testnet", + secretKeys: keys.secretKeys[0] // Can be either the array or individual secret key string +}) + +console.log('linkdropUrl: ', linkdropUrl) +``` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `claimPage?` | `string` | +| โ€บย `contractId?` | `string` | +| โ€บย `customURL?` | `string` | +| โ€บย `networkId?` | `string` | +| โ€บย `secretKeys` | `string` \| `string`[] | + +#### Returns + +`string`[] + +- An array of the linkdrop URLs + +#### Defined in + +[lib/keypom-utils.ts:384](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L384) + +___ + +### generateKeys + +**generateKeys**(`ยซdestructuredยป`): `Promise`<[`GeneratedKeyPairs`](interfaces/GeneratedKeyPairs.md)\> + +Generate ed25519 KeyPairs that can be used for Keypom linkdrops, or full access keys to claimed accounts. These keys can optionally be derived from some entropy such as a root password and metadata pertaining to each key (user provided password etc.). +Entropy is useful for creating an onboarding experience where in order to recover a keypair, the client simply needs to provide the meta entropy (could be a user's password) and the secret root key like a UUID). + +**`Example`** + +Generating 10 unique random keypairs with no entropy: +```js +// Generate 10 keys with no entropy (all random) +let keys = await generateKeys({ + numKeys: 10, +}) + +let pubKey1 = keys.publicKeys[0]; +let secretKey1 = keys.secretKeys[0]; + +console.log('1st Public Key: ', pubKey1); +console.log('1st Secret Key: ', secretKey1) +``` + +**`Example`** + +Generating 1 keypair based on entropy: +```js +// Generate 1 key with the given entropy +let {publicKeys, secretKeys} = await generateKeys({ + numKeys: 1, + rootEntropy: "my-global-password", + metaEntropy: "user-password-123" // In this case, since there is only 1 key, the entropy can be an array of size 1 as well. +}) + +let pubKey = publicKeys[0]; +let secretKey = secretKeys[0]; + +console.log('Public Key: ', pubKey); +console.log('Secret Key: ', secretKey) +``` + +**`Example`** + +Generating 2 keypairs each with their own entropy: +```js +// Generate 2 keys each with their own unique entropy +let keys = await generateKeys({ + numKeys: 2, + rootEntropy: "my-global-password", + metaEntropy: [ + `first-password:0`, + `second-password:1` + ] +}) + +console.log('Pub Keys ', keys.publicKeys); +console.log('Secret Keys ', keys.secretKeys); +``` + * + +**`Example`** + +Generate 50 keys exactly how the auto key generation would in createDrop and addKeys: +```js +const dropId = '1676913490360'; +const basePassword = "my-password"; +// Generate 50 keys each with their own unique entropy +let keys = await generateKeys({ + numKeys: 50, + rootEntropy: `${basePassword}-${dropId}`, + autoMetaNonceStart: 0 +}) + +console.log('Pub Keys ', keys.publicKeys); +console.log('Secret Keys ', keys.secretKeys); +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `autoMetaNonceStart?` | `number` | - | +| โ€บย `metaEntropy?` | `string` \| `string`[] | An array of entropies to use in conjunction with a base rootEntropy to deterministically generate the private keys. For single key generation, you can either pass in a string array with a single element, or simply pass in the string itself directly (not within an array). | +| โ€บย `numKeys` | `number` | The number of keys to generate. | +| โ€บย `rootEntropy?` | `string` | A root string that will be used as a baseline for all keys in conjunction with different metaEntropies (if provided) to deterministically generate a keypair. If not provided, the keypair will be completely random. | + +#### Returns + +`Promise`<[`GeneratedKeyPairs`](interfaces/GeneratedKeyPairs.md)\> + +- An object containing an array of KeyPairs, Public Keys and Secret Keys. + +#### Defined in + +[lib/keypom-utils.ts:536](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L536) + +___ + +### generatePerUsePasswords + +**generatePerUsePasswords**(`ยซdestructuredยป`): `Promise`<[`PasswordPerUse`](interfaces/PasswordPerUse.md)[][]\> + +Generate passwords for a set of public keys. A unique password will be created for each specified use of a public key where the use is NOT zero indexed (i.e 1st use = 1). +The passwords will be generated via a double hash of the base password + public key + specific use + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `basePassword` | `string` | +| โ€บย `publicKeys` | `string`[] | +| โ€บย `uses` | `number`[] | + +#### Returns + +`Promise`<[`PasswordPerUse`](interfaces/PasswordPerUse.md)[][]\> + +An array of objects for each key where each object has a password and maps it to its specific key use. + +#### Defined in + +[lib/keypom-utils.ts:1358](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L1358) + +___ + +### getFTMetadata + +**getFTMetadata**(`contractId`): `Promise`<[`FungibleTokenMetadata`](interfaces/FungibleTokenMetadata.md)\> + +Get the FT Metadata for a given fungible token contract. This is used to display important information such as the icon for the token, decimal format etc. + +**`Example`** + +```js +const ft = await getFTMetadata({ + contractId: "ft.keypom.testnet" +}); +console.log(ft); +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `contractId` | `Object` | The contract ID of the FT contract | +| `contractId.contractId` | `string` | - | + +#### Returns + +`Promise`<[`FungibleTokenMetadata`](interfaces/FungibleTokenMetadata.md)\> + +- The FT Metadata + +#### Defined in + +[lib/keypom-utils.ts:156](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L156) + +___ + +### getNFTMetadata + +**getNFTMetadata**(`ยซdestructuredยป`): `Promise`<[`ProtocolReturnedNonFungibleTokenObject`](interfaces/ProtocolReturnedNonFungibleTokenObject.md)\> + +Get the NFT Object (metadata, owner, approval IDs etc.) for a given token ID on a given contract. + +**`Example`** + +```js +const nft = await getNFTMetadata({ + contractId: "nft.keypom.testnet", + tokenId: "1" +}); +console.log(nft); +``` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `contractId` | `string` | +| โ€บย `tokenId` | `string` | + +#### Returns + +`Promise`<[`ProtocolReturnedNonFungibleTokenObject`](interfaces/ProtocolReturnedNonFungibleTokenObject.md)\> + +- The NFT Object + +#### Defined in + +[lib/keypom-utils.ts:120](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L120) + +___ + +### getPubFromSecret + +**getPubFromSecret**(`secretKey`): `string` + +Get the public key from a given secret key. + +**`Example`** + +```js +const pubKey = getPubFromSecret("ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1"); +console.log(pubKey); +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `secretKey` | `string` | The secret key you wish to get the public key from | + +#### Returns + +`string` + +- The public key + +#### Defined in + +[lib/keypom-utils.ts:68](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L68) + +___ + +### getStorageBase + +**getStorageBase**(`ยซdestructuredยป`): `string` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | [`CreateDropProtocolArgs`](interfaces/CreateDropProtocolArgs.md) | + +#### Returns + +`string` + +#### Defined in + +[lib/keypom-utils.ts:1073](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L1073) + +___ + +### hashPassword + +**hashPassword**(`str`, `fromHex?`): `Promise`<`string`\> + +Generate a sha256 hash of a passed in string. If the string is hex encoded, set the fromHex flag to true. + +**`Example`** + +Generating the required password to pass into `claim` given a base password: +```js + // Create the password to pass into claim which is a hash of the basePassword, public key and whichever use we are on +let currentUse = 1; +let passwordForClaim = await hashPassword(basePassword + publicKey + currentUse.toString()); +``` + +#### Parameters + +| Name | Type | Default value | Description | +| :------ | :------ | :------ | :------ | +| `str` | `string` | `undefined` | the string you wish to hash. By default, this should be utf8 encoded. If the string is hex encoded, set the fromHex flag to true. | +| `fromHex` | `boolean` | `false` | (OPTIONAL) - A flag that should be set if the string is hex encoded. Defaults to false. | + +#### Returns + +`Promise`<`string`\> + +- The resulting hash + +#### Defined in + +[lib/keypom-utils.ts:451](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L451) + +___ + +### viewAccessKeyData + +**viewAccessKeyData**(`ยซdestructuredยป`): `Promise`<`any`\> + +Query for important access key data such as the nonce, allowance, method names etc. that is stored on the NEAR protocol for a given account and public key. + +**`Example`** + +Check if an access key belongs to a trial account +```js +const keyInfo = await viewAccessKeyData({accountId, secretKey}); +let keyPerms = keyInfo.permission.FunctionCall; +isValidTrialInfo = keyPerms.receiver_id === accountId && keyPerms.method_names.includes('execute') +console.log('isValidTrialInfo: ', isValidTrialInfo) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `accountId` | `string` | The account that the access key belongs to. | +| โ€บย `publicKey?` | `string` | The public key of the access key | +| โ€บย `secretKey?` | `string` | The secret key of the access key | + +#### Returns + +`Promise`<`any`\> + +#### Defined in + +[lib/keypom-utils.ts:623](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L623) + +## Creating, And Claiming Drops + +### addKeys + +**addKeys**(`ยซdestructuredยป`): `Promise`<[`CreateOrAddReturn`](interfaces/CreateOrAddReturn.md)\> + +Add keys that are manually generated and passed in, or automatically generated to an existing drop. If they're +automatically generated, they can be based off a set of entropy. For NFT and FT drops, assets can automatically be sent to Keypom to register keys as part of the payload. +The deposit is estimated based on parameters that are passed in and the transaction can be returned instead of signed and sent to the network. This can allow you to get the +required deposit from the return value and use that to fund the account's Keypom balance to avoid multiple transactions being signed in the case of a drop with many keys. + +**`Example`** + +Create a basic empty simple drop and add 10 keys. Each key is completely random: +```js +// Initialize the SDK for the given network and NEAR connection. No entropy passed in so any auto generated keys will +// be completely random unless otherwise overwritten. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Create an empty simple drop with no keys. +const {dropId} = await createDrop({ + depositPerUseNEAR: 1, +}); + +// Add 10 completely random keys. The return value `keys` contains information about the generated keys +const {keys} = await addKeys({ + dropId, + numKeys: 10 +}) + +console.log('public keys: ', keys.publicKeys); +console.log('private keys: ', keys.secretKeys); +``` + +**`Example`** + +Init funder with root entropy, create empty drop and add generate deterministic keys. Compare with manually generated keys: +```js +// Initialize the SDK for the given network and NEAR connection. Root entropy is passed into the funder account so any generated keys +// Will be based off that entropy. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1", + rootEntropy: "my-global-secret-password" + } +}); + +// Create a simple drop with no keys +const { dropId } = await createDrop({ + depositPerUseNEAR: 1, +}); + +// Add 5 keys to the empty simple drop. Each key will be derived based on the rootEntropy of the funder, the drop ID, and key nonce. +const {keys: keysFromDrop} = await addKeys({ + dropId, + numKeys: 5 +}) + +// Deterministically Generate the Private Keys: +const nonceDropIdMeta = Array.from({length: 5}, (_, i) => `${dropId}_${i}`); +const manualKeys = await generateKeys({ + numKeys: 5, + rootEntropy: "my-global-secret-password", + metaEntropy: nonceDropIdMeta +}) + +// Get the public and private keys from the keys generated by addKeys +const {publicKeys, secretKeys} = keysFromDrop; +// Get the public and private keys from the keys that were manually generated +const {publicKeys: pubKeysGenerated, secretKeys: secretKeysGenerated} = manualKeys; +// These should match! +console.log('secretKeys: ', secretKeys) +console.log('secretKeysGenerated: ', secretKeysGenerated) + +// These should match! +console.log('publicKeys: ', publicKeys) +console.log('pubKeysGenerated: ', pubKeysGenerated) +``` + +**`Example`** + +Create an empty drop and add manually created keys: +```js +// Initialize the SDK for the given network and NEAR connection. No entropy passed in so any auto generated keys will +// be completely random unless otherwise overwritten. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Create an empty simple drop using the keys that were generated. Since keys are passed in, the return value won't contain information about the keys. +const {dropId} = await createDrop({ + publicKeys, + depositPerUseNEAR: 1, +}); + +// Generate 10 random keys +const {publicKeys} = await generateKeys({ + numKeys: 10 +}); + +// Add keys to the drop using the keys that were generated. Since keys are passed in, the return value won't contain information about the keys. +await addKeys({ + publicKeys, + dropId +}) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `basePassword?` | `string` | For doing password protected drops, this is the base password that will be used to generate all the passwords. It will be double hashed with the public keys. If specified, by default, all key uses will have their own unique password unless passwordProtectedUses is passed in. | +| โ€บย `drop?` | [`ProtocolReturnedDrop`](interfaces/ProtocolReturnedDrop.md) | If the drop information from getDropInformation is already known to the client, it can be passed in instead of the drop ID to reduce computation. | +| โ€บย `dropId?` | `string` | Specify the drop ID for which you want to add keys to. | +| โ€บย `extraDepositNEAR?` | `number` | For Public Sales, drops might require an additional fee for adding keys. This specifies the amount of $NEAR in human readable format (i.e `1.5` = 1.5 $NEAR) | +| โ€บย `extraDepositYocto?` | `string` | For Public Sales, drops might require an additional fee for adding keys. This specifies the amount of $NEAR in yoctoNEAR (i.e `1` = 1 $yoctoNEAR = 1e-24 $NEAR) | +| โ€บย `nftTokenIds?` | `string`[] | If the drop type is an NFT drop, the token IDs can be passed in so that the tokens are automatically sent to the Keypom contract rather than having to do two separate transactions. A maximum of 2 token IDs can be sent during the `addKeys` function. To send more token IDs in order to register key uses, use the `nftTransferCall` function. | +| โ€บย `numKeys` | `number` | Specify how many keys should be generated for the drop. If the funder has rootEntropy set OR rootEntropy is passed in, the keys will be deterministically generated using the drop ID, key nonce, and entropy. Otherwise, each key will be generated randomly. | +| โ€บย `passwordProtectedUses?` | `number`[] | For doing password protected drops, specifies exactly which uses will be password protected. The uses are NOT zero indexed (i.e 1st use = 1). Each use will have a different, unique password generated via double hashing the base password + public key + key use. | +| โ€บย `publicKeys?` | `string`[] | Pass in a custom set of publicKeys to add to the drop. If this is not passed in, keys will be generated based on the numKeys parameter. | +| โ€บย `returnTransactions?` | `boolean` | If true, the transaction will be returned instead of being signed and sent. This is useful for getting the requiredDeposit from the return value without actually signing the transaction. | +| โ€บย `rootEntropy?` | `string` | Specify an entropy to use for generating keys (will overload the funder's rootEntropy if applicable). This parameter only matters if the publicKeys variable is not passed in. | +| โ€บย `useBalance?` | `boolean` | If the account has a balance within the Keypom contract, set this to true to avoid the need to attach a deposit. If the account doesn't have enough balance, an error will throw. | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<[`CreateOrAddReturn`](interfaces/CreateOrAddReturn.md)\> + +Object containing: the drop ID, the responses of the execution, as well as any auto generated keys (if any). + +#### Defined in + +[lib/keys.ts:148](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keys.ts#L148) + +___ + +### claim + +**claim**(`ยซdestructuredยป`): `Promise`<`any`\> + +Allows a specific Keypom drop to be claimed via the secret key. + +**`Example`** + +Creating a simple $NEAR drop and claiming to an existing account: +```js +// Initialize the SDK for the given network and NEAR connection +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// create 1 keys with no entropy (random key) +const {publicKeys, secretKeys} = await generateKeys({ + numKeys: 1 +}); + +// Create a simple drop with 1 $NEAR +await createDrop({ + publicKeys, + depositPerUseNEAR: 1, +}); + +// Claim the drop to the passed in account ID +await claim({ + secretKey: secretKeys[0], + accountId: "benjiman.testnet" +}) +``` + +**`Example`** + +Creating a simple $NEAR drop and using it to create a brand new NEAR account: +```js +// Initialize the SDK for the given network and NEAR connection +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// create 2 keys with no entropy (all random). The first will be used for the drop and the second +// will be used as the full access key for the newly created account +const {publicKeys, secretKeys} = await generateKeys({ + numKeys: 2 +}); + +// Create a simple drop with 1 $NEAR +await createDrop({ + publicKeys: [publicKeys[0]], + depositPerUseNEAR: 1, +}); + +// Claim the drop and create a new account +await claim({ + secretKey: secretKeys[0], + newAccountId: "my-newly-creating-account.testnet", + newPublicKey: publicKeys[1] +}) +``` + +**`Example`** + +Creating a drop and adding a password to it. Generate the password using the hash function and pass it into claim the drop: +```js +// Initialize the SDK for the given network and NEAR connection +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +const basePassword = "my-cool-password123"; +// Create a simple drop with 1 $NEAR and pass in a base password to create a unique password for each use of each key +const {keys} = await createDrop({ + numKeys: 1, + depositPerUseNEAR: 1, + basePassword +}); + +// Create the password to pass into claim which is a hash of the basePassword, public key and whichever use we are on +let currentUse = 1; +let passwordForClaim = await hashPassword(basePassword + keys.publicKeys[0] + currentUse.toString()); + +// Claim the drop to the passed in account ID and use the password we generated above. +await claim({ + secretKey: keys.secretKeys[0], + accountId: "benjiman.testnet", + password: passwordForClaim +}) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `accountId?` | `string` | The account ID of an existing account that will be used to claim the drop. | +| โ€บย `fcArgs?` | `string`[] | For FC drops, if `user_args_rule` is set by the funder, when claiming, custom arguments can be passed into the function. The number of args in the array need to match the number of methods being executed. | +| โ€บย `newAccountId?` | `string` | If passed in, a new account ID will be created and the drop will be claimed to that account. This must be an account that does not exist yet. | +| โ€บย `newPublicKey?` | `string` | If creating a new account, a public key must be passed in to be used as the full access key for the newly created account. | +| โ€บย `password?` | `string` | If a password is required to use the key, it can be passed in | +| โ€บย `secretKey` | `string` | The private key associated with the Keypom link. This can either contain the `ed25519:` prefix or not. | + +#### Returns + +`Promise`<`any`\> + +#### Defined in + +[lib/claims.ts:108](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/claims.ts#L108) + +___ + +### createDrop + +**createDrop**(`ยซdestructuredยป`): `Promise`<[`CreateOrAddReturn`](interfaces/CreateOrAddReturn.md)\> + +Creates a new drop based on parameters passed in. This drop can have keys that are manually generated and passed in, or automatically generated. If they're +automatically generated, they can be based off a set of entropy. For NFT and FT drops, assets can automatically be sent to Keypom to register keys as part of the payload. +The deposit is estimated based on parameters that are passed in and the transaction can be returned instead of signed and sent to the network. This can allow you to get the +required deposit from the return value and use that to fund the account's Keypom balance to avoid multiple transactions being signed in the case of a drop with many keys. + +**`Example`** + +Create a basic simple drop containing 10 keys each with 1 $NEAR. Each key is completely random: +```js +// Initialize the SDK for the given network and NEAR connection. No entropy passed in so any auto generated keys will +// be completely random unless otherwise overwritten. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Create a drop with 10 completely random keys. The return value `keys` contains information about the generated keys +const {keys} = await createDrop({ + numKeys: 10, + depositPerUseNEAR: 1, +}); + +console.log('public keys: ', keys.publicKeys); +console.log('private keys: ', keys.secretKeys); +``` + +**`Example`** + +Init funder with root entropy and generate deterministic keys for a drop. Compare with manually generated keys: +```js +// Initialize the SDK for the given network and NEAR connection. Root entropy is passed into the funder account so any generated keys +// Will be based off that entropy. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1", + rootEntropy: "my-global-secret-password" + } +}); + +// Create a simple drop with 5 keys. Each key will be derived based on the rootEntropy of the funder, the drop ID, and key nonce. +const { keys: keysFromDrop, dropId } = await createDrop({ + numKeys: 5, + depositPerUseNEAR: 1, +}); + +// Deterministically Generate the Private Keys: +const nonceDropIdMeta = Array.from({length: 5}, (_, i) => `${dropId}_${i}`); +const manualKeys = await generateKeys({ + numKeys: 5, + rootEntropy: "my-global-secret-password", + metaEntropy: nonceDropIdMeta +}) + +// Get the public and private keys from the keys generated by the drop +const {publicKeys, secretKeys} = keysFromDrop; +// Get the public and private keys from the keys that were manually generated +const {publicKeys: pubKeysGenerated, secretKeys: secretKeysGenerated} = manualKeys; +// These should match! +console.log('secretKeys: ', secretKeys) +console.log('secretKeysGenerated: ', secretKeysGenerated) + +// These should match! +console.log('publicKeys: ', publicKeys) +console.log('pubKeysGenerated: ', pubKeysGenerated) +``` + +**`Example`** + +Use manually generated keys to create a drop: +```js +// Initialize the SDK for the given network and NEAR connection. No entropy passed in so any auto generated keys will +// be completely random unless otherwise overwritten. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Generate 10 random keys +const {publicKeys} = await generateKeys({ + numKeys: 10 +}); + +// Create a drop using the keys that were generated. Since keys are passed in, the return value won't contain information about the keys. +await createDrop({ + publicKeys, + depositPerUseNEAR: 1, +}); +``` + +**`Example`** + +Create a simple drop with 1 key and 1 use per key. This 1 use-key should be password protected based on a base-password: +```js +// Initialize the SDK for the given network and NEAR connection +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +const basePassword = "my-cool-password123"; +// Create a simple drop with 1 $NEAR and pass in a base password to create a unique password for each use of each key +const {keys} = await createDrop({ + numKeys: 1, + depositPerUseNEAR: 1, + basePassword +}); + +// Create the password to pass into claim which is a hash of the basePassword, public key and whichever use we are on +let currentUse = 1; +let passwordForClaim = await hashPassword(basePassword + keys.publicKeys[0] + currentUse.toString()); +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `basePassword?` | `string` | For doing password protected drops, this is the base password that will be used to generate all the passwords. It will be double hashed with the public keys. If specified, by default, all key uses will have their own unique password unless passwordProtectedUses is passed in. | +| โ€บย `config?` | [`DropConfig`](interfaces/DropConfig.md) | Allows specific drop behaviors to be configured such as the number of uses each key / link will have. | +| โ€บย `depositPerUseNEAR?` | `string` \| `number` | How much $NEAR should be contained in each link. Unit in $NEAR (i.e `1` = 1 $NEAR) | +| โ€บย `depositPerUseYocto?` | `string` | How much $yoctoNEAR should be contained in each link. Unit in yoctoNEAR (1 yoctoNEAR = 1e-24 $NEAR) | +| โ€บย `dropId?` | `string` | Specify a custom drop ID rather than using the incrementing nonce on the contract. | +| โ€บย `fcData?` | [`FCData`](interfaces/FCData.md) | For creating a function call drop, this contains necessary configurable information about the drop. | +| โ€บย `ftData?` | [`FTData`](interfaces/FTData.md) | For creating a fungible token drop, this contains necessary configurable information about the drop. | +| โ€บย `metadata?` | `string` | String of metadata to attach to the drop. This can be whatever you would like and is optional. Often this is stringified JSON. | +| โ€บย `nftData?` | [`NFTData`](interfaces/NFTData.md) | For creating a non-fungible token drop, this contains necessary configurable information about the drop. | +| โ€บย `numKeys?` | `number` | Specify how many keys should be generated for the drop. If the funder has rootEntropy set OR rootEntropy is passed in, the keys will be deterministically generated using the drop ID, key nonce, and entropy. Otherwise, each key will be generated randomly. If this is not passed in, the publicKeys parameter *must* be passed in. | +| โ€บย `passwordProtectedUses?` | `number`[] | For doing password protected drops, specifies exactly which uses will be password protected. The uses are NOT zero indexed (i.e 1st use = 1). Each use will have a different, unique password generated via double hashing the base password + public key + key use. | +| โ€บย `publicKeys?` | `string`[] | Pass in a custom set of publicKeys to add to the drop. If this is not passed in, keys will be generated based on the numKeys parameter. | +| โ€บย `requiredGas?` | `string` | Allows you to overload how much gas should be attached to the transaction when the key is claimed. This should be in Gas units (1 TGas = 1000000000000). By default, 100 TGas is attached. | +| โ€บย `returnTransactions?` | `boolean` | If true, the transaction will be returned instead of being signed and sent. This is useful for getting the requiredDeposit from the return value without actually signing the transaction. | +| โ€บย `rootEntropy?` | `string` | Specify an entropy to use for generating keys (will overload the funder's rootEntropy if applicable). This parameter only matters if the publicKeys variable is not passed in. | +| โ€บย `simpleData?` | [`SimpleData`](interfaces/SimpleData.md) | For creating a simple drop, this contains necessary configurable information about the drop. | +| โ€บย `successUrl?` | `string` | When signing with a wallet, a success URl can be included that the user will be redirected to once the transaction has been successfully signed. | +| โ€บย `useBalance?` | `boolean` | If the account has a balance within the Keypom contract, set this to true to avoid the need to attach a deposit. If the account doesn't have enough balance, an error will throw. | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<[`CreateOrAddReturn`](interfaces/CreateOrAddReturn.md)\> + +Object containing: the drop ID, the responses of the execution, as well as any auto generated keys (if any). + +#### Defined in + +[lib/drops.ts:176](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/drops.ts#L176) + +## User Balance Functions + +### addToBalance + +**addToBalance**(`ยซdestructuredยป`): `Promise`<`any`\> + +Deposit some amount of $NEAR or yoctoNEAR$ into the Keypom contract. This amount can then be used to create drops or add keys without +Having to explicitly attach a deposit every time. It can be thought of like a bank account. + +**`Example`** + +Add 1 $NEAR to the account balance +```js +// Initialize the SDK on testnet +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +await addToBalance({ + amount: "1", +)}; +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `amountNear?` | `string` | Human readable format for the amount of tokens to add. **`Example`** ```ts Example: transferring one $NEAR should be passed in as "1" and NOT "1000000000000000000000000" ``` | +| โ€บย `amountYocto?` | `string` | Amount of tokens to add but considering the decimal amount (non human-readable). **`Example`** ```ts Transferring one $NEAR should be passed in as "1000000000000000000000000" and NOT "1" ``` | +| โ€บย `successUrl?` | `string` | When signing with a wallet, a success URl can be included that the user will be redirected to once the transaction has been successfully signed. | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<`any`\> + +#### Defined in + +[lib/balances.ts:37](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/balances.ts#L37) + +___ + +### withdrawBalance + +**withdrawBalance**(`ยซdestructuredยป`): `Promise`<`any`\> + +Withdraw all the $NEAR from your balance in the Keypom contract. + +**`Example`** + +Add 1 $NEAR to the account balance and then withdraw it +```js +// Initialize the SDK on testnet +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +await addToBalance({ + amount: "1", +}); + +await withdrawBalance({}); +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<`any`\> + +#### Defined in + +[lib/balances.ts:118](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/balances.ts#L118) + +## Public Sale Functions + +### addToSaleAllowlist + +**addToSaleAllowlist**(`ยซdestructuredยป`): `Promise`<`any`\> + +Add a list of account IDs to a drop's sale allowlist. If the allowlist is empty, anyone can purchase keys. The sale object must exist in the drop's config for this to go through. + +**`Example`** + +```js +const {dropId} = await createDrop({ + numKeys: 0, + depositPerUseNEAR: 0.1, + config: { + sale: { + maxNumKeys: 2, + pricePerKeyNEAR: 1 + } + } + }); + + let canAddKeys = await canUserAddKeys({dropId, accountId: "foobar.testnet"}); + t.is(canAddKeys, true); + + await addToSaleAllowlist({dropId, accountIds: ["barfoo.testnet"]}); + canAddKeys = await canUserAddKeys({dropId, accountId: "foobar.testnet"}); + t.is(canAddKeys, false); + ``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `accountIds` | `string`[] | A list of account IDs that should be added to the sale allowlist | +| โ€บย `dropId` | `string` | The drop ID for the drop | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<`any`\> + +#### Defined in + +[lib/sales.ts:44](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/sales.ts#L44) + +___ + +### addToSaleBlocklist + +**addToSaleBlocklist**(`ยซdestructuredยป`): `Promise`<`any`\> + +Add a list of account IDs to a drop's sale blocklist. The sale object must exist in the drop's config for this to go through. + +**`Example`** + +```js + const {dropId} = await createDrop({ + numKeys: 0, + depositPerUseNEAR: 0.1, + config: { + sale: { + maxNumKeys: 2, + pricePerKeyNEAR: 1 + } + } + }); + + let canAddKeys = await canUserAddKeys({dropId, accountId: "foobar.testnet"}); + t.is(canAddKeys, true); + + await addToSaleBlocklist({dropId, accountIds: ["foobar.testnet"]}); + canAddKeys = await canUserAddKeys({dropId, accountId: "foobar.testnet"}); + t.is(canAddKeys, false); + ``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `accountIds` | `string`[] | A list of account IDs that should be added to the sale blocklist | +| โ€บย `dropId` | `string` | The drop ID for the drop | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<`any`\> + +#### Defined in + +[lib/sales.ts:224](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/sales.ts#L224) + +___ + +### removeFromSaleAllowlist + +**removeFromSaleAllowlist**(`ยซdestructuredยป`): `Promise`<`any`\> + +Remove a list of account IDs from a drop's sale allowlist. If the allowlist is empty, anyone can purchase keys. The sale object must exist in the drop's config for this to go through. + +**`Example`** + +```js + const {dropId} = await createDrop({ + numKeys: 0, + depositPerUseNEAR: 0.1, + config: { + sale: { + maxNumKeys: 2, + pricePerKeyNEAR: 1, + allowlist: ["foobar.testnet", "barfoo.testnet"] + } + } + }); + + let canAddKeys = await canUserAddKeys({dropId, accountId: "foobar.testnet"}); + t.is(canAddKeys, true); + + canAddKeys = await canUserAddKeys({dropId, accountId: "not_in_allowlist.testnet"}); + t.is(canAddKeys, false); + + await removeFromSaleAllowlist({dropId, accountIds: ["foobar.testnet"]}); + canAddKeys = await canUserAddKeys({dropId, accountId: "foobar.testnet"}); + t.is(canAddKeys, false); + + await removeFromSaleAllowlist({dropId, accountIds: ["barfoo.testnet"]}); + canAddKeys = await canUserAddKeys({dropId, accountId: "foobar.testnet"}); + t.is(canAddKeys, true); + ``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `accountIds` | `string`[] | A list of account IDs that should be removed from the sale's allowlist | +| โ€บย `dropId` | `string` | The drop ID for the drop | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<`any`\> + +#### Defined in + +[lib/sales.ts:138](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/sales.ts#L138) + +___ + +### removeFromSaleBlocklist + +**removeFromSaleBlocklist**(`ยซdestructuredยป`): `Promise`<`any`\> + +Remove a list of account IDs from a drop's sale blocklist. The sale object must exist in the drop's config for this to go through. + +**`Example`** + +```js + const {dropId} = await createDrop({ + numKeys: 0, + depositPerUseNEAR: 0.1, + config: { + sale: { + maxNumKeys: 2, + pricePerKeyNEAR: 1, + blocklist: ["foobar.testnet"] + } + } + }); + + let canAddKeys = await canUserAddKeys({dropId, accountId: "foobar.testnet"}); + t.is(canAddKeys, false); + + canAddKeys = await canUserAddKeys({dropId, accountId: "not_in_blocklist.testnet"}); + t.is(canAddKeys, true); + + await removeFromSaleBlocklist({dropId, accountIds: ["foobar.testnet"]}); + canAddKeys = await canUserAddKeys({dropId, accountId: "foobar.testnet"}); + t.is(canAddKeys, true); + ``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `accountIds` | `string`[] | A list of account IDs that should be removed from the sale's allowlist | +| โ€บย `dropId` | `string` | The drop ID for the drop | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<`any`\> + +#### Defined in + +[lib/sales.ts:314](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/sales.ts#L314) + +___ + +### updateSale + +**updateSale**(`ยซdestructuredยป`): `Promise`<`any`\> + +Remove a list of account IDs from a drop's sale blocklist. The sale object must exist in the drop's config for this to go through. + +**`Example`** + +```js + const {dropId} = await createDrop({ + numKeys: 0, + depositPerUseNEAR: 0.1, + config: { + sale: { + maxNumKeys: 2, + pricePerKeyNEAR: 1 + } + } + }); + + await updateSale({ + dropId, + pricePerKeyNEAR: 2 + }) + ``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `autoWithdrawFunds?` | `boolean` | Should the revenue generated be sent to the funder's account balance or automatically withdrawn and sent to their NEAR wallet? | +| โ€บย `dropId` | `string` | The drop ID for the drop | +| โ€บย `end?` | `number` | Block timestamp dictating the end of the public sale. If None, keys can be added indefinitely Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. | +| โ€บย `maxNumKeys?` | `number` | Maximum number of keys that can be added to this drop. If None, there is no max. | +| โ€บย `pricePerKeyNEAR?` | `number` | Amount of $NEAR that the user needs to attach (if they are not the funder) on top of costs. This amount will be Automatically sent to the funder's balance. If None, the keys are free to the public. | +| โ€บย `pricePerKeyYocto?` | `string` | - | +| โ€บย `start?` | `number` | Minimum block timestamp before the public sale starts. If None, keys can be added immediately Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<`any`\> + +#### Defined in + +[lib/sales.ts:399](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/sales.ts#L399) + +## Trial Accounts + +### canExitTrial + +**canExitTrial**(`ยซdestructuredยป`): `Promise`<`boolean`\> + +Check whether a trial account is able to exit their trial state and become a fully fledged normal account. + +**`Example`** + +Create a trial account and check whether it can immediately exit +```js + await initKeypom({ + // near, + network: 'testnet', + funder: { + accountId: fundingAccountId, + secretKey: fundingAccountSecretKey, + } + }); + + const callableContracts = [ + `nft.examples.testnet` + ] + + const {dropId, keys: {secretKeys: trialSecretKeys, publicKeys: trialPublicKeys}} + = await createTrialAccountDrop({ + numKeys: 1, + contractBytes: [...readFileSync('./test/ext-wasm/trial-accounts.wasm')], + startingBalanceNEAR: 0.5, + callableContracts: callableContracts, + callableMethods: ['*'], + maxAttachableNEARPerContract: [1], + trialEndFloorNEAR: 0.33 + 0.3 + }) + + const desiredAccountId = `${dropId}-keypom.testnet` + const trialSecretKey = trialSecretKeys[0] + await claimTrialAccountDrop({ + desiredAccountId, + secretKey: trialSecretKey + }) + + const canExitTrial = await keypom.canExitTrial({ + trialAccountId: desiredAccountId + }) + console.log('canExitTrial: ', canExitTrial) + ``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `trialAccountId` | `string` | The account ID of the trial account | + +#### Returns + +`Promise`<`boolean`\> + +#### Defined in + +[lib/trial-accounts/trial-active.ts:403](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/trial-accounts/trial-active.ts#L403) + +___ + +### claimTrialAccountDrop + +**claimTrialAccountDrop**(`ยซdestructuredยป`): `Promise`<`any`\> + +Claim a Keypom trial account drop which will create a new account, deploy and initialize the trial account contract, and setup the account with initial conditions as specified in the drop. + +**`Example`** + +Creating a trial account with any callable methods, an amount of 0.5 $NEAR and 5 keys. +```js +const callableContracts = [ + `v1.social08.testnet`, + 'guest-book.examples.keypom.testnet', +] + +const {dropId, keys: {secretKeys: trialSecretKeys, publicKeys: trialPublicKeys}} += await createTrialAccountDrop({ + numKeys: 1, + contractBytes: [...readFileSync('./test/ext-wasm/trial-accounts.wasm')], + startingBalanceNEAR: 0.5, + callableContracts: callableContracts, + callableMethods: ['set:grant_write_permission', '*'], + maxAttachableNEARPerContract: callableContracts.map(() => '1'), + trialEndFloorNEAR: 0.33 +}) + +const newAccountId = `${Date.now().toString()}.linkdrop-beta.keypom.testnet` +await claimTrialAccountDrop({ + secretKey: trialSecretKeys[0], + desiredAccountId: newAccountId, +}) + +console.log(` + +${JSON.stringify({ + account_id: newAccountId, + public_key: trialPublicKeys[0], + private_key: trialSecretKeys[0] +})} + +`) + +console.log(`http://localhost:1234/keypom-url/${newAccountId}#${trialSecretKeys[0]}`) + +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `desiredAccountId` | `string` | The account ID that will be created for the trial | +| โ€บย `secretKey` | `string` | The private key associated with the Keypom link. This can either contain the `ed25519:` prefix or not. | + +#### Returns + +`Promise`<`any`\> + +#### Defined in + +[lib/trial-accounts/pre-trial.ts:505](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/trial-accounts/pre-trial.ts#L505) + +___ + +### createTrialAccountDrop + +**createTrialAccountDrop**(`ยซdestructuredยป`): `Promise`<[`CreateOrAddReturn`](interfaces/CreateOrAddReturn.md)\> + +Creates a new trial account drop which can be used to instantly sign users into decentralized applications that support the Keypom wallet selector plugin. + +The trial account is locked into certain behaviors depending on what is passed into `createTrialAccountDrop`. These behaviors include callable contracts, methods on +those contracts, the maximum amount of $NEAR that can be spent on each contract as well as an exit condition. Once the trial account has run out of funds, the only way to +retain any assets from the trial or continue using the account ID, is to repay the specific account ID for the amount of $NEAR specified. + +**`Example`** + +Creating a trial account with any callable methods, an amount of 0.5 $NEAR and 5 keys. +```js +const {keys: {secretKeys: trialSecretKeys, publicKeys: trialPublicKeys}} = await createTrialAccountDrop({ + contractBytes: [...readFileSync('./test/ext-wasm/trial-accounts.wasm')], + trialFundsNEAR: 0.5, + callableContracts: ['dev-1676298343226-57701595703433'], + callableMethods: ['*'], + amounts: ['0.5'], + numKeys: 5, + config: { + dropRoot: "linkdrop-beta.keypom.testnet" + } +}) + +const newAccountId = `${Date.now().toString()}.linkdrop-beta.keypom.testnet` +await claimTrialAccountDrop({ + secretKey: trialSecretKeys[0], + desiredAccountId: newAccountId, +}) + +console.log(` + +${JSON.stringify({ + account_id: newAccountId, + public_key: trialPublicKeys[0], + private_key: trialSecretKeys[0] +})} + +`) + +console.log(`http://localhost:1234/keypom-url/${newAccountId}#${trialSecretKeys[0]}`) + +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `callableContracts` | `string`[] | The contracts that the trial account should be able to call. | +| โ€บย `callableMethods` | `string`[][] | An array that contains the list of methods that the trial account should be able to call on each respective contract. To allow any methods to be called on the receiver contract, pass in `[*]`. | +| โ€บย `config?` | [`DropConfig`](interfaces/DropConfig.md) | Allows specific drop behaviors to be configured such as the number of uses each key / link will have. | +| โ€บย `contractBytes` | `number`[] | Bytes of the trial account smart contract | +| โ€บย `dropId?` | `string` | Specify a custom drop ID rather than using the incrementing nonce on the contract. | +| โ€บย `maxAttachableNEARPerContract` | (`string` \| `number`)[] | The upper bound of $NEAR that trial account is able to attach to calls associated with each contract passed in. For no upper limit, pass in `*`. Units are in $NEAR (i.e `1` = 1 $NEAR). | +| โ€บย `maxAttachableYoctoPerContract` | `string`[] | The upper bound of $yocto that trial account is able to attach to calls associated with each contract passed in. For no upper limit, pass in `*`. Units are in $yoctoNEAR (i.e `1` = 1 $yoctoNEAR). | +| โ€บย `metadata?` | `string` | String of metadata to attach to the drop. This can be whatever you would like and is optional. Often this is stringified JSON. | +| โ€บย `numKeys` | `number` | Specify how many keys should be generated for the drop. If the funder has rootEntropy set OR rootEntropy is passed in, the keys will be deterministically generated using the drop ID, key nonce, and entropy. Otherwise, each key will be generated randomly. | +| โ€บย `publicKeys?` | `string`[] | Pass in a custom set of publicKeys to add to the drop. If this is not passed in, keys will be generated based on the numKeys parameter. | +| โ€บย `repayAmountNEAR?` | `string` \| `number` | How much $NEAR should be paid back to the specified funder in order to unlock the trial account. Unit in $NEAR (i.e `1` = 1 $NEAR) | +| โ€บย `repayAmountYocto?` | `string` | How much $NEAR should be paid back to the specified funder in order to unlock the trial account. Unit in yoctoNEAR (1 yoctoNEAR = 1e-24 $NEAR) | +| โ€บย `repayTo?` | `string` | The account that should receive the repayment of the trial account. If not specified, the drop funder will be used. | +| โ€บย `returnTransactions?` | `boolean` | If true, the transaction will be returned instead of being signed and sent. This is useful for getting the requiredDeposit from the return value without actually signing the transaction. | +| โ€บย `rootEntropy?` | `string` | Specify an entropy to use for generating keys (will overload the funder's rootEntropy if applicable). This parameter only matters if the publicKeys variable is not passed in. | +| โ€บย `startingBalanceNEAR?` | `string` \| `number` | How much $NEAR should the trial account start with? Unit in $NEAR (i.e `1` = 1 $NEAR) | +| โ€บย `startingBalanceYocto?` | `string` | How much $NEAR should the trial account start with? Unit in yoctoNEAR (1 yoctoNEAR = 1e-24 $NEAR) | +| โ€บย `successUrl?` | `string` | When signing with a wallet, a success URl can be included that the user will be redirected to once the transaction has been successfully signed. | +| โ€บย `trialEndFloorNEAR` | `string` \| `number` | Once the account has spent more than this amount (in $NEAR), the trial is over and the exit conditions must be met. | +| โ€บย `trialEndFloorYocto` | `string` | Once the account has spent more than this amount (in yocto), the trial is over and the exit conditions must be met. | +| โ€บย `useBalance?` | `boolean` | If the account has a balance within the Keypom contract, set this to true to avoid the need to attach a deposit. If the account doesn't have enough balance, an error will throw. | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<[`CreateOrAddReturn`](interfaces/CreateOrAddReturn.md)\> + +Object containing: the drop ID, the responses of the execution, as well as any auto generated keys (if any). + +#### Defined in + +[lib/trial-accounts/pre-trial.ts:81](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/trial-accounts/pre-trial.ts#L81) + +___ + +### trialCallMethod + +**trialCallMethod**(`ยซdestructuredยป`): `Promise`<`FinalExecutionOutcome`[]\> + +Execute a method using a trial account. If the trial account is in the exit state, this will throw an error. Similarly, if the given method data +cannot be executed by the trial account (e.g. the attached deposit exceeds the trial account's restrictions), this will throw an error. + +**`Example`** + +Using a trial account to mint a new NFT: +```js + await initKeypom({ + network: 'testnet', + funder: { + accountId: fundingAccountId, + secretKey: fundingAccountSecretKey, + } + }); + + const callableContracts = [ + `nft.examples.testnet` + ] + + const {dropId, keys: {secretKeys: trialSecretKeys, publicKeys: trialPublicKeys}} + = await createTrialAccountDrop({ + numKeys: 1, + contractBytes: [...readFileSync('./test/ext-wasm/trial-accounts.wasm')], + startingBalanceNEAR: 0.5, + callableContracts: callableContracts, + callableMethods: ['*'], + maxAttachableNEARPerContract: [1], + trialEndFloorNEAR: 0.33 + 0.3 + }) + + const desiredAccountId = `${dropId}-keypom.testnet` + const trialSecretKey = trialSecretKeys[0] + await claimTrialAccountDrop({ + desiredAccountId, + secretKey: trialSecretKeys[0], + }) + + console.log('desiredAccountId: ', desiredAccountId) + console.log(`trialSecretKey: ${JSON.stringify(trialSecretKey)}`) + + await trialCallMethod({ + trialAccountId: desiredAccountId, + trialAccountSecretKey: trialSecretKey, + contractId: callableContracts[0], + methodName: 'nft_mint', + args: { + token_id: 'asdkasldkjasdlkajsldajsldaskjd', + receiver_id: 'foo.testnet', + metadata: { + title: 'test', + description: 'test', + media: 'test', + } + }, + attachedDeposit: parseNearAmount('0.1'), + attachedGas: '30000000000000', + }) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `args` | `Object` | The arguments to pass to the method | +| โ€บย `attachedDeposit` | `string` | The amount of NEAR to attach to the transaction | +| โ€บย `attachedGas` | `string` | The amount of gas to attach to the transaction | +| โ€บย `contractId` | `string` | The contract ID of the contract to call | +| โ€บย `methodName` | `string` | The method name to call | +| โ€บย `trialAccountId` | `string` | The account ID of the trial account | +| โ€บย `trialAccountSecretKey` | `string` | The secret key of the trial account | + +#### Returns + +`Promise`<`FinalExecutionOutcome`[]\> + +The outcome of the transaction + +#### Defined in + +[lib/trial-accounts/trial-active.ts:248](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/trial-accounts/trial-active.ts#L248) + +___ + +### trialSignAndSendTxns + +**trialSignAndSendTxns**(`ยซdestructuredยป`): `Promise`<`FinalExecutionOutcome`[]\> + +Execute a transaction that can contain multiple actions using a trial account. If the trial account is in the exit state, this will throw an error. Similarly, if any action +cannot be executed by the trial account (e.g. the attached deposit exceeds the trial account's restrictions), this will throw an error. + +**`Example`** + +Use a Trial Account to min2 +```js +await initKeypom({ + // near, + network: 'testnet', + funder: { + accountId: fundingAccountId, + secretKey: fundingAccountSecretKey, + } + }); + + const callableContracts = [ + `nft.examples.testnet` + ] + + const {dropId, keys: {secretKeys: trialSecretKeys, publicKeys: trialPublicKeys}} + = await createTrialAccountDrop({ + numKeys: 1, + contractBytes: [...readFileSync('./test/ext-wasm/trial-accounts.wasm')], + startingBalanceNEAR: 0.5, + callableContracts: callableContracts, + callableMethods: ['*'], + maxAttachableNEARPerContract: [1], + trialEndFloorNEAR: 0.33 + 0.3 + }) + + const desiredAccountId = `${dropId}-keypom.testnet` + const trialSecretKey = trialSecretKeys[0] + await claimTrialAccountDrop({ + desiredAccountId, + secretKey: trialSecretKeys[0], + }) + + console.log('desiredAccountId: ', desiredAccountId) + console.log(`trialSecretKey: ${JSON.stringify(trialSecretKey)}`) + const txns = [{ + receiverId: callableContracts[0], + actions: [ + { + type: 'FunctionCall', + params: { + methodName: 'nft_mint', + args: { + token_id: 'tokenId-keypom-1', + receiver_id: 'foo.testnet', + metadata: { + title: 'test1', + description: 'test1', + media: 'test1', + } + }, + gas: '30000000000000', + deposit: parseNearAmount('0.1') + }, + }, + { + type: 'FunctionCall', + params: { + methodName: 'nft_mint', + args: { + token_id: 'tokenId-keypom-2', + receiver_id: 'foo.testnet', + metadata: { + title: 'test2', + description: 'test2', + media: 'test2', + } + }, + gas: '30000000000000', + deposit: parseNearAmount('0.1') + }, + }, + ], + }]; + + await trialSignAndSendTxns({ + trialAccountId: desiredAccountId, + trialAccountSecretKey: trialSecretKey, + txns + }) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `trialAccountId` | `string` | The trial account ID to use | +| โ€บย `trialAccountSecretKey` | `string` | The trial account secret key to use | +| โ€บย `txns` | `Transaction`[] | The transactions to execute | + +#### Returns + +`Promise`<`FinalExecutionOutcome`[]\> + +The outcomes of the transactions + +#### Defined in + +[lib/trial-accounts/trial-active.ts:106](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/trial-accounts/trial-active.ts#L106) + +## View Functions + +### canUserAddKeys + +**canUserAddKeys**(`ยซdestructuredยป`): `Promise`<`boolean`\> + +Check if a given user can add keys to a drop. The only case where a user *other than the funder* could add keys is if the drop has a public sale running. + +**`Example`** + +```js +await createDrop({ + numKeys: 0, + depositPerUseNEAR: 0, + config: { + sale: { + maxNumKeys: 2, + pricePerKeyNEAR: 1 + } + } +}); + +const canAddKeys = await canUserAddKeys({accountId: "foobar.testnet"}); +t.is(canAddKeys, true); +``` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `accountId` | `string` | +| โ€บย `dropId` | `string` | + +#### Returns + +`Promise`<`boolean`\> + +Whether or not the user can add keys to the drop + +#### Defined in + +[lib/views.ts:854](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L854) + +___ + +### getContractSourceMetadata + +**getContractSourceMetadata**(): `Promise`<[`ContractSourceMetadata`](interfaces/ContractSourceMetadata.md)\> + +Returns the source metadata for the Keypom contract that the SDK has been initialized on. This includes valuable information +such as which specific version the contract is on and link to exactly which GitHub commit is deployed. + +**`Example`** + +Query for the current Keypom contract's source metadata: +```js +// Initialize the SDK on testnet. No funder is passed in since we're only doing view calls. +await initKeypom({ +network: "testnet", +}); + +// Query for the Keypom contract's source metadata +const metadata = await getContractSourceMetadata(); + +console.log('metadata: ', metadata) +``` + +#### Returns + +`Promise`<[`ContractSourceMetadata`](interfaces/ContractSourceMetadata.md)\> + +The contract's source metadata + +#### Defined in + +[lib/views.ts:896](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L896) + +___ + +### getCurMethodData + +**getCurMethodData**(`ยซdestructuredยป`): `Promise`<[`ProtocolReturnedMethod`](interfaces/ProtocolReturnedMethod.md)[]\> + +Query for the current method data for a given key. This pertains to FC drops and the current method data is either null or an array of methods that will be invoked when the key is claimed next. + +**`Example`** + +```js +const fcData = { + methods: [ + null, + [ + { + methodName: "nft_token", + receiverId: "nft.examples.testnet", + args: JSON.stringify({ + token_id: "1" + }), + attachedDeposit: "0" + }, + { + methodName: "nft_token", + receiverId: "nft.examples.testnet", + args: JSON.stringify({ + token_id: "2" + }), + attachedDeposit: "0" + } + ], + null + ] +} + +const {keys: {publicKeys, secretKeys}} = await createDrop({ + numKeys: 1, + depositPerUseNEAR: 0, + fcData, + config: { + usesPerKey: 3 + } +}); +const secretKey = secretKeys[0]; + +let curMethodData = await getCurMethodData({secretKey}); +console.log('curMethodData (first): ', curMethodData) +t.is(curMethodData, null); + + curMethodData = await getCurMethodData({secretKey, keyUse: 1}); + t.is(curMethodData, null); + curMethodData = await getCurMethodData({secretKey, keyUse: 2}); + t.true(curMethodData != null); + curMethodData = await getCurMethodData({secretKey, keyUse: 3}); + t.is(curMethodData, null); + +await claim({secretKey, accountId: 'foobar'}) +curMethodData = await getCurMethodData({secretKey}); +t.true(curMethodData != null); + +await claim({secretKey, accountId: 'foobar'}) +curMethodData = await getCurMethodData({secretKey}); +console.log('curMethodData (third): ', curMethodData) +t.is(curMethodData, null); +``` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `keyUse?` | `number` | +| โ€บย `publicKey?` | `string` | +| โ€บย `secretKey?` | `string` | + +#### Returns + +`Promise`<[`ProtocolReturnedMethod`](interfaces/ProtocolReturnedMethod.md)[]\> + +The current method data for the key + +#### Defined in + +[lib/views.ts:797](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L797) + +___ + +### getDropInformation + +**getDropInformation**(`ยซdestructuredยป`): `Promise`<[`ProtocolReturnedDrop`](interfaces/ProtocolReturnedDrop.md)\> + +Get information about a specific drop by passing in either a drop ID, public key, or secret key. + +**`Example`** + +Create a simple drop and retrieve information about it: +```js +// Initialize the SDK on testnet. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Create a drop with 1 key automatically created. That key will be completely random since there is no entropy. +const {dropId} = await createDrop({ + numKeys: 1, + depositPerUseNEAR: 1 +}); + +// Query for the drop information and also return the key information as well +const dropInfo = await getDropInformation({ + dropId, + withKeys: true +}) + +console.log('dropInfo: ', dropInfo) +``` + +**`Example`** + +Create a simple drop and get the drop information based on a public key and then the secret key: +```js +// Initialize the SDK on testnet. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Create a drop with 1 key automatically created. That key will be completely random since there is no entropy. +const {keys} = await createDrop({ + numKeys: 1, + depositPerUseNEAR: 1 +}); + +// Query for the drop information and also return the key information as well +let dropInfo = await getDropInformation({ + publicKey: keys.publicKeys[0], + withKeys: true +}) + +console.log('dropInfo via public key: ', dropInfo) + +// Query for the drop information and also return the key information as well +dropInfo = await getDropInformation({ + secretKey: keys.secretKeys[0], + withKeys: true +}) + +console.log('dropInfo via secret key: ', dropInfo) +``` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `dropId?` | `string` | +| โ€บย `publicKey?` | `string` | +| โ€บย `secretKey?` | `string` | +| โ€บย `withKeys?` | `boolean` | + +#### Returns + +`Promise`<[`ProtocolReturnedDrop`](interfaces/ProtocolReturnedDrop.md)\> + +Drop information which may or may not have a keys field of type `KeyInfo` depending on if withKeys is specified as true. + +#### Defined in + +[lib/views.ts:336](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L336) + +___ + +### getDropSupplyForOwner + +**getDropSupplyForOwner**(`accountId`): `Promise`<`number`\> + +Returns the total supply of active drops for a given account ID + +**`Example`** + +Create a drop and check how many the owner has: +```js +// Initialize the SDK on testnet. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Create a drop with no keys +await createDrop({ + depositPerUseNEAR: 1 +}); + +// Query for the amount of drops owned by the account +const dropSupply = await getDropSupplyForOwner({ + accountId: "benji_demo.testnet" +}) + +console.log('dropSupply: ', dropSupply) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `accountId` | `Object` | The account that the drops belong to. | +| `accountId.accountId` | `string` | - | + +#### Returns + +`Promise`<`number`\> + +Amount of drops + +#### Defined in + +[lib/views.ts:517](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L517) + +___ + +### getDrops + +**getDrops**(`ยซdestructuredยป`): `Promise`<[`ProtocolReturnedDrop`](interfaces/ProtocolReturnedDrop.md)[]\> + +Paginate through drops owned by an account. If specified, information for the first 50 keys in each drop can be returned as well. + +**`Example`** + +Get drop information for the last 5 drops owned by a given account: +```js +// Initialize the SDK on testnet. No funder is passed in since we're only doing view calls. +await initKeypom({ + network: "testnet", +}); + +// Get the number of drops the account has. +const numDrops = await getDropSupply({ + accountId: "benjiman.testnet" +}); + +// Query for drop information for the last 5 drops and their respective keys +const dropsAndKeys = await getDrops({ + accountId: "benjiman.testnet", + start: numDrops - 5, + withKeys: true +}) + +console.log('dropsAndKeys: ', dropsAndKeys) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `accountId` | `string` | The funding account that the drops belong to. | +| โ€บย `limit` | `number` | How many drops to paginate through. | +| โ€บย `start` | `string` \| `number` | Where to start paginating through drops. | +| โ€บย `withKeys` | `boolean` | Whether or not to include key information for the first 50 keys in each drop. | + +#### Returns + +`Promise`<[`ProtocolReturnedDrop`](interfaces/ProtocolReturnedDrop.md)[]\> + +#### Defined in + +[lib/views.ts:562](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L562) + +___ + +### getKeyBalance + +**getKeyBalance**(`ยซdestructuredยป`): `Promise`<`string`\> + +Returns the balance associated a with given public key. If only the secret key is known, this can be passed in instead. This is used by the NEAR wallet to display the amount of the linkdrop + +**`Example`** + +Create a 1 $NEAR linkdrop and query for its balance: +```js +// Initialize the SDK on testnet. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Create a drop with 1 key automatically created. That key will be completely random since there is no entropy. +const {keys} = await createDrop({ + numKeys: 1, + depositPerUseNEAR: 1 +}); + +// Query for the amount of yoctoNEAR contained within the key +const keyBalance = await getKeyBalance({ + publicKey: keys.publicKeys[0] +}) + +console.log('keyBalance: ', keyBalance) +``` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `publicKey?` | `string` | +| โ€บย `secretKey?` | `string` | + +#### Returns + +`Promise`<`string`\> + +The amount of yoctoNEAR that is contained within the key + +#### Defined in + +[lib/views.ts:47](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L47) + +___ + +### getKeyInformation + +**getKeyInformation**(`ยซdestructuredยป`): `Promise`<[`ProtocolReturnedKeyInfo`](interfaces/ProtocolReturnedKeyInfo.md)\> + +Returns the KeyInfo corresponding to a specific public key + +**`Example`** + +Create a drop and query for the key information: +```js +// Initialize the SDK on testnet. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Create a drop with 1 key automatically created. That key will be completely random since there is no entropy. +const {keys} = await createDrop({ + numKeys: 1, + depositPerUseNEAR: 1 +}); + +// Query for the key information for the key that was created +const keyInfo = await getKeyInformation({ + publicKey: keys.publicKeys[0] +}) + +console.log('keyInfo: ', keyInfo) +``` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `publicKey?` | `string` | +| โ€บย `secretKey?` | `string` | + +#### Returns + +`Promise`<[`ProtocolReturnedKeyInfo`](interfaces/ProtocolReturnedKeyInfo.md)\> + +Key information struct for that specific key. + +#### Defined in + +[lib/views.ts:177](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L177) + +___ + +### getKeyInformationBatch + +**getKeyInformationBatch**(`ยซdestructuredยป`): `Promise`<[`ProtocolReturnedKeyInfo`](interfaces/ProtocolReturnedKeyInfo.md)[]\> + +Returns a vector of KeyInfo corresponding to a set of public keys passed in. + +**`Example`** + +Create a drop and query for the key information for all keys created: +```js +// Initialize the SDK on testnet. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Create a drop with 5 keys automatically created. That key will be completely random since there is no entropy. +const {keys} = await createDrop({ + numKeys: 5, + depositPerUseNEAR: 1 +}); + +// Query for the key information for the key that was created +const keyInfos = await getKeyInformationBatch({ + publicKeys: keys.publicKeys +}) + +console.log('keyInfos: ', keyInfos) +``` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `publicKeys?` | `string`[] | +| โ€บย `secretKeys?` | `string`[] | + +#### Returns + +`Promise`<[`ProtocolReturnedKeyInfo`](interfaces/ProtocolReturnedKeyInfo.md)[]\> + +Array of Key information structs for the keys passed in + +#### Defined in + +[lib/views.ts:236](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L236) + +___ + +### getKeySupplyForDrop + +**getKeySupplyForDrop**(`dropId`): `Promise`<`number`\> + +Returns the total supply of active keys for a given drop + +**`Example`** + +Create a drop with 5 keys and query for the key supply: +```js +// Initialize the SDK on testnet. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Create a drop with 5 keys automatically created. That key will be completely random since there is no entropy. +const {keys, dropId} = await createDrop({ + numKeys: 5, + depositPerUseNEAR: 1 +}); + +// Query for the key supply for the drop that was created +const keySupply = await getKeySupplyForDrop({ + dropId +}) + +console.log('keySupply: ', keySupply) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `dropId` | `Object` | The drop ID for the specific drop that you want to get information about. | +| `dropId.dropId` | `string` | - | + +#### Returns + +`Promise`<`number`\> + +Number of active keys + +#### Defined in + +[lib/views.ts:416](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L416) + +___ + +### getKeyTotalSupply + +**getKeyTotalSupply**(): `Promise`<`number`\> + +Query for the total supply of keys currently on the Keypom contract + +**`Example`** + +Query for the key supply on the `v1.keypom.testnet` contract: +```js +// Initialize the SDK on testnet. No funder is passed in since we're only doing view calls +await initKeypom({ + network: "testnet", + keypomContractId: "v1.keypom.testnet" +}); + +// Query for the number of keys on the contract +const numKeys = await getKeyTotalSupply(); + +console.log('numKeys: ', numKeys) +``` + +#### Returns + +`Promise`<`number`\> + +The amount of keys. + +#### Defined in + +[lib/views.ts:92](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L92) + +___ + +### getKeys + +**getKeys**(`ยซdestructuredยป`): `Promise`<[`ProtocolReturnedKeyInfo`](interfaces/ProtocolReturnedKeyInfo.md)[]\> + +Paginate through all active keys on the contract and return a vector of key info. + +**`Example`** + +Query for first 50 keys on the `v1.keypom.testnet` contract: +```js +// Initialize the SDK on testnet. No funder is passed in since we're only doing view calls +await initKeypom({ + network: "testnet", + keypomContractId: "v1.keypom.testnet" +}); + +// Query for the first 50 keys on the contract +const keyInfo = await getKeys({ + start: 0, + limit: 50 +}); + +console.log('keyInfo: ', keyInfo) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `limit?` | `number` | (OPTIONAL) How many keys to paginate through. | +| โ€บย `start?` | `string` \| `number` | (OPTIONAL) Where to start paginating through keys. | + +#### Returns + +`Promise`<[`ProtocolReturnedKeyInfo`](interfaces/ProtocolReturnedKeyInfo.md)[]\> + +Vector of KeyInfo. + +#### Defined in + +[lib/views.ts:126](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L126) + +___ + +### getKeysForDrop + +**getKeysForDrop**(`ยซdestructuredยป`): `Promise`<[`ProtocolReturnedKeyInfo`](interfaces/ProtocolReturnedKeyInfo.md)[]\> + +Paginate through all keys in a specific drop, returning an array of KeyInfo. + +**`Example`** + +Create a drop with 5 keys and return all the key info objects: +```js +// Initialize the SDK on testnet. +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Create a drop with 5 keys automatically created. That key will be completely random since there is no entropy. +const {dropId} = await createDrop({ + numKeys: 5, + depositPerUseNEAR: 1 +}); + +// Query for the key supply for the drop that was created +const keyInfos = await getKeysForDrop({ + dropId +}) + +console.log('keyInfos: ', keyInfos) +``` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `dropId` | `string` | +| โ€บย `limit?` | `number` | +| โ€บย `start?` | `string` \| `number` | + +#### Returns + +`Promise`<[`ProtocolReturnedKeyInfo`](interfaces/ProtocolReturnedKeyInfo.md)[]\> + +Vector of KeyInfo objects returned from pagination + +#### Defined in + +[lib/views.ts:465](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L465) + +___ + +### getNftSupplyForDrop + +**getNftSupplyForDrop**(`dropId`): `Promise`<`number`\> + +Return the total supply of token IDs for a given NFT drop. + +**`Example`** + +Query for the supply of tokens on a specific drop: +```js +// Initialize the SDK on testnet. No funder is passed in since we're only doing view calls. +await initKeypom({ +network: "testnet", +}); + +// Query for the amount of token IDs on the drop +const tokenSupply = await getNftSupplyForDrop({ + dropId: "1669840629120" +}) + +console.log('tokenSupply: ', tokenSupply) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `dropId` | `Object` | The drop ID that the tokens belong to. | +| `dropId.dropId` | `string` | - | + +#### Returns + +`Promise`<`number`\> + +The amount of token IDs on the drop + +#### Defined in + +[lib/views.ts:634](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L634) + +___ + +### getNftTokenIDsForDrop + +**getNftTokenIDsForDrop**(`ยซdestructuredยป`): `Promise`<`string`[]\> + +Paginate through token IDs in an NFT drop to return a vector of token IDs. + +**`Example`** + +Query for a list of token IDs on a specific drop: +```js +// Initialize the SDK on testnet. No funder is passed in since we're only doing view calls. +await initKeypom({ +network: "testnet", +}); + +// Query for a set of token IDs on the drop +const tokenList = await getNftTokenIDsForDrop({ + dropId: "1669840629120" +}) + +console.log('tokenList: ', tokenList) +``` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `dropId` | `string` | +| โ€บย `limit?` | `number` | +| โ€บย `start?` | `string` \| `number` | + +#### Returns + +`Promise`<`string`[]\> + +Vector of token IDs + +#### Defined in + +[lib/views.ts:673](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L673) + +___ + +### getUserBalance + +**getUserBalance**(`accountId`): `Promise`<`string`\> + +Query for a user's current balance on the Keypom contract + +**`Example`** + +Query for a user's current balance on the Keypom contract: +```js +// Initialize the SDK on testnet. No funder is passed in since we're only doing view calls. +await initKeypom({ +network: "testnet", +}); + +// Query for the drop information for a specific drop +const userBal = await getUserBalance({ +accountId: "benjiman.testnet", +}) + +console.log('userBal: ', userBal) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `accountId` | `Object` | The account ID of the user to retrieve the balance for. | +| `accountId.accountId` | `string` | - | + +#### Returns + +`Promise`<`string`\> + +The user's current balance + +#### Defined in + +[lib/views.ts:716](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/views.ts#L716) + +## Functions + +### convertBasicTransaction + +**convertBasicTransaction**(`ยซdestructuredยป`): `Promise`<`Transaction`\> + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `signerId` | `string` | +| โ€บย `signerPk` | `PublicKey` | +| โ€บย `txnInfo` | [`BasicTransaction`](interfaces/BasicTransaction.md) | + +#### Returns + +`Promise`<`Transaction`\> + +#### Defined in + +[lib/keypom-utils.ts:1445](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L1445) + +___ + +### isUnclaimedTrialDrop + +**isUnclaimedTrialDrop**(`ยซdestructuredยป`): `Promise`<`boolean`\> + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | + +#### Returns + +`Promise`<`boolean`\> + +#### Defined in + +[lib/trial-accounts/utils.ts:232](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/trial-accounts/utils.ts#L232) + +___ + +### wrapTxnParamsForTrial + +**wrapTxnParamsForTrial**(`params`, `newParams?`): `Object` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `params` | `any` | +| `newParams` | `Object` | + +#### Returns + +`Object` + +#### Defined in + +[lib/trial-accounts/utils.ts:103](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/trial-accounts/utils.ts#L103) + +## Deleting State + +### deleteDrops + +**deleteDrops**(`ยซdestructuredยป`): `Promise`<(`void` \| `FinalExecutionOutcome`[])[][]\> + +Delete a set of drops and optionally withdraw any remaining balance you have on the Keypom contract. + +**`Example`** + +Create 5 drops and delete each of them: +```js +// Initialize the SDK for the given network and NEAR connection +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// loop to create 5 simple drops each with 5 more keys than the next +for(var i = 0; i < 5; i++) { + // create 10 keys with no entropy (all random) + const {publicKeys} = await generateKeys({ + numKeys: 5 * (i+1) // First drop will have 5, then 10, then 15 etc.. + }); + + // Create the simple + await createDrop({ + publicKeys, + depositPerUseNEAR: 1, + }); +} + +let drops = await getDrops({accountId: "benji_demo.testnet"}); +console.log('drops: ', drops) + +await deleteDrops({ + drops +}) + + // Get the number of drops the account has after deletion (should be zero) + const numDrops = await getDropSupply({ + accountId: "benjiman.testnet" +}); +console.log('numDrops: ', numDrops) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `dropIds?` | `string`[] | Specify a set of drop IDs to delete. | +| โ€บย `drops?` | [`ProtocolReturnedDrop`](interfaces/ProtocolReturnedDrop.md)[] | If the set of drop information for the drops you want to delete (from `getDropInformation` or `getDrops`) is already known to the client, it can be passed in instead of the drop IDs to reduce computation. | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | +| โ€บย `withdrawBalance?` | `boolean` | Whether or not to withdraw any remaining balance on the Keypom contract. | + +#### Returns + +`Promise`<(`void` \| `FinalExecutionOutcome`[])[][]\> + +#### Defined in + +[lib/drops.ts:599](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/drops.ts#L599) + +___ + +### deleteKeys + +**deleteKeys**(`ยซdestructuredยป`): `Promise`<`any`\> + +Delete a set of keys from a drop and optionally withdraw any remaining balance you have on the Keypom contract. + +**`Example`** + +Create a drop with 5 keys and delete the first one: +```js +// Initialize the SDK for the given network and NEAR connection +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +// Create the simple drop with 5 random keys +const {keys, dropId} = await createDrop({ + numKeys: 5, + depositPerUseNEAR: 1, +}); + +await deleteKeys({ + dropId, + publicKeys: keys.publicKeys[0] // Can be wrapped in an array as well +}) +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `dropId` | `string` | Which drop ID do the keys belong to? | +| โ€บย `publicKeys` | `string` \| `string`[] | Specify a set of public keys to delete. If deleting a single publicKey, the string can be passed in without wrapping it in an array. | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | +| โ€บย `withdrawBalance?` | `boolean` | Whether or not to withdraw any remaining balance on the Keypom contract. | + +#### Returns + +`Promise`<`any`\> + +#### Defined in + +[lib/keys.ts:441](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keys.ts#L441) + +## Registering Key Uses + +### ftTransferCall + +**ftTransferCall**(`ยซdestructuredยป`): `Promise`<`Transaction` \| `Promise`<`void` \| `FinalExecutionOutcome`[]\>\> + +For FT Drops, keys need to be registered before they can be used. This is done via the `ft_transfer_call` method on the FT contract. +This is a convenience method to make that process easier. + +**`Example`** + +Send FTs using the funder account (not passing in any accounts into the call): +```js +// Initialize the SDK on testnet +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +await ftTransferCall({ + contractId: "ft.keypom.testnet", + amount: "1", + dropId: "1231231", +)}; +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `absoluteAmount?` | `string` | Amount of tokens to transfer but considering the decimal amount (non human-readable). Example: transferring one wNEAR should be passed in as "1000000000000000000000000" and NOT "1" | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `amount?` | `string` | Human readable format for the amount of tokens to transfer. Example: transferring one wNEAR should be passed in as "1" and NOT "1000000000000000000000000" | +| โ€บย `contractId` | `string` | The fungible token contract ID. | +| โ€บย `dropId` | `string` | The drop ID to register the keys for. | +| โ€บย `returnTransaction?` | `boolean` | If true, the transaction will be returned instead of being signed and sent. | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<`Transaction` \| `Promise`<`void` \| `FinalExecutionOutcome`[]\>\> + +#### Defined in + +[lib/keypom-utils.ts:797](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L797) + +___ + +### nftTransferCall + +**nftTransferCall**(`ยซdestructuredยป`): `Promise`<`Transaction`[] \| (`void` \| `FinalExecutionOutcome`[])[]\> + +For NFT Drops, keys need to be registered before they can be used. This is done via the `nft_transfer_call` method on the NFT contract. +This is a convenience method to make that process easier. + +**`Example`** + +Send 3 NFTs using the funder account (not passing in any accounts into the call): +```js +// Initialize the SDK on testnet +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +await nftTransferCall({ + contractId: "nft.keypom.testnet", + tokenIds: ["1", "2", "3], + dropId: "1231231", +)}; +``` + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `ยซdestructuredยป` | `Object` | - | +| โ€บย `account?` | `Account` | Account object that if passed in, will be used to sign the txn instead of the funder account. | +| โ€บย `contractId` | `string` | The non-fungible token contract ID. | +| โ€บย `dropId` | `string` | The drop ID to register the keys for. | +| โ€บย `returnTransactions?` | `boolean` | If true, the transaction will be returned instead of being signed and sent. | +| โ€บย `tokenIds` | `string`[] | A set of token IDs that should be sent to the Keypom contract in order to register keys. | +| โ€บย `wallet?` | `AnyWallet` | If using a browser wallet through wallet selector and that wallet should sign the transaction, pass in the object. | + +#### Returns + +`Promise`<`Transaction`[] \| (`void` \| `FinalExecutionOutcome`[])[]\> + +#### Defined in + +[lib/keypom-utils.ts:906](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/core/src/lib/keypom-utils.ts#L906) diff --git a/versioned_docs/version-2.0/keypom-sdk/Core/welcome.md b/versioned_docs/version-2.0/keypom-sdk/Core/welcome.md new file mode 100644 index 00000000..3fcc11a5 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Core/welcome.md @@ -0,0 +1,216 @@ +--- +id: "welcome" +title: "@keypom/core - v1.0.2" +sidebar_label: "Readme" +sidebar_position: 0 +custom_edit_url: null +--- + +

+ + + + +

Keypom Core SDK

+ +

+ +

+ + + + + + + + + + + + +

+ +The core package serves as a way to interact with Keypom through a set of easy to use methods that abstract away the complexities of the protocol. The package includes ways to: +- Create drops of all kinds +- Claim drops +- Create and use trial accounts +- View information about drops and keys +- Delete drops and refund assets +- Manage user balances + +# Table of Contents +- [Table of Contents](#table-of-contents) +- [Installation](#installation) +- [Getting Started](#getting-started) + - [View Methods \& Utility Functions Only](#view-methods--utility-functions-only) + - [Funder Object](#funder-object) + - [Customized KeyStore \& Multiple Signers](#customized-keystore--multiple-signers) +- [Costs](#costs) + - [Per Drop](#per-drop) + - [Per Key](#per-key) + - [Key Costs for Simple Drop](#key-costs-for-simple-drop) + - [Additional Costs for NFT Drops](#additional-costs-for-nft-drops) + - [Additional Costs for FT Drops](#additional-costs-for-ft-drops) + - [Additional Costs for FC Drops](#additional-costs-for-fc-drops) +- [Contributing](#contributing) +- [License](#license) + +--- + +# Installation + +To install the Keypom Core SDK, run the following command: + +```bash +npm install @keypom/core +# or +yarn add @keypom/core +# or +pnpm add @keypom/core +``` + +# Getting Started + +The first thing you must *always* do when using the SDK is to call `initKeypom`. This will initialize the package state and establish a connection to the NEAR blockchain. + +By default, the SDK will create a new [InMemoryKeyStore](https://github.com/near/near-api-js/blob/master/packages/keystores/src/in_memory_key_store.ts) to sign transactions with. Thus, if you don't pass in a `funder` object, you won't be able to sign transactions and can only invoke utility and view methods. Alternatively, if you'd like to use a different keystore, you can pass in a customized `near` object to the initialization function. + +With the SDK, every function that requires transactions to be signed can be carried through in 1 of two ways: +1. Passing in an [Account](https://github.com/near/near-api-js/blob/master/packages/accounts/src/account.ts) object into the function whose keys are kept in the SDK's keystore. +2. Passing in a `funder` object once during initialization whose keys will be kept in the SDK's [InMemoryKeyStore](https://github.com/near/near-api-js/blob/master/packages/keystores/src/in_memory_key_store.ts). + +## View Methods & Utility Functions Only + +If your only purpose is to query information from the chain or use Keypom's utility functions such as `generateKeys`, you don't need to pass in a `near` or `funder` object to `initKeypom`: + +```js +await initKeypom({ + network: "testnet" +}); + +const keys = await generateKeys({ + numKeys: 1 +}) +console.log('keys: ', keys) + +const dropSupply = await getKeyTotalSupply(); +console.log('dropSupply: ', dropSupply) +``` + +## Funder Object + +If you have the private key of an account that you'd like to use to sign transactions with, you can pass in a `funder` object to `initKeypom`. The private key can either be hardcoded or passed in through environment variables / secrets. + +Using this method, you only need to pass the funder object once on initialization and can freely invoke any of the SDK methods moving forward. To update the funder object, you can call `updateFunder` and pass in different information. + +```js +await initKeypom({ + network: "testnet", + funder: { + accountId: "benji_demo.testnet", + secretKey: "ed25519:5yARProkcALbxaSQ66aYZMSBPWL9uPBmkoQGjV3oi2ddQDMh1teMAbz7jqNV9oVyMy7kZNREjYvWPqjcA6LW9Jb1" + } +}); + +const dropSupply = await getKeyTotalSupply(); +console.log('dropSupply: ', dropSupply) + +const {keys} = await createDrop({ + numKeys: 1, + depositPerUseNEAR: 1 +}) +console.log('keys: ', keys) +``` + +## Customized KeyStore & Multiple Signers + +Passing in a custom `near` object when initializing Keypom has several benefits as seen below: +- If you have multiple accounts that will be signing transactions and don't want to keep calling `updateFunder`. +- You don't want to hardcode the private key in the `funder` object. +- You have a keystore containing keys that will be used to sign transactions already in scope. + +In this case, you can pass in an existing `near` object and then pass in `Account` objects when calling the SDK methods. + +```js +let keyStore = new UnencryptedFileSystemKeyStore(credentialsPath); +let nearConfig = { + networkId: NETWORK_ID, + keyStore: keyStore, + nodeUrl: `https://rpc.${NETWORK_ID}.near.org`, + walletUrl: `https://wallet.${NETWORK_ID}.near.org`, + helperUrl: `https://helper.${NETWORK_ID}.near.org`, + explorerUrl: `https://explorer.${NETWORK_ID}.near.org`, +}; +let near = new Near(nearConfig); + +await initKeypom({ + near +}); + +const dropSupply = await getKeyTotalSupply(); +console.log('dropSupply: ', dropSupply) + +const fundingAccount = new Account(near.connection, funderAccountId); +const {keys} = await createDrop({ + account: fundingAccount, + numKeys: 1, + depositPerUseNEAR: 1 +}) +console.log('keys: ', keys) +``` + +# Costs + +It is important to note that the Keypom contracts are 100% **FEE FREE** and will remain that way for the *foreseeable future*. These contracts are a public good and are meant to inspire change in the NEAR ecosystem. + +With that being said, there are several mandatory costs that must be taken into account when using Keypom. These costs are broken down into two categories: per key and per drop. + +> **NOTE:** Creating an empty drop and then adding 100 keys in separate calls will incur the same cost as creating a drop with 100 keys in the same call. + +## Per Drop + +When creating an empty drop, there is only one cost to keep in mind regardless of the drop type: +- Storage cost (**~0.006 $NEAR** for simple drops) + +## Per Key +Whenever keys are added to a drop (either when the drop is first created or at a later date), the costs are outlined below. + +### Key Costs for Simple Drop + +- $NEAR sent whenever the key is used (can be 0). +- Access key allowance (**~0.0187 $NEAR per use**). +- Storage for creating access key (**0.001 $NEAR**). +- Storage cost (**~0.006 $NEAR** for simple drops) + +### Additional Costs for NFT Drops + +Since keys aren't registered for use until **after** the contract has received the NFT, we don't know how much storage the token IDs will use on the contract. To combat this, the Keypom contract will automatically measure the storage used up for storing each token ID in the `nft_on_transfer` function and that $NEAR will be taken from the funder's balance. + +### Additional Costs for FT Drops + +Since accounts claiming FTs may or may not be registered on the Fungible Token contract, Keypom will automatically try to register **all** accounts. This means that the drop creators must front the cost of registering users depending on the `storage_balance_bounds` returned from the FT contract. This applies to every use for every key. + +In addition, Keypom must be registered on the FT contract. If you create a FT drop and are the first person to ever do so for a specific FT contract on Keypom, Keypom will be automatically registered when the drop is created. This is a one time cost and once it is done, no other account will need to register Keypom for that specific FT contract. + +### Additional Costs for FC Drops + +Drop creators have a ton of customization available to them when creation Function Call drops. A cost that they might incur is the attached deposit being sent alongside the function call. Keypom will charge creators for all the attached deposits they specify. + +> **NOTE:** The storage costs are dynamically calculated and will vary depending on the information you store on-chain. + +# Contributing + +First off, thanks for taking the time to contribute! Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are **greatly appreciated**. + +Please try to create bug reports that are: + +- _Reproducible._ Include steps to reproduce the problem. +- _Specific._ Include as much detail as possible: which version, what environment, etc. +- _Unique._ Do not duplicate existing opened issues. +- _Scoped to a Single Bug._ One bug per report. + +You can use [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) to check for common markdown style inconsistency. + +# License + +This project is licensed under the **GPL License**. diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/_category_.yml b/versioned_docs/version-2.0/keypom-sdk/Selector/_category_.yml new file mode 100644 index 00000000..368d9d7e --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/_category_.yml @@ -0,0 +1,3 @@ +label: "Selector TypeDocs" +position: 0 +collapsed: false \ No newline at end of file diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/classes/KeypomWallet.md b/versioned_docs/version-2.0/keypom-sdk/Selector/classes/KeypomWallet.md new file mode 100644 index 00000000..b105c864 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/classes/KeypomWallet.md @@ -0,0 +1,465 @@ +--- +id: "KeypomWallet" +title: "Class: KeypomWallet" +sidebar_label: "KeypomWallet" +sidebar_position: 0 +custom_edit_url: null +--- + +## Implements + +- `InstantLinkWalletBehaviour` + +## Constructors + +### constructor + +**new KeypomWallet**(`ยซdestructuredยป`) + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `instantSignInSpecs?` | `InstantSignInSpecs` | +| โ€บย `networkId` | `string` | +| โ€บย `signInContractId` | `string` | +| โ€บย `trialAccountSpecs?` | `TrialSignInSpecs` | + +#### Defined in + +[core/wallet.ts:33](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L33) + +## Properties + +### accountId + + `Optional` **accountId**: `string` + +#### Defined in + +[core/wallet.ts:19](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L19) + +___ + +### instantSignInSpecs + + `Optional` **instantSignInSpecs**: `InternalInstantSignInSpecs` + +#### Defined in + +[core/wallet.ts:29](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L29) + +___ + +### keyStore + + **keyStore**: `BrowserLocalStorageKeyStore` + +#### Defined in + +[core/wallet.ts:26](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L26) + +___ + +### modal + + `Optional` **modal**: `KeypomTrialModal` + +#### Defined in + +[core/wallet.ts:31](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L31) + +___ + +### moduleId + + `Optional` **moduleId**: `string` + +#### Defined in + +[core/wallet.ts:21](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L21) + +___ + +### near + + **near**: `Near` + +#### Defined in + +[core/wallet.ts:25](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L25) + +___ + +### secretKey + + `Optional` **secretKey**: `string` + +#### Defined in + +[core/wallet.ts:20](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L20) + +___ + +### signInContractId + + **signInContractId**: `string` + +#### Defined in + +[core/wallet.ts:23](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L23) + +___ + +### trialAccountSpecs + + `Optional` **trialAccountSpecs**: `InternalTrialSignInSpecs` + +#### Defined in + +[core/wallet.ts:28](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L28) + +## Methods + +### assertSignedIn + +`Private` **assertSignedIn**(): `void` + +#### Returns + +`void` + +#### Defined in + +[core/wallet.ts:337](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L337) + +___ + +### checkValidTrialInfo + +**checkValidTrialInfo**(): `boolean` + +#### Returns + +`boolean` + +#### Defined in + +[core/wallet.ts:287](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L287) + +___ + +### getAccountId + +**getAccountId**(): `string` + +#### Returns + +`string` + +#### Defined in + +[core/wallet.ts:63](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L63) + +___ + +### getAccounts + +**getAccounts**(): `Promise`<`Account`[]\> + +#### Returns + +`Promise`<`Account`[]\> + +#### Implementation of + +InstantLinkWalletBehaviour.getAccounts + +#### Defined in + +[core/wallet.ts:306](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L306) + +___ + +### getAvailableBalance + +**getAvailableBalance**(`id?`): `Promise`<`BN`\> + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `id?` | `string` | + +#### Returns + +`Promise`<`BN`\> + +#### Defined in + +[core/wallet.ts:301](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L301) + +___ + +### getContractId + +**getContractId**(): `string` + +#### Returns + +`string` + +#### Implementation of + +InstantLinkWalletBehaviour.getContractId + +#### Defined in + +[core/wallet.ts:59](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L59) + +___ + +### internalSignIn + +`Private` **internalSignIn**(`accountId`, `secretKey`, `moduleId`): `Promise`<`Account`[]\> + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `accountId` | `any` | +| `secretKey` | `any` | +| `moduleId` | `any` | + +#### Returns + +`Promise`<`Account`[]\> + +#### Defined in + +[core/wallet.ts:319](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L319) + +___ + +### isSignedIn + +**isSignedIn**(): `Promise`<`boolean`\> + +#### Returns + +`Promise`<`boolean`\> + +#### Defined in + +[core/wallet.ts:68](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L68) + +___ + +### setSpecsFromKeypomParams + +`Private` **setSpecsFromKeypomParams**(`ยซdestructuredยป`): `void` + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `Object` | +| โ€บย `instantSignInSpecs?` | `InstantSignInSpecs` | +| โ€บย `shouldSetupModal` | `boolean` | +| โ€บย `trialAccountSpecs?` | `TrialSignInSpecs` | + +#### Returns + +`void` + +#### Defined in + +[core/wallet.ts:343](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L343) + +___ + +### showModal + +**showModal**(`modalType?`): `void` + +#### Parameters + +| Name | Type | Default value | +| :------ | :------ | :------ | +| `modalType` | `Object` | `undefined` | +| `modalType.id` | `string` | `MODAL_TYPE_IDS.TRIAL_OVER` | + +#### Returns + +`void` + +#### Defined in + +[core/wallet.ts:282](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L282) + +___ + +### signAndSendTransaction + +**signAndSendTransaction**(`params`): `Promise`<`FinalExecutionOutcome`\> + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `params` | `any` | + +#### Returns + +`Promise`<`FinalExecutionOutcome`\> + +#### Implementation of + +InstantLinkWalletBehaviour.signAndSendTransaction + +#### Defined in + +[core/wallet.ts:201](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L201) + +___ + +### signAndSendTransactions + +**signAndSendTransactions**(`params`): `Promise`<`FinalExecutionOutcome`[]\> + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `params` | `Object` | +| `params.transactions` | `Transaction`[] | + +#### Returns + +`Promise`<`FinalExecutionOutcome`[]\> + +#### Implementation of + +InstantLinkWalletBehaviour.signAndSendTransactions + +#### Defined in + +[core/wallet.ts:225](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L225) + +___ + +### signIn + +**signIn**(): `Promise`<`Account`[]\> + +#### Returns + +`Promise`<`Account`[]\> + +#### Implementation of + +InstantLinkWalletBehaviour.signIn + +#### Defined in + +[core/wallet.ts:147](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L147) + +___ + +### signInInstantAccount + +**signInInstantAccount**(`accountId`, `secretKey`, `moduleId`): `Promise`<`Account`[]\> + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `accountId` | `any` | +| `secretKey` | `any` | +| `moduleId` | `any` | + +#### Returns + +`Promise`<`Account`[]\> + +#### Defined in + +[core/wallet.ts:128](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L128) + +___ + +### signInTrialAccount + +**signInTrialAccount**(`accountId`, `secretKey`): `Promise`<`Account`[]\> + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `accountId` | `any` | +| `secretKey` | `any` | + +#### Returns + +`Promise`<`Account`[]\> + +#### Defined in + +[core/wallet.ts:72](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L72) + +___ + +### signOut + +**signOut**(): `Promise`<`void`\> + +#### Returns + +`Promise`<`void`\> + +#### Implementation of + +InstantLinkWalletBehaviour.signOut + +#### Defined in + +[core/wallet.ts:191](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L191) + +___ + +### switchAccount + +**switchAccount**(`id`): `Promise`<`void`\> + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `id` | `string` | + +#### Returns + +`Promise`<`void`\> + +#### Defined in + +[core/wallet.ts:315](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L315) + +___ + +### verifyOwner + +**verifyOwner**(): `Promise`<`void`\> + +#### Returns + +`Promise`<`void`\> + +#### Implementation of + +InstantLinkWalletBehaviour.verifyOwner + +#### Defined in + +[core/wallet.ts:295](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/wallet.ts#L295) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/classes/_category_.yml b/versioned_docs/version-2.0/keypom-sdk/Selector/classes/_category_.yml new file mode 100644 index 00000000..55c7980a --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/classes/_category_.yml @@ -0,0 +1,2 @@ +label: "Classes" +position: 3 \ No newline at end of file diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/BasicTransaction.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/BasicTransaction.md new file mode 100644 index 00000000..83586f31 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/BasicTransaction.md @@ -0,0 +1,37 @@ +--- +id: "BasicTransaction" +title: "Interface: BasicTransaction" +sidebar_label: "BasicTransaction" +sidebar_position: 0 +custom_edit_url: null +--- + +## Properties + +### actions + + **actions**: `Action`[] + +#### Defined in + +[lib/types/general.ts:108](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L108) + +___ + +### receiverId + + **receiverId**: `string` + +#### Defined in + +[lib/types/general.ts:106](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L106) + +___ + +### signerId + + **signerId**: `string` + +#### Defined in + +[lib/types/general.ts:107](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L107) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ContractSourceMetadata.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ContractSourceMetadata.md new file mode 100644 index 00000000..1f98bad4 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ContractSourceMetadata.md @@ -0,0 +1,34 @@ +--- +id: "ContractSourceMetadata" +title: "Interface: ContractSourceMetadata" +sidebar_label: "ContractSourceMetadata" +sidebar_position: 0 +custom_edit_url: null +--- + +Information returned from `getContractSourceMetadata` about the deployed Keypom contract. This is part of [NEP-330](https://nomicon.io/Standards/SourceMetadata) and +can allow you to view exactly what code is deployed to the contract. + +## Properties + +### link + + **link**: `string` + +Link to the specific commit and code on GitHub that is deployed to the Keypom account + +#### Defined in + +[lib/types/general.ts:102](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L102) + +___ + +### version + + **version**: `string` + +Versioning used by the Keypom developers to indicate which version of the contract is deployed. + +#### Defined in + +[lib/types/general.ts:100](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L100) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/CreateDropProtocolArgs.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/CreateDropProtocolArgs.md new file mode 100644 index 00000000..628606b8 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/CreateDropProtocolArgs.md @@ -0,0 +1,117 @@ +--- +id: "CreateDropProtocolArgs" +title: "Interface: CreateDropProtocolArgs" +sidebar_label: "CreateDropProtocolArgs" +sidebar_position: 0 +custom_edit_url: null +--- + +## Properties + +### config + + `Optional` **config**: [`ProtocolReturnedDropConfig`](ProtocolReturnedDropConfig.md) + +#### Defined in + +[lib/types/params.ts:54](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L54) + +___ + +### deposit\_per\_use + + **deposit\_per\_use**: `string` + +#### Defined in + +[lib/types/params.ts:51](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L51) + +___ + +### drop\_id + + `Optional` **drop\_id**: `string` + +#### Defined in + +[lib/types/params.ts:53](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L53) + +___ + +### fc + + `Optional` **fc**: [`ProtocolReturnedFCData`](ProtocolReturnedFCData.md) + +#### Defined in + +[lib/types/params.ts:60](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L60) + +___ + +### ft + + `Optional` **ft**: [`ProtocolReturnedFTData`](ProtocolReturnedFTData.md) + +#### Defined in + +[lib/types/params.ts:58](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L58) + +___ + +### metadata + + `Optional` **metadata**: `string` + +#### Defined in + +[lib/types/params.ts:55](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L55) + +___ + +### nft + + `Optional` **nft**: [`ProtocolReturnedNFTData`](ProtocolReturnedNFTData.md) + +#### Defined in + +[lib/types/params.ts:59](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L59) + +___ + +### passwords\_per\_use + + `Optional` **passwords\_per\_use**: [`PasswordPerUse`](PasswordPerUse.md)[][] + +#### Defined in + +[lib/types/params.ts:61](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L61) + +___ + +### public\_keys + + `Optional` **public\_keys**: `string`[] + +#### Defined in + +[lib/types/params.ts:50](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L50) + +___ + +### required\_gas + + `Optional` **required\_gas**: `string` + +#### Defined in + +[lib/types/params.ts:56](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L56) + +___ + +### simple + + `Optional` **simple**: [`ProtocolReturnedSimpleData`](ProtocolReturnedSimpleData.md) + +#### Defined in + +[lib/types/params.ts:57](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L57) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/CreateOrAddReturn.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/CreateOrAddReturn.md new file mode 100644 index 00000000..098ae1bc --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/CreateOrAddReturn.md @@ -0,0 +1,69 @@ +--- +id: "CreateOrAddReturn" +title: "Interface: CreateOrAddReturn" +sidebar_label: "CreateOrAddReturn" +sidebar_position: 0 +custom_edit_url: null +--- + +Information returned when creating a drop or adding keys via `createDrop` and `addKeys` respectively. + +## Properties + +### dropId + + **dropId**: `string` + +The drop ID for the drop that is being interacted with. + +#### Defined in + +[lib/types/params.ts:34](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L34) + +___ + +### keys + + `Optional` **keys**: [`GeneratedKeyPairs`](GeneratedKeyPairs.md) + +Any keys that were automatically generated. + +#### Defined in + +[lib/types/params.ts:32](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L32) + +___ + +### requiredDeposit + + `Optional` **requiredDeposit**: `string` + +The required deposit that should be attached to the transaction. + +#### Defined in + +[lib/types/params.ts:30](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L30) + +___ + +### responses + + `Optional` **responses**: `any` + +The responses to any transactions that were signed and sent to the network. + +#### Defined in + +[lib/types/params.ts:26](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L26) + +___ + +### transactions + + `Optional` **transactions**: `Transaction`[] + +Information about the transactions if `returnTransactions` is specified in the arguments. This will result in the information being returned instead of signed and sent. + +#### Defined in + +[lib/types/params.ts:28](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/params.ts#L28) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/Drop.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/Drop.md new file mode 100644 index 00000000..906fde01 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/Drop.md @@ -0,0 +1,153 @@ +--- +id: "Drop" +title: "Interface: Drop" +sidebar_label: "Drop" +sidebar_position: 0 +custom_edit_url: null +--- + +Information related to a specific drop. + +## Properties + +### config + + `Optional` **config**: [`DropConfig`](DropConfig.md) + +All drops regardless of their type can have a suite of configurations such as how many uses each key has or how often a key can be used. + +#### Defined in + +[lib/types/drops.ts:50](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L50) + +___ + +### depositPerUse + + **depositPerUse**: `string` + +How much $yoctoNEAR will be transferred anytime a key is used that is part of this drop. + +#### Defined in + +[lib/types/drops.ts:40](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L40) + +___ + +### dropId + + **dropId**: `string` + +Drop ID for this specific drop. + +#### Defined in + +[lib/types/drops.ts:36](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L36) + +___ + +### fc + + `Optional` **fc**: [`FCData`](FCData.md) + +For Function-Call drops, important information needs to be stored such as which methods, the attached deposit, args etc. + +#### Defined in + +[lib/types/drops.ts:48](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L48) + +___ + +### ft + + `Optional` **ft**: [`FTData`](FTData.md) + +For Fungible Token drops, important information such as the amount of tokens to transfer, or contract need to be stored. + +#### Defined in + +[lib/types/drops.ts:46](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L46) + +___ + +### metadata + + `Optional` **metadata**: `string` + +Any extra information about the drop can be stored as metadata. This is up to the drop creator and can be stringified JSON, or any other string. + +#### Defined in + +[lib/types/drops.ts:52](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L52) + +___ + +### nextKeyId + + **nextKeyId**: `number` + +What is the next unique ID that will be given to the next access key added to this drop. + +#### Defined in + +[lib/types/drops.ts:58](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L58) + +___ + +### nft + + `Optional` **nft**: [`NFTData`](NFTData.md) + +For NFT drops, important information such as the token IDs, or contract need to be stored. + +#### Defined in + +[lib/types/drops.ts:44](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L44) + +___ + +### ownerId + + **ownerId**: `string` + +Which account created this drop. + +#### Defined in + +[lib/types/drops.ts:38](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L38) + +___ + +### registeredUses + + **registeredUses**: `number` + +How many key uses are registered for this drop? This is only applicable to simple drops with lazy registrations, FT drops, and NFT drops. + +#### Defined in + +[lib/types/drops.ts:54](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L54) + +___ + +### requiredGas + + **requiredGas**: `string` + +In order to use an access key that's part of this drop, how much Gas *needs* to be attached to the call? + +#### Defined in + +[lib/types/drops.ts:56](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L56) + +___ + +### simple + + `Optional` **simple**: [`SimpleData`](SimpleData.md) + +For simple drops, there are specific, optional configurations. + +#### Defined in + +[lib/types/drops.ts:42](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L42) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/DropConfig.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/DropConfig.md new file mode 100644 index 00000000..caf9f428 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/DropConfig.md @@ -0,0 +1,71 @@ +--- +id: "DropConfig" +title: "Interface: DropConfig" +sidebar_label: "DropConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Configurable options for any drop regardless of type. + +## Properties + +### dropRoot + + `Optional` **dropRoot**: `string` + +Override the global root account that all created sub-accounts will have (currently `near` or `testnet`). This allows users to drops that have a custom root. +For example, Fayyr could specify a root of `fayyr.near` By which all sub-accounts will then be `ACCOUNT.fayyr.near`. +It's important to note that this root account *MUST* have a smart contract deployed that has a method `create_account`. + +#### Defined in + +[lib/types/drops.ts:81](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L81) + +___ + +### sale + + `Optional` **sale**: [`PublicSaleConfig`](PublicSaleConfig.md) + +Any information related to primary market sales for access keys added to this drop. + +#### Defined in + +[lib/types/drops.ts:75](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L75) + +___ + +### time + + `Optional` **time**: [`TimeConfig`](TimeConfig.md) + +Any information related to time-based configurations such as a starting date for keys etc. + +#### Defined in + +[lib/types/drops.ts:69](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L69) + +___ + +### usage + + `Optional` **usage**: [`UsageConfig`](UsageConfig.md) + +Any information related to how access keys are used such as which methods they can call or whether an empty drop should be automatically deleted etc. + +#### Defined in + +[lib/types/drops.ts:72](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L72) + +___ + +### usesPerKey + + `Optional` **usesPerKey**: `number` + +How many uses can each key have before it's deleted. If this isn't specified, it defaults to 1 use per key. + +#### Defined in + +[lib/types/drops.ts:66](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L66) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/EnvVars.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/EnvVars.md new file mode 100644 index 00000000..f4334f13 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/EnvVars.md @@ -0,0 +1,223 @@ +--- +id: "EnvVars" +title: "Interface: EnvVars" +sidebar_label: "EnvVars" +sidebar_position: 0 +custom_edit_url: null +--- + +Important context that is used throughout the SDK. This is generated when `initKeypom` is called and can be retrieved by calling `useKeypom`. +All parameters will start off as undefined until the Keypom SDK is initialized. + +## Properties + +### attachedGas + + `Optional` **attachedGas**: `string` + +The amount of Gas that will be attached to the `claim` and `create_account_and_claim` functions for claiming linkdrops (100 TGas). + +#### Defined in + +[lib/types/general.ts:77](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L77) + +___ + +### connection + + `Optional` **connection**: `Connection` + +The connection instance that is part of the NEAR object + +#### Defined in + +[lib/types/general.ts:59](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L59) + +___ + +### contractAccount + + `Optional` **contractAccount**: `Account` + +The NEAR Account object for the Keypom contract being used. This lets you know the account ID for the contract and can be used to sign transactions for claiming linkdrops. + +#### Defined in + +[lib/types/general.ts:69](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L69) + +___ + +### contractId + + `Optional` **contractId**: `string` + +The account ID where the Keypom contract is deployed to. + +#### Defined in + +[lib/types/general.ts:79](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L79) + +___ + +### error + + `Optional` **error**: `string` + +#### Defined in + +[lib/types/general.ts:83](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L83) + +___ + +### execute + + `Optional` **execute**: `any` + +#### Defined in + +[lib/types/general.ts:87](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L87) + +___ + +### fundingAccount + + `Optional` **fundingAccount**: `Account` + +The NEAR Account object for the Funder + +#### Defined in + +[lib/types/general.ts:65](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L65) + +___ + +### fundingAccountDetails + + `Optional` **fundingAccountDetails**: [`Funder`](Funder.md) + +The details for the funder such as any `rootEntropy` or their `secretKey` etc. + +#### Defined in + +[lib/types/general.ts:67](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L67) + +___ + +### gas + + `Optional` **gas**: `string` + +The default amount of Gas that will be attached to transactions (200 TGas). + +#### Defined in + +[lib/types/general.ts:73](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L73) + +___ + +### gas300 + + `Optional` **gas300**: `string` + +The max amount of Gas that will be attached to transactions (300 TGas). + +#### Defined in + +[lib/types/general.ts:75](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L75) + +___ + +### getAccount + + `Optional` **getAccount**: `any` + +#### Defined in + +[lib/types/general.ts:85](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L85) + +___ + +### keyStore + + `Optional` **keyStore**: `KeyStore` + +Which type of KeyStore is used when locating keys and signing transactions throughout the SDK (In Memory, Unencrypted FileStore etc.) + +#### Defined in + +[lib/types/general.ts:61](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L61) + +___ + +### near + + `Optional` **near**: `Near` + +The specific NEAR object that contains important information such as the KeyStore and connection. This is used to interact with the chain and can either be manually passed in or will be automatically created during `initKeypom` + +#### Defined in + +[lib/types/general.ts:57](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L57) + +___ + +### networkId + + `Optional` **networkId**: `string` + +What network is the SDK using (`testnet` or `mainnet`) + +#### Defined in + +[lib/types/general.ts:63](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L63) + +___ + +### receiverId + + `Optional` **receiverId**: `string` + +#### Defined in + +[lib/types/general.ts:81](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L81) + +___ + +### supportedKeypomContracts + + `Optional` **supportedKeypomContracts**: `Object` + +Object containing the supported Keypom contracts for both mainnet and testnet + +#### Type declaration + +| Name | Type | +| :------ | :------ | +| `mainnet` | {} | +| `testnet` | {} | + +#### Defined in + +[lib/types/general.ts:89](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L89) + +___ + +### viewAccount + + `Optional` **viewAccount**: `any` + +#### Defined in + +[lib/types/general.ts:71](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L71) + +___ + +### viewCall + + `Optional` **viewCall**: `any` + +Function that allows you to invoke a view method. This takes in a `receiverId`, `methodName`, and `args`. + +#### Defined in + +[lib/types/general.ts:91](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L91) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/FCData.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/FCData.md new file mode 100644 index 00000000..8a814cde --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/FCData.md @@ -0,0 +1,22 @@ +--- +id: "FCData" +title: "Interface: FCData" +sidebar_label: "FCData" +sidebar_position: 0 +custom_edit_url: null +--- + +Information pertaining to all Function-Call drops. This should be passed in if the drop will be a Function-Call drop. + +## Properties + +### methods + + **methods**: [`Method`](Method.md)[][] + +The top level array indicates a different set of methods that can be called for every key use. It is possible that for a given key use, no methods are called thus acting as a "free" key use whereby the use is reflected on-chain but no assets are transferred. +If a given key use does not have an undefined set of methods, when it is used, all the methods in the set will be called. + +#### Defined in + +[lib/types/fc.ts:73](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/fc.ts#L73) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/FTData.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/FTData.md new file mode 100644 index 00000000..2b0726d5 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/FTData.md @@ -0,0 +1,59 @@ +--- +id: "FTData" +title: "Interface: FTData" +sidebar_label: "FTData" +sidebar_position: 0 +custom_edit_url: null +--- + +Information pertaining to all Fungible-Token drops. This should be passed in if the drop will be used to transfer any fungible tokens. + +## Properties + +### absoluteAmount + + `Optional` **absoluteAmount**: `string` + +Amount of tokens to transfer but considering the decimal amount. +Example: transferring one wNEAR should be passed in as "1000000000000000000000000" and NOT "1" + +#### Defined in + +[lib/types/ft.ts:22](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/ft.ts#L22) + +___ + +### amount + + `Optional` **amount**: `string` + +Human readable format for the amount of tokens to transfer every time the FT key is used. +Example: transferring one wNEAR should be passed in as "1" and NOT "1000000000000000000000000" + +#### Defined in + +[lib/types/ft.ts:17](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/ft.ts#L17) + +___ + +### contractId + + **contractId**: `string` + +Which contract do the FTs belong to? + +#### Defined in + +[lib/types/ft.ts:8](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/ft.ts#L8) + +___ + +### senderId + + `Optional` **senderId**: `string` + +By default, anyone can fund your drop with FTs. This field allows you to set a specific account ID that will be locked into sending the FTs. + +#### Defined in + +[lib/types/ft.ts:12](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/ft.ts#L12) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/Funder.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/Funder.md new file mode 100644 index 00000000..6230c715 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/Funder.md @@ -0,0 +1,75 @@ +--- +id: "Funder" +title: "Interface: Funder" +sidebar_label: "Funder" +sidebar_position: 0 +custom_edit_url: null +--- + +Outlines how the structure of the *funder* object should be passed into `initKeypom` or `updateFunder`. This contains important information such as the +secret key, account ID and any root entropy associated with the account. + +**`Throws`** + +if neither `secretKey` or `seedPhrase` are provided. One of these need to be passed in. + +## Properties + +### accountId + + **accountId**: `string` + +The account ID of the funder that will be used to sign transactions. + +#### Defined in + +[lib/types/general.ts:35](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L35) + +___ + +### fundingKeyPair + + `Optional` **fundingKeyPair**: `KeyPair` + +#### Defined in + +[lib/types/general.ts:48](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L48) + +___ + +### rootEntropy + + `Optional` **rootEntropy**: `string` + +When interacting with the SDK, there are several places where KeyPairs can be generated automatically rather than you having to pass them in. +For example, during `createDrop` and `addKeys`, if `publicKeys` isn't passed in, the SDK will generate `numKeys` number of keys automatically. +These generated keys can either be completely random or deterministically generated based off some entropy. If `rootEntropy` is provided, all the +keys that are auto-generated will be based off this entropy. + +#### Defined in + +[lib/types/general.ts:46](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L46) + +___ + +### secretKey + + `Optional` **secretKey**: `string` + +A valid private key associated with the funder's account. This can be function-call or full access (depending on what limitations and security measures are in place). + +#### Defined in + +[lib/types/general.ts:37](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L37) + +___ + +### seedPhrase + + `Optional` **seedPhrase**: `string` + +12 word seedphrase that can be used to derive the `secretKey`. If this is present, it will override the passed in `secretKey`. + +#### Defined in + +[lib/types/general.ts:39](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L39) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/FungibleTokenMetadata.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/FungibleTokenMetadata.md new file mode 100644 index 00000000..184f02f1 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/FungibleTokenMetadata.md @@ -0,0 +1,96 @@ +--- +id: "FungibleTokenMetadata" +title: "Interface: FungibleTokenMetadata" +sidebar_label: "FungibleTokenMetadata" +sidebar_position: 0 +custom_edit_url: null +--- + +General structure of Fungible Token Metadata as per official NEP-148 standard (https://github.com/near/NEPs/blob/master/neps/nep-0148.md). + +## Properties + +### decimals + + **decimals**: `number` + +Used in frontends to show the proper significant digits of a token. This concept is explained well in this OpenZeppelin post (https://docs.openzeppelin.com/contracts/3.x/erc20#a-note-on-decimals). + +#### Defined in + +[lib/types/ft.ts:36](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/ft.ts#L36) + +___ + +### icon + + `Optional` **icon**: `string` + +A small image associated with this token. Must be a data URL, to help consumers display it quickly while protecting user data. +Recommendation: use optimized SVG, which can result in high-resolution images with only 100s of bytes of storage cost. +(Note that these storage costs are incurred to the token owner/deployer, but that querying these icons is a very cheap & cacheable read operation for all consumers of the contract and the RPC nodes that serve the data.) +Recommendation: create icons that will work well with both light-mode and dark-mode websites by either using middle-tone color schemes, or by embedding media queries in the SVG. + +#### Defined in + +[lib/types/ft.ts:43](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/ft.ts#L43) + +___ + +### name + + **name**: `string` + +The human-readable name of the token. + +#### Defined in + +[lib/types/ft.ts:32](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/ft.ts#L32) + +___ + +### reference + + `Optional` **reference**: `string` + +A link to a valid JSON file containing various keys offering supplementary details on the token. Example: /ipfs/QmdmQXB2mzChmMeKY47C43LxUdg1NDJ5MWcKMKxDu7RgQm, https://example.com/token.json, etc. If the information given in this document conflicts with the on-chain attributes, the values in reference shall be considered the source of truth. + +#### Defined in + +[lib/types/ft.ts:45](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/ft.ts#L45) + +___ + +### reference\_hash + + `Optional` **reference\_hash**: `string` + +The base64-encoded sha256 hash of the JSON file contained in the reference field. This is to guard against off-chain tampering. + +#### Defined in + +[lib/types/ft.ts:47](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/ft.ts#L47) + +___ + +### spec + + **spec**: `string` + +A string. Should be ft-1.0.0 to indicate that a Fungible Token contract adheres to the current versions of this Metadata and the Fungible Token Core specs. This will allow consumers of the Fungible Token to know if they support the features of a given contract. + +#### Defined in + +[lib/types/ft.ts:30](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/ft.ts#L30) + +___ + +### symbol + + **symbol**: `string` + +The abbreviation, like wETH or AMPL. + +#### Defined in + +[lib/types/ft.ts:34](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/ft.ts#L34) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/GeneratedKeyPairs.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/GeneratedKeyPairs.md new file mode 100644 index 00000000..adb8ab92 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/GeneratedKeyPairs.md @@ -0,0 +1,46 @@ +--- +id: "GeneratedKeyPairs" +title: "Interface: GeneratedKeyPairs" +sidebar_label: "GeneratedKeyPairs" +sidebar_position: 0 +custom_edit_url: null +--- + +For each generated KeyPair (either through `createDrop`, `addKeys` or `generateKeys`), the public and private keys are returned. +In addition, the actual KeyPair objects are returned as well. + +## Properties + +### keyPairs + + **keyPairs**: `KeyPair`[] + +Actual KeyPair objects that can be used to sign messages, verify signatures, and get the public and private keys + +#### Defined in + +[lib/types/general.ts:20](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L20) + +___ + +### publicKeys + + **publicKeys**: `string`[] + +Set of public keys that were generated + +#### Defined in + +[lib/types/general.ts:22](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L22) + +___ + +### secretKeys + + **secretKeys**: `string`[] + +Set of private keys that were generated + +#### Defined in + +[lib/types/general.ts:24](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/general.ts#L24) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/KeyInfo.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/KeyInfo.md new file mode 100644 index 00000000..4f60ca08 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/KeyInfo.md @@ -0,0 +1,93 @@ +--- +id: "KeyInfo" +title: "Interface: KeyInfo" +sidebar_label: "KeyInfo" +sidebar_position: 0 +custom_edit_url: null +--- + +Important information returned in many view calls regarding a specific access key. + +## Properties + +### allowance + + **allowance**: `number` + +How much allowance does the key have left (measured in $yoctoNEAR). When the key is deleted, this is refunded to the funder's balance. + +#### Defined in + +[lib/types/drops.ts:25](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L25) + +___ + +### curKeyUse + + **curKeyUse**: `number` + +Which use is the key currently on? For single-use keys, this is always 1. + +#### Defined in + +[lib/types/drops.ts:16](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L16) + +___ + +### dropId + + **dropId**: `string` + +Drop ID for the specific drop that the key belongs to. + +#### Defined in + +[lib/types/drops.ts:11](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L11) + +___ + +### keyId + + **keyId**: `number` + +The unique ID associated to this key. IDs are *not* unique across drops but they are unique for any key in the drop. + +#### Defined in + +[lib/types/drops.ts:28](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L28) + +___ + +### lastUsed + + **lastUsed**: `number` + +At what timestamp was the key last used? Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:22](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L22) + +___ + +### publicKey + + **publicKey**: `string` + +Public key for this access key. + +#### Defined in + +[lib/types/drops.ts:13](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L13) + +___ + +### remainingUses + + **remainingUses**: `number` + +How many uses this key has left before it's deleted. + +#### Defined in + +[lib/types/drops.ts:19](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L19) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/Method.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/Method.md new file mode 100644 index 00000000..475cd370 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/Method.md @@ -0,0 +1,153 @@ +--- +id: "Method" +title: "Interface: Method" +sidebar_label: "Method" +sidebar_position: 0 +custom_edit_url: null +--- + +Outlines the information needed for any given method as part of a Function-Call drop. +Each individual key use can have an array of Methods that can be called. + +## Properties + +### accountIdField + + `Optional` **accountIdField**: `string` + +Specifies what field Keypom should auto-inject the account that claimed the drop's ID into when calling the function. +As an example, if the methodName was `nft_mint` and it expected a field `receiver_id` to be passed in, indicating who should receive the token, then the `accountIdField` would be `receiver_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/fc.ts:34](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/fc.ts#L34) + +___ + +### args + + **args**: `string` + +What arguments should be passed to the method. This should be in stringified JSON. + +#### Defined in + +[lib/types/fc.ts:19](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/fc.ts#L19) + +___ + +### attachedDeposit + + **attachedDeposit**: `string` + +How much yoctoNEAR should be attached to the call. + +#### Defined in + +[lib/types/fc.ts:23](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/fc.ts#L23) + +___ + +### attachedGas + + `Optional` **attachedGas**: `string` + +How much gas to attach to this method call. If none, all the gas is split between the parallel method calls in a given claim. +If this is specified, the key can ONLY be used to call `claim` and no `deposit_per_use` can be specified. This leads the key to act like a method calling proxy instead of a linkdrop. + +#### Defined in + +[lib/types/fc.ts:28](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/fc.ts#L28) + +___ + +### dropIdField + + `Optional` **dropIdField**: `string` + +Specifies what field Keypom should auto-inject the drops ID into when calling the function. +As an example, if an NFT contract expected the Keypom drop ID to be passed in as the field `keypom_drop_id` in order to gate access to who can mint NFTs, then the `dropIdField` would be `keypom_drop_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/fc.ts:40](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/fc.ts#L40) + +___ + +### funderIdField + + `Optional` **funderIdField**: `string` + +Specifies what field Keypom should auto-inject the drop funder's account ID into when calling the function. +As an example, if an NFT contract wanted to gate only users that had a key coming from a specific funder's drops, it could expect a field called `keypom_funder_id` and the `funderIdField` would be `keypom_funder_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/fc.ts:52](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/fc.ts#L52) + +___ + +### keyIdField + + `Optional` **keyIdField**: `string` + +Specifies what field Keypom should auto-inject the key's ID into when calling the function. +As an example, if an NFT contract wanted to gate only users with an odd key ID to be able to mint an NFT and their parameter was called `keypom_key_id`, then the `keyIdField` would be `keypom_key_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/fc.ts:46](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/fc.ts#L46) + +___ + +### methodName + + **methodName**: `string` + +The method that should be invoked on the `receiverId`'s contract. + +#### Defined in + +[lib/types/fc.ts:15](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/fc.ts#L15) + +___ + +### receiverId + + **receiverId**: `string` + +The account ID that the contract is deployed to that the method will be called on. + +#### Defined in + +[lib/types/fc.ts:11](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/fc.ts#L11) + +___ + +### receiverToClaimer + + `Optional` **receiverToClaimer**: `boolean` + +If set to true, the claiming account ID will be the receiver ID of the method call. +This receiver must be a valid account and non-malicious (cannot be set to the keypom contract) + +#### Defined in + +[lib/types/fc.ts:57](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/fc.ts#L57) + +___ + +### userArgsRule + + `Optional` **userArgsRule**: ``"AllUser"`` \| ``"FunderPreferred"`` \| ``"UserPreferred"`` + +What permissions does the user have when providing custom arguments to the function call? +By default, the user cannot provide any custom arguments + +#### Defined in + +[lib/types/fc.ts:62](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/fc.ts#L62) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/NFTData.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/NFTData.md new file mode 100644 index 00000000..b16cde0b --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/NFTData.md @@ -0,0 +1,47 @@ +--- +id: "NFTData" +title: "Interface: NFTData" +sidebar_label: "NFTData" +sidebar_position: 0 +custom_edit_url: null +--- + +General structure of a Non-Fungible Token drop. This should be passed into `createDrop` if you wish to have an NFT drop. + +## Properties + +### contractId + + **contractId**: `string` + +The account ID that the NFT contract is deployed to. This contract is where all the NFTs for the specific drop must come from. + +#### Defined in + +[lib/types/nft.ts:6](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L6) + +___ + +### senderId + + `Optional` **senderId**: `string` + +By default, anyone can fund your drop with NFTs. This field allows you to set a specific account ID that will be locked into sending the NFTs. + +#### Defined in + +[lib/types/nft.ts:8](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L8) + +___ + +### tokenIds + + `Optional` **tokenIds**: `string`[] + +If there are any token IDs that you wish to be automatically sent to the Keypom contract in order to register keys as part of `createDrop`, specify them here. +A maximum of 2 token IDs can be sent as part of the transaction. If you wish to register more keys by sending more NFTs, you must do this in a separate call by invoking +the `nftTransferCall` method separately. + +#### Defined in + +[lib/types/nft.ts:14](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L14) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/NonFungibleTokenMetadata.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/NonFungibleTokenMetadata.md new file mode 100644 index 00000000..1aff33fc --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/NonFungibleTokenMetadata.md @@ -0,0 +1,153 @@ +--- +id: "NonFungibleTokenMetadata" +title: "Interface: NonFungibleTokenMetadata" +sidebar_label: "NonFungibleTokenMetadata" +sidebar_position: 0 +custom_edit_url: null +--- + +General structure of Non-Fungible Token Metadata (in camelCase) as per official NEP-177 standard (https://github.com/near/NEPs/blob/master/neps/nep-0177.md). + +## Properties + +### copies + + `Optional` **copies**: `number` + +number of copies of this set of metadata in existence when token was minted. + +#### Defined in + +[lib/types/nft.ts:76](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L76) + +___ + +### description + + `Optional` **description**: `string` + +free-form description + +#### Defined in + +[lib/types/nft.ts:70](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L70) + +___ + +### expiresAt + + `Optional` **expiresAt**: `number` + +When token expires, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:80](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L80) + +___ + +### extra + + `Optional` **extra**: `string` + +anything extra the NFT wants to store on-chain. Can be stringified JSON. + +#### Defined in + +[lib/types/nft.ts:86](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L86) + +___ + +### issuedAt + + `Optional` **issuedAt**: `number` + +When token was issued or minted, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:78](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L78) + +___ + +### media + + `Optional` **media**: `string` + +URL to associated media, preferably to decentralized, content-addressed storage + +#### Defined in + +[lib/types/nft.ts:72](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L72) + +___ + +### mediaHash + + `Optional` **mediaHash**: `string` + +Base64-encoded sha256 hash of content referenced by the `media` field. Required if `media` is included. + +#### Defined in + +[lib/types/nft.ts:74](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L74) + +___ + +### reference + + `Optional` **reference**: `string` + +URL to an off-chain JSON file with more info. + +#### Defined in + +[lib/types/nft.ts:88](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L88) + +___ + +### referenceHash + + `Optional` **referenceHash**: `string` + +Base64-encoded sha256 hash of JSON from reference field. Required if `reference` is included. + +#### Defined in + +[lib/types/nft.ts:90](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L90) + +___ + +### startsAt + + `Optional` **startsAt**: `number` + +When token starts being valid, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:82](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L82) + +___ + +### title + + `Optional` **title**: `string` + +ex. "Arch Nemesis: Mail Carrier" or "Parcel #5055" + +#### Defined in + +[lib/types/nft.ts:68](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L68) + +___ + +### updatedAt + + `Optional` **updatedAt**: `number` + +When token was last updated, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:84](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L84) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/PasswordPerUse.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/PasswordPerUse.md new file mode 100644 index 00000000..4d76ef2f --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/PasswordPerUse.md @@ -0,0 +1,33 @@ +--- +id: "PasswordPerUse" +title: "Interface: PasswordPerUse" +sidebar_label: "PasswordPerUse" +sidebar_position: 0 +custom_edit_url: null +--- + +Keeps track of the password for a given key use. This should be passed in as an array for each key that has passwords. + +## Properties + +### key\_use + + **key\_use**: `number` + +Which use does the password belong to? These uses are *NOT* zero-indexed so the first use corresponds to `1` not `0`. + +#### Defined in + +[lib/types/drops.ts:196](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L196) + +___ + +### pw + + **pw**: `string` + +The password for this given use + +#### Defined in + +[lib/types/drops.ts:194](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L194) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedDrop.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedDrop.md new file mode 100644 index 00000000..e1af40d1 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedDrop.md @@ -0,0 +1,166 @@ +--- +id: "ProtocolReturnedDrop" +title: "Interface: ProtocolReturnedDrop" +sidebar_label: "ProtocolReturnedDrop" +sidebar_position: 0 +custom_edit_url: null +--- + +Drop information returned from the Protocol. This interface is exactly the same as the `Drop`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### config + + `Optional` **config**: [`ProtocolReturnedDropConfig`](ProtocolReturnedDropConfig.md) + +All drops regardless of their type can have a suite of configurations such as how many uses each key has or how often a key can be used. + +#### Defined in + +[lib/types/protocol.ts:49](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L49) + +___ + +### deposit\_per\_use + + **deposit\_per\_use**: `string` + +How much $yoctoNEAR will be transferred anytime a key is used that is part of this drop. + +#### Defined in + +[lib/types/protocol.ts:39](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L39) + +___ + +### drop\_id + + **drop\_id**: `string` + +Drop ID for this specific drop. + +#### Defined in + +[lib/types/protocol.ts:35](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L35) + +___ + +### fc + + `Optional` **fc**: [`ProtocolReturnedFCData`](ProtocolReturnedFCData.md) + +For Function-Call drops, important information needs to be stored such as which methods, the attached deposit, args etc. + +#### Defined in + +[lib/types/protocol.ts:47](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L47) + +___ + +### ft + + `Optional` **ft**: [`ProtocolReturnedFTData`](ProtocolReturnedFTData.md) + +For Fungible Token drops, important information such as the amount of tokens to transfer, or contract need to be stored. + +#### Defined in + +[lib/types/protocol.ts:45](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L45) + +___ + +### keys + + `Optional` **keys**: [`ProtocolReturnedKeyInfo`](ProtocolReturnedKeyInfo.md)[] + +If calling `getDrops` or `getDropInformation` and `withKeys` is passed in as true, an extra view call will be done to get a set of keys that are currently on the drop. + +#### Defined in + +[lib/types/protocol.ts:59](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L59) + +___ + +### metadata + + `Optional` **metadata**: `string` + +Any extra information about the drop can be stored as metadata. This is up to the drop creator and can be stringified JSON, or any other string. + +#### Defined in + +[lib/types/protocol.ts:51](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L51) + +___ + +### next\_key\_id + + **next\_key\_id**: `number` + +What is the next unique ID that will be given to the next access key added to this drop. + +#### Defined in + +[lib/types/protocol.ts:57](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L57) + +___ + +### nft + + `Optional` **nft**: [`ProtocolReturnedNFTData`](ProtocolReturnedNFTData.md) + +For NFT drops, important information such as the token IDs, or contract need to be stored. + +#### Defined in + +[lib/types/protocol.ts:43](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L43) + +___ + +### owner\_id + + **owner\_id**: `string` + +Which account created this drop. + +#### Defined in + +[lib/types/protocol.ts:37](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L37) + +___ + +### registered\_uses + + **registered\_uses**: `number` + +How many key uses are registered for this drop? This is only applicable to simple drops with lazy registrations, FT drops, and NFT drops. + +#### Defined in + +[lib/types/protocol.ts:53](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L53) + +___ + +### required\_gas + + **required\_gas**: `string` + +In order to use an access key that's part of this drop, how much Gas *needs* to be attached to the call? + +#### Defined in + +[lib/types/protocol.ts:55](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L55) + +___ + +### simple + + `Optional` **simple**: [`ProtocolReturnedSimpleData`](ProtocolReturnedSimpleData.md) + +For simple drops, there are specific, optional configurations. + +#### Defined in + +[lib/types/protocol.ts:41](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L41) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedDropConfig.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedDropConfig.md new file mode 100644 index 00000000..aa4df5c3 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedDropConfig.md @@ -0,0 +1,70 @@ +--- +id: "ProtocolReturnedDropConfig" +title: "Interface: ProtocolReturnedDropConfig" +sidebar_label: "ProtocolReturnedDropConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Drop config returned from the Protocol. This interface is exactly the same as the `DropConfig`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### root\_account\_id + + `Optional` **root\_account\_id**: `string` + +Override the global root account that all created sub-accounts will have (currently `near` or `testnet`). This allows users to drops that have a custom root. +For example, Fayyr could specify a root of `fayyr.near` By which all sub-accounts will then be `ACCOUNT.fayyr.near`. +It's important to note that this root account *MUST* have a smart contract deployed that has a method `create_account`. + +#### Defined in + +[lib/types/protocol.ts:83](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L83) + +___ + +### sale + + `Optional` **sale**: [`ProtocolReturnedPublicSaleConfig`](ProtocolReturnedPublicSaleConfig.md) + +#### Defined in + +[lib/types/protocol.ts:76](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L76) + +___ + +### time + + `Optional` **time**: [`ProtocolReturnedTimeConfig`](ProtocolReturnedTimeConfig.md) + +Any information related to time-based configurations such as a starting date for keys etc. + +#### Defined in + +[lib/types/protocol.ts:71](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L71) + +___ + +### usage + + `Optional` **usage**: [`ProtocolReturnedUsageConfig`](ProtocolReturnedUsageConfig.md) + +Any information related to how access keys are used such as which methods they can call or whether an empty drop should be automatically deleted etc. + +#### Defined in + +[lib/types/protocol.ts:74](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L74) + +___ + +### uses\_per\_key + + `Optional` **uses\_per\_key**: `number` + +How many uses can each key have before it's deleted. If this isn't specified, it defaults to 1 use per key. + +#### Defined in + +[lib/types/protocol.ts:68](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L68) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedFCData.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedFCData.md new file mode 100644 index 00000000..34d8c655 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedFCData.md @@ -0,0 +1,23 @@ +--- +id: "ProtocolReturnedFCData" +title: "Interface: ProtocolReturnedFCData" +sidebar_label: "ProtocolReturnedFCData" +sidebar_position: 0 +custom_edit_url: null +--- + +FC Data returned from the Protocol. This interface is exactly the same as the `FCData`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### methods + + **methods**: [`ProtocolReturnedMethod`](ProtocolReturnedMethod.md)[][] + +The top level array indicates a different set of methods that can be called for every key use. It is possible that for a given key use, no methods are called thus acting as a "free" key use whereby the use is reflected on-chain but no assets are transferred. +If a given key use does not have an undefined set of methods, when it is used, all the methods in the set will be called. + +#### Defined in + +[lib/types/protocol.ts:300](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L300) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedFTData.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedFTData.md new file mode 100644 index 00000000..be0e8340 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedFTData.md @@ -0,0 +1,47 @@ +--- +id: "ProtocolReturnedFTData" +title: "Interface: ProtocolReturnedFTData" +sidebar_label: "ProtocolReturnedFTData" +sidebar_position: 0 +custom_edit_url: null +--- + +FT Data returned from the Protocol. This interface is exactly the same as the `FTData`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### balance\_per\_use + + `Optional` **balance\_per\_use**: `string` + +Amount of tokens to transfer but considering the decimal amount. +Example: transferring one wNEAR should be passed in as "1000000000000000000000000" and NOT "1" + +#### Defined in + +[lib/types/protocol.ts:226](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L226) + +___ + +### contract\_id + + **contract\_id**: `string` + +Which contract do the FTs belong to? + +#### Defined in + +[lib/types/protocol.ts:217](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L217) + +___ + +### sender\_id + + `Optional` **sender\_id**: `string` + +By default, anyone can fund your drop with FTs. This field allows you to set a specific account ID that will be locked into sending the FTs. + +#### Defined in + +[lib/types/protocol.ts:221](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L221) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedKeyInfo.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedKeyInfo.md new file mode 100644 index 00000000..fc5551be --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedKeyInfo.md @@ -0,0 +1,94 @@ +--- +id: "ProtocolReturnedKeyInfo" +title: "Interface: ProtocolReturnedKeyInfo" +sidebar_label: "ProtocolReturnedKeyInfo" +sidebar_position: 0 +custom_edit_url: null +--- + +Key information returned from the Protocol. This interface is exactly the same as the `KeyInfo`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### allowance + + **allowance**: `number` + +How much allowance does the key have left (measured in $yoctoNEAR). When the key is deleted, this is refunded to the funder's balance. + +#### Defined in + +[lib/types/protocol.ts:23](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L23) + +___ + +### cur\_key\_use + + **cur\_key\_use**: `number` + +Which use is the key currently on? For single-use keys, this is always 1. + +#### Defined in + +[lib/types/protocol.ts:14](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L14) + +___ + +### drop\_id + + **drop\_id**: `string` + +Drop ID for the specific drop that the key belongs to. + +#### Defined in + +[lib/types/protocol.ts:9](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L9) + +___ + +### key\_id + + **key\_id**: `number` + +The unique ID associated to this key. IDs are *not* unique across drops but they are unique for any key in the drop. + +#### Defined in + +[lib/types/protocol.ts:26](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L26) + +___ + +### last\_used + + **last\_used**: `number` + +At what timestamp was the key last used? Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:20](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L20) + +___ + +### public\_key + + **public\_key**: `string` + +Public key for this access key. + +#### Defined in + +[lib/types/protocol.ts:11](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L11) + +___ + +### remaining\_uses + + **remaining\_uses**: `number` + +How many uses this key has left before it's deleted. + +#### Defined in + +[lib/types/protocol.ts:17](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L17) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedMethod.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedMethod.md new file mode 100644 index 00000000..0746a1e0 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedMethod.md @@ -0,0 +1,153 @@ +--- +id: "ProtocolReturnedMethod" +title: "Interface: ProtocolReturnedMethod" +sidebar_label: "ProtocolReturnedMethod" +sidebar_position: 0 +custom_edit_url: null +--- + +Method information returned from the Protocol. This interface is exactly the same as the `Method`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### account\_id\_field + + `Optional` **account\_id\_field**: `string` + +Specifies what field Keypom should auto-inject the account that claimed the drop's ID into when calling the function. +As an example, if the methodName was `nft_mint` and it expected a field `receiver_id` to be passed in, indicating who should receive the token, then the `accountIdField` would be `receiver_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/protocol.ts:260](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L260) + +___ + +### args + + **args**: `string` + +What arguments should be passed to the method. This should be in stringified JSON. + +#### Defined in + +[lib/types/protocol.ts:245](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L245) + +___ + +### attached\_deposit + + **attached\_deposit**: `string` + +How much yoctoNEAR should be attached to the call. + +#### Defined in + +[lib/types/protocol.ts:249](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L249) + +___ + +### attached\_gas + + `Optional` **attached\_gas**: `string` + +How much gas to attach to this method call. If none, all the gas is split between the parallel method calls in a given claim. +If this is specified, the key can ONLY be used to call `claim` and no `deposit_per_use` can be specified. This leads the key to act like a method calling proxy instead of a linkdrop. + +#### Defined in + +[lib/types/protocol.ts:254](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L254) + +___ + +### drop\_id\_field + + `Optional` **drop\_id\_field**: `string` + +Specifies what field Keypom should auto-inject the drops ID into when calling the function. +As an example, if an NFT contract expected the Keypom drop ID to be passed in as the field `keypom_drop_id` in order to gate access to who can mint NFTs, then the `dropIdField` would be `keypom_drop_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/protocol.ts:266](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L266) + +___ + +### funder\_id\_field + + `Optional` **funder\_id\_field**: `string` + +Specifies what field Keypom should auto-inject the funder's account ID into when calling the function. +As an example, if an NFT contract wanted to gate only users with an odd key ID to be able to mint an NFT and their parameter was called `keypom_key_id`, then the `keyIdField` would be `keypom_key_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/protocol.ts:278](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L278) + +___ + +### key\_id\_field + + `Optional` **key\_id\_field**: `string` + +Specifies what field Keypom should auto-inject the key's ID into when calling the function. +As an example, if an NFT contract wanted to gate only users with an odd key ID to be able to mint an NFT and their parameter was called `keypom_key_id`, then the `keyIdField` would be `keypom_key_id`. +To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + +#### Defined in + +[lib/types/protocol.ts:272](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L272) + +___ + +### method\_name + + **method\_name**: `string` + +The method that should be invoked on the `receiverId`'s contract. + +#### Defined in + +[lib/types/protocol.ts:241](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L241) + +___ + +### receiver\_id + + **receiver\_id**: `string` + +The account ID that the contract is deployed to that the method will be called on. + +#### Defined in + +[lib/types/protocol.ts:237](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L237) + +___ + +### receiver\_to\_claimer + + `Optional` **receiver\_to\_claimer**: `boolean` + +If set to true, the claiming account ID will be the receiver ID of the method call. +This receiver must be a valid account and non-malicious (cannot be set to the keypom contract) + +#### Defined in + +[lib/types/protocol.ts:283](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L283) + +___ + +### user\_args\_rule + + `Optional` **user\_args\_rule**: ``"AllUser"`` \| ``"FunderPreferred"`` \| ``"UserPreferred"`` + +What permissions does the user have when providing custom arguments to the function call? +By default, the user cannot provide any custom arguments + +#### Defined in + +[lib/types/protocol.ts:288](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L288) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedNFTData.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedNFTData.md new file mode 100644 index 00000000..1f809b8b --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedNFTData.md @@ -0,0 +1,34 @@ +--- +id: "ProtocolReturnedNFTData" +title: "Interface: ProtocolReturnedNFTData" +sidebar_label: "ProtocolReturnedNFTData" +sidebar_position: 0 +custom_edit_url: null +--- + +NFT Data information returned from the Protocol. This interface is exactly the same as the `NFTData`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### contract\_id + + **contract\_id**: `string` + +The account ID that the NFT contract is deployed to. This contract is where all the NFTs for the specific drop must come from. + +#### Defined in + +[lib/types/protocol.ts:204](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L204) + +___ + +### sender\_id + + `Optional` **sender\_id**: `string` + +By default, anyone can fund your drop with NFTs. This field allows you to set a specific account ID that will be locked into sending the NFTs. + +#### Defined in + +[lib/types/protocol.ts:206](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L206) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedNonFungibleTokenMetadata.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedNonFungibleTokenMetadata.md new file mode 100644 index 00000000..1460ffac --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedNonFungibleTokenMetadata.md @@ -0,0 +1,153 @@ +--- +id: "ProtocolReturnedNonFungibleTokenMetadata" +title: "Interface: ProtocolReturnedNonFungibleTokenMetadata" +sidebar_label: "ProtocolReturnedNonFungibleTokenMetadata" +sidebar_position: 0 +custom_edit_url: null +--- + +General structure of Non-Fungible Token Metadata as per official NEP-177 standard (https://github.com/near/NEPs/blob/master/neps/nep-0177.md). + +## Properties + +### copies + + `Optional` **copies**: `number` + +number of copies of this set of metadata in existence when token was minted. + +#### Defined in + +[lib/types/nft.ts:46](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L46) + +___ + +### description + + `Optional` **description**: `string` + +free-form description + +#### Defined in + +[lib/types/nft.ts:40](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L40) + +___ + +### expires\_at + + `Optional` **expires\_at**: `number` + +When token expires, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:50](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L50) + +___ + +### extra + + `Optional` **extra**: `string` + +anything extra the NFT wants to store on-chain. Can be stringified JSON. + +#### Defined in + +[lib/types/nft.ts:56](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L56) + +___ + +### issued\_at + + `Optional` **issued\_at**: `number` + +When token was issued or minted, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:48](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L48) + +___ + +### media + + `Optional` **media**: `string` + +URL to associated media, preferably to decentralized, content-addressed storage + +#### Defined in + +[lib/types/nft.ts:42](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L42) + +___ + +### media\_hash + + `Optional` **media\_hash**: `string` + +Base64-encoded sha256 hash of content referenced by the `media` field. Required if `media` is included. + +#### Defined in + +[lib/types/nft.ts:44](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L44) + +___ + +### reference + + `Optional` **reference**: `string` + +URL to an off-chain JSON file with more info. + +#### Defined in + +[lib/types/nft.ts:58](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L58) + +___ + +### reference\_hash + + `Optional` **reference\_hash**: `string` + +Base64-encoded sha256 hash of JSON from reference field. Required if `reference` is included. + +#### Defined in + +[lib/types/nft.ts:60](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L60) + +___ + +### starts\_at + + `Optional` **starts\_at**: `number` + +When token starts being valid, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:52](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L52) + +___ + +### title + + `Optional` **title**: `string` + +ex. "Arch Nemesis: Mail Carrier" or "Parcel #5055" + +#### Defined in + +[lib/types/nft.ts:38](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L38) + +___ + +### updated\_at + + `Optional` **updated\_at**: `number` + +When token was last updated, Unix epoch in milliseconds + +#### Defined in + +[lib/types/nft.ts:54](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L54) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedNonFungibleTokenObject.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedNonFungibleTokenObject.md new file mode 100644 index 00000000..6170554a --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedNonFungibleTokenObject.md @@ -0,0 +1,69 @@ +--- +id: "ProtocolReturnedNonFungibleTokenObject" +title: "Interface: ProtocolReturnedNonFungibleTokenObject" +sidebar_label: "ProtocolReturnedNonFungibleTokenObject" +sidebar_position: 0 +custom_edit_url: null +--- + +General structure of a Non-Fungible Token object as per official NEP-171 standard (https://github.com/near/NEPs/blob/master/neps/nep-0171.md). + +## Properties + +### approved\_account\_ids + + `Optional` **approved\_account\_ids**: `Map`<`string`, `number`\> + +Map of account IDs to approval IDs as per official NEP-178 standard (https://github.com/near/NEPs/blob/master/neps/nep-0178.md). + +#### Defined in + +[lib/types/nft.ts:28](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L28) + +___ + +### metadata + + `Optional` **metadata**: [`ProtocolReturnedNonFungibleTokenMetadata`](ProtocolReturnedNonFungibleTokenMetadata.md) + +Metadata for the token + +#### Defined in + +[lib/types/nft.ts:26](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L26) + +___ + +### owner\_id + + **owner\_id**: `string` + +Account ID of the owner + +#### Defined in + +[lib/types/nft.ts:24](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L24) + +___ + +### royalty + + `Optional` **royalty**: `Map`<`string`, `number`\> + +A mapping of NEAR accounts to the amount each should be paid out as per official NEP-199 standard (https://github.com/near/NEPs/blob/master/neps/nep-0199.md). + +#### Defined in + +[lib/types/nft.ts:30](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L30) + +___ + +### token\_id + + **token\_id**: `string` + +String ID for the token + +#### Defined in + +[lib/types/nft.ts:22](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/nft.ts#L22) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedPublicSaleConfig.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedPublicSaleConfig.md new file mode 100644 index 00000000..936dcc77 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedPublicSaleConfig.md @@ -0,0 +1,97 @@ +--- +id: "ProtocolReturnedPublicSaleConfig" +title: "Interface: ProtocolReturnedPublicSaleConfig" +sidebar_label: "ProtocolReturnedPublicSaleConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Within the config, there are configurable options related to how keys can be sold and a funder can potentially make a profit. + +## Properties + +### allowlist + + `Optional` **allowlist**: `string`[] + +Which accounts are allowed to add keys? If the allowlist is empty, anyone that is not in the blocklist can add keys. + +#### Defined in + +[lib/types/protocol.ts:173](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L173) + +___ + +### auto\_withdraw\_funds + + `Optional` **auto\_withdraw\_funds**: `boolean` + +Should the revenue generated be sent to the funder's account balance or +automatically withdrawn and sent to their NEAR wallet? + +#### Defined in + +[lib/types/protocol.ts:180](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L180) + +___ + +### blocklist + + `Optional` **blocklist**: `string`[] + +Which accounts are NOT allowed to add keys? + +#### Defined in + +[lib/types/protocol.ts:175](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L175) + +___ + +### end + + `Optional` **end**: `number` + +Block timestamp dictating the end of the public sale. If None, keys can be added indefinitely +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:190](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L190) + +___ + +### max\_num\_keys + + `Optional` **max\_num\_keys**: `number` + +Maximum number of keys that can be added to this drop. If None, there is no max. + +#### Defined in + +[lib/types/protocol.ts:166](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L166) + +___ + +### price\_per\_key + + `Optional` **price\_per\_key**: `string` + +Amount of $NEAR that the user needs to attach (if they are not the funder) on top of costs. This amount will be +Automatically sent to the funder's balance. If None, the keys are free to the public. + +#### Defined in + +[lib/types/protocol.ts:171](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L171) + +___ + +### start + + `Optional` **start**: `number` + +Minimum block timestamp before the public sale starts. If None, keys can be added immediately +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:185](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L185) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedSimpleData.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedSimpleData.md new file mode 100644 index 00000000..9b62136b --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedSimpleData.md @@ -0,0 +1,17 @@ +--- +id: "ProtocolReturnedSimpleData" +title: "Interface: ProtocolReturnedSimpleData" +sidebar_label: "ProtocolReturnedSimpleData" +sidebar_position: 0 +custom_edit_url: null +--- + +## Properties + +### lazy\_register + + `Optional` **lazy\_register**: `boolean` + +#### Defined in + +[lib/types/protocol.ts:195](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L195) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedTimeConfig.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedTimeConfig.md new file mode 100644 index 00000000..0d0eeb09 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedTimeConfig.md @@ -0,0 +1,63 @@ +--- +id: "ProtocolReturnedTimeConfig" +title: "Interface: ProtocolReturnedTimeConfig" +sidebar_label: "ProtocolReturnedTimeConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Time Config information returned from the Protocol. This interface is exactly the same as the `TimeConfig`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### end + + `Optional` **end**: `number` + +Block timestamp that keys must be used before. If this isn't specified, keys can be used indefinitely. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:101](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L101) + +___ + +### interval + + `Optional` **interval**: `number` + +Interval of time after the `start_timestamp` that must pass before a key can be used. If multiple intervals pass, the key can be used multiple times. +This has nothing to do With the throttle timestamp. It only pertains to the start timestamp and the current timestamp. The last_used timestamp is not taken into account. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:114](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L114) + +___ + +### start + + `Optional` **start**: `number` + +Minimum block timestamp before keys can be used. If this isn't specified, keys can be used immediately. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:95](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L95) + +___ + +### throttle + + `Optional` **throttle**: `number` + +Amount of time that *must* pass in between each key use. If this isn't specified, there is no delay between key uses. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/protocol.ts:107](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L107) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedUsageConfig.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedUsageConfig.md new file mode 100644 index 00000000..5fc090bd --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/ProtocolReturnedUsageConfig.md @@ -0,0 +1,80 @@ +--- +id: "ProtocolReturnedUsageConfig" +title: "Interface: ProtocolReturnedUsageConfig" +sidebar_label: "ProtocolReturnedUsageConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Usage Config information returned from the Protocol. This interface is exactly the same as the `UsageConfig`, except all the fields are +snake cased instead of camel cased due to what the Protocol returns. + +## Properties + +### account\_creation\_fields + + `Optional` **account\_creation\_fields**: `Object` + +When calling `create_account` on the root account, which keypom args should be attached to the payload. + +#### Type declaration + +| Name | Type | Description | +| :------ | :------ | :------ | +| `account_id_field?` | `string` | Specifies what field Keypom should auto-inject the account that claimed the drop's ID into when calling the `create_account` function. | +| `drop_id_field?` | `string` | Specifies what field Keypom should auto-inject the drop's ID into when calling the `create_account` function. | +| `funder_id_field?` | `string` | Specifies what field Keypom should auto-inject the drop funder's account ID into when calling the `create_account` function. | +| `key_id_field?` | `string` | Specifies what field Keypom should auto-inject the key's ID into when calling the `create_account` function. | + +#### Defined in + +[lib/types/protocol.ts:141](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L141) + +___ + +### auto\_delete\_drop + + `Optional` **auto\_delete\_drop**: `boolean` + +When a key is used and deleted, if it results in the drop being empty, should the drop automatically be deleted? If this isn't specified, it defaults to false. + +#### Defined in + +[lib/types/protocol.ts:134](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L134) + +___ + +### auto\_withdraw + + `Optional` **auto\_withdraw**: `boolean` + +In the case where `autoDeleteDrop` is set to true and the drop is the owner's last, should their balance be automatically withdrawn? If this isn't specified, it defaults to false. + +#### Defined in + +[lib/types/protocol.ts:138](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L138) + +___ + +### permissions + + `Optional` **permissions**: `string` + +Specify which methods can be called by the access key (either `claim` or `create_account_and_claim`). If this isn't specified, both methods can be called. + +#### Defined in + +[lib/types/protocol.ts:125](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L125) + +___ + +### refund\_deposit + + `Optional` **refund\_deposit**: `boolean` + +If the method `claim` is called rather than `create_account_and_claim`, should the `deposit_per_use` be refunded to the owner's balance? +If this isn't specified, it defaults to false. + +#### Defined in + +[lib/types/protocol.ts:130](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/protocol.ts#L130) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/PublicSaleConfig.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/PublicSaleConfig.md new file mode 100644 index 00000000..2f2fe27f --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/PublicSaleConfig.md @@ -0,0 +1,107 @@ +--- +id: "PublicSaleConfig" +title: "Interface: PublicSaleConfig" +sidebar_label: "PublicSaleConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Within the config, there are configurable options related to how keys can be sold and a funder can potentially make a profit. + +## Properties + +### allowlist + + `Optional` **allowlist**: `string`[] + +Which accounts are allowed to add keys? If the allowlist is empty, anyone that is not in the blocklist can add keys. + +#### Defined in + +[lib/types/drops.ts:169](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L169) + +___ + +### autoWithdrawFunds + + `Optional` **autoWithdrawFunds**: `boolean` + +Should the revenue generated be sent to the funder's account balance or +automatically withdrawn and sent to their NEAR wallet? + +#### Defined in + +[lib/types/drops.ts:176](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L176) + +___ + +### blocklist + + `Optional` **blocklist**: `string`[] + +Which accounts are NOT allowed to add keys? + +#### Defined in + +[lib/types/drops.ts:171](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L171) + +___ + +### end + + `Optional` **end**: `number` + +Block timestamp dictating the end of the public sale. If None, keys can be added indefinitely +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:186](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L186) + +___ + +### maxNumKeys + + `Optional` **maxNumKeys**: `number` + +Maximum number of keys that can be added to this drop. If None, there is no max. + +#### Defined in + +[lib/types/drops.ts:161](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L161) + +___ + +### pricePerKeyNEAR + + `Optional` **pricePerKeyNEAR**: `number` + +Amount of $NEAR that the user needs to attach (if they are not the funder) on top of costs. This amount will be +Automatically sent to the funder's balance. If None, the keys are free to the public. + +#### Defined in + +[lib/types/drops.ts:166](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L166) + +___ + +### pricePerKeyYocto + + `Optional` **pricePerKeyYocto**: `string` + +#### Defined in + +[lib/types/drops.ts:167](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L167) + +___ + +### start + + `Optional` **start**: `number` + +Minimum block timestamp before the public sale starts. If None, keys can be added immediately +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:181](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L181) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/SimpleData.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/SimpleData.md new file mode 100644 index 00000000..ea3cb6fb --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/SimpleData.md @@ -0,0 +1,21 @@ +--- +id: "SimpleData" +title: "Interface: SimpleData" +sidebar_label: "SimpleData" +sidebar_position: 0 +custom_edit_url: null +--- + +Specific configurable information for Simple drops. + +## Properties + +### lazyRegister + + `Optional` **lazyRegister**: `boolean` + +If this is set to true, keys can be created and registered AFTER they've been created (for simple and FC drops only). + +#### Defined in + +[lib/types/simple.ts:6](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/simple.ts#L6) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/TimeConfig.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/TimeConfig.md new file mode 100644 index 00000000..ac76a265 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/TimeConfig.md @@ -0,0 +1,62 @@ +--- +id: "TimeConfig" +title: "Interface: TimeConfig" +sidebar_label: "TimeConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Within the config, there are configurable options related to timing such as how often a key can be used. + +## Properties + +### end + + `Optional` **end**: `number` + +Block timestamp that keys must be used before. If this isn't specified, keys can be used indefinitely. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:98](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L98) + +___ + +### interval + + `Optional` **interval**: `number` + +Interval of time after the `start_timestamp` that must pass before a key can be used. If multiple intervals pass, the key can be used multiple times. +This has nothing to do With the throttle timestamp. It only pertains to the start timestamp and the current timestamp. The last_used timestamp is not taken into account. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:111](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L111) + +___ + +### start + + `Optional` **start**: `number` + +Minimum block timestamp before keys can be used. If this isn't specified, keys can be used immediately. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:92](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L92) + +___ + +### throttle + + `Optional` **throttle**: `number` + +Amount of time that *must* pass in between each key use. If this isn't specified, there is no delay between key uses. +Measured in number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC. + +#### Defined in + +[lib/types/drops.ts:104](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L104) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/UsageConfig.md b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/UsageConfig.md new file mode 100644 index 00000000..e86b592d --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/UsageConfig.md @@ -0,0 +1,79 @@ +--- +id: "UsageConfig" +title: "Interface: UsageConfig" +sidebar_label: "UsageConfig" +sidebar_position: 0 +custom_edit_url: null +--- + +Within the config, there are configurable options related to how keys can be used. What permissions they have, whether an empty drop should be automatically deleted etc. + +## Properties + +### accountCreationFields + + `Optional` **accountCreationFields**: `Object` + +When calling `create_account` on the root account, which keypom args should be attached to the payload. + +#### Type declaration + +| Name | Type | Description | +| :------ | :------ | :------ | +| `accountIdField?` | `string` | Specifies what field Keypom should auto-inject the account that claimed the drop's ID into when calling the `create_account` function. | +| `dropIdField?` | `string` | Specifies what field Keypom should auto-inject the drop's ID into when calling the `create_account` function. | +| `funderIdField?` | `string` | Specifies what field Keypom should auto-inject the drop funder's account ID into when calling the `create_account` function. | +| `keyIdField?` | `string` | Specifies what field Keypom should auto-inject the key's ID into when calling the `create_account` function. | + +#### Defined in + +[lib/types/drops.ts:136](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L136) + +___ + +### autoDeleteDrop + + `Optional` **autoDeleteDrop**: `boolean` + +When a key is used and deleted, if it results in the drop being empty, should the drop automatically be deleted? If this isn't specified, it defaults to false. + +#### Defined in + +[lib/types/drops.ts:130](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L130) + +___ + +### autoWithdraw + + `Optional` **autoWithdraw**: `boolean` + +When the last key in this drop is used, in the case where `autoDeleteDrop` is set to true and the drop is the owner's last, should their balance be automatically withdrawn? If this isn't specified, it defaults to false. + +#### Defined in + +[lib/types/drops.ts:134](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L134) + +___ + +### permissions + + `Optional` **permissions**: `string` + +Specify which methods can be called by the access key (either `claim` or `create_account_and_claim`). If this isn't specified, both methods can be called. + +#### Defined in + +[lib/types/drops.ts:121](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L121) + +___ + +### refundDeposit + + `Optional` **refundDeposit**: `boolean` + +If the method `claim` is called rather than `create_account_and_claim`, should the `deposit_per_use` be refunded to the owner's balance? +If this isn't specified, it defaults to false. + +#### Defined in + +[lib/types/drops.ts:126](https://github.com/keypom/keypom-js/blob/68bf90396/packages/core/src/lib/types/drops.ts#L126) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/_category_.yml b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/_category_.yml new file mode 100644 index 00000000..43bec88c --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/interfaces/_category_.yml @@ -0,0 +1,2 @@ +label: "Interfaces" +position: 4 \ No newline at end of file diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/modules.md b/versioned_docs/version-2.0/keypom-sdk/Selector/modules.md new file mode 100644 index 00000000..2dd4129f --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/modules.md @@ -0,0 +1,31 @@ +--- +id: "modules" +title: "@keypom/selector - v1.2.0" +sidebar_label: "Exports" +sidebar_position: 0.5 +custom_edit_url: null +--- + +## Classes + +- [KeypomWallet](classes/KeypomWallet.md) + +## Functions + +### setupKeypom + +**setupKeypom**(`ยซdestructuredยป`): `WalletModuleFactory`<`KeypomWalletInstant`\> + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `ยซdestructuredยป` | `KeypomParams` | + +#### Returns + +`WalletModuleFactory`<`KeypomWalletInstant`\> + +#### Defined in + +[core/setup.ts:92](https://github.com/keypom/keypom-js/blob/9a866ee41/packages/selector/src/core/setup.ts#L92) diff --git a/versioned_docs/version-2.0/keypom-sdk/Selector/welcome.md b/versioned_docs/version-2.0/keypom-sdk/Selector/welcome.md new file mode 100644 index 00000000..27dff653 --- /dev/null +++ b/versioned_docs/version-2.0/keypom-sdk/Selector/welcome.md @@ -0,0 +1,407 @@ +--- +id: "welcome" +title: "@keypom/selector - v1.2.0" +sidebar_label: "Readme" +sidebar_position: 0 +custom_edit_url: null +--- + +

+ + + + +

Keypom Wallet Selector

+ +

+ +

+ + + + + + + + + + + + +

+ +The Keypom Wallet Selector is a package that allows apps to be fully compatible with both trial accounts and instant sign in experiences. See the following demos for examples of the user experience. +- Instant Sign-In [Demo](https://www.youtube.com/watch?v=p_NOcYbRlJw&feature=youtu.be) +- Trial Account [Demo](https://www.youtube.com/watch?v=p_NOcYbRlJw) + +# Table of Contents +- [Table of Contents](#table-of-contents) +- [Installation](#installation) +- [Getting Started](#getting-started) + - [Setup Keypom Parameters](#setup-keypom-parameters) + - [IPFS Customizations](#ipfs-customizations) +- [Keypom Trial Accounts](#keypom-trial-accounts) + - [Trial Account Specs](#trial-account-specs) + - [Modal Options](#modal-options) + - [Wallets](#wallets) + - [Theme And CSS](#theme-and-css) + - [Modal Text](#modal-text) + - [Example Trial Account Integration](#example-trial-account-integration) +- [Keypom Instant Sign In Experiences](#keypom-instant-sign-in-experiences) + - [Instant Sign In Specs](#instant-sign-in-specs) +- [Contributing](#contributing) +- [License](#license) + +--- + +# Installation + +To install the Keypom Wallet Selector, run the following command: + +```bash +npm install @keypom/selector +# or +yarn add @keypom/selector +# or +pnpm add @keypom/selector +``` + +# Getting Started + +Most apps on NEAR should be compatible with the official [wallet selector](https://github.com/near/wallet-selector) to enable sign-in and sending transactions. For this reason, the Keypom selector has been made to fully support any app that uses the wallet selector. + +To get started, navigate to the app's `setupWalletSelector` code where the selector is initialized. Here, you can specify which wallet modules your app should support. Simply add Keypom's `setupKeypom` function to the list of modules and you're good to go! + +```js +const selector = await setupWalletSelector({ + network: "testnet", + modules: [ + setupMyNearWallet(), + ... + setupSender(), + setupKeypom(PARAMS) + ], +}); +``` + +## Setup Keypom Parameters + +`setupKeypom` is the core of the Keypom wallet selector and is the only function you should know about. There are a ton of customizable features that you can make use of to tailor the user experience to your app's needs. At its core, the setup function takes the following parameters: + +- `networkId`: Either `testnet` or `mainnet`. +- `signInContractId`: Which contract will be used to sign in users. +- `trialAccountSpecs`: If specified, trial accounts will be supported on the app. These specifications outline two aspects: + 1. How the URL should be constructed for the app to trigger the trial account sign in flow. + 2. Customizable options for the trial account modals including *all* the text such as titles, descriptions, buttons, placeholders etc. In addition, you can specify exactly which off-boarding wallets you'd like to support. +- `instantSignInSpecs`: If specified, trial accounts will be supported on the app. The instant sign in specs dictate how the URL should be constructed for the app to trigger the instant sign in flow. + +### IPFS Customizations + +For apps that wish to customize the Keypom parameters on a per page basis or even a per user basis, they can make use of IPFS CIDs. By adding a `?cid=` parameter to the URL, Keypom will fetch the parameters from the specified CID. The contents on IPFS must be JSON that match the Keypom parameters: + +```json +{ + "networkId": "testnet", // Or "mainnet", + "signInContractId": CONTRACT_ID, + "trialAccountSpecs": { + "url": "vandeley_industries.com/trial-sign-in/ACCOUNT_ID#SECRET_KEY", + "modalOptions": KEYPOM_OPTIONS + }, + "instantSignInSpecs": { + "url": "vandeley_industries.com/instant-sign-in/ACCOUNT_ID#SECRET_KEY" + } +} +``` + +An example CID can be found below: +``` +bafkreidneri4ffymscahjprlapg4j62yleli73ncwdmopnkxpgczpusqn4 +``` + +# Keypom Trial Accounts + +Keypom Trial Accounts are an exciting new opportunity for Web3 apps to seamlessly onboard users whether theyโ€™re completely new to crypto or seasoned veterans. With the click of a link, users require no software, wallet setup, wallet connection, and are *instantly signed into apps* with their trial account, ready to make on-chain transactions. Unlike most other onboarding mechanisms, the entire experience can be embedded *directly in the app* to increase user retention and is entirely on-chain. + +This technology is perfect for dApps of all sizes ranging from small indie to large enterprise applications. + +- Trial Account [Demo](https://www.youtube.com/watch?v=p_NOcYbRlJw) + +In order to support trial accounts, your app must have the `setupKeypom` function embedded within the wallet selector with the `trialAccountSpecs` parameter specified. + +## Trial Account Specs + +The trial account specifications allows the Keypom wallet selector to support trial accounts on your app. In order to trigger the sign in flow, the user must be on the correct URL. This URL is specified in the specifications as a string and should look like this: + +```js +https://near.org/#trial-url/ACCOUNT_ID/SECRET_KEY +``` + +The URL *must* have the `ACCOUNT_ID` and `SECRET_KEY` placeholders. + +As an example, if you wanted your trial users to sign in once they reached `https://near.org/#trial-url/`, and you wanted the account and secret key to be separated using `/`, your specs should look like this: + +```js +trialAccountSpecs: { + url: "https://near.org/#trial-url/ACCOUNT_ID/SECRET_KEY", +} +``` + +Alternatively, you could swap the `/` delimiter with a `#` instead: + +```js +trialAccountSpecs: { + url: "https://near.org/#trial-url/ACCOUNT_ID#SECRET_KEY", +} +``` + +> **NOTE:** The account ID must come first and the secret key must follow the delimiter. For unclaimed trial account linkdrops, the account ID will be the Keypom contract. For claimed trial account linkdrops, the account ID will be the account ID chosen by the user. + +## Modal Options + +The second field in the trial account specs is the `modalOptions`. This contains all the customizable options for the trial account modals as well as the wallets you want to support for user offboarding. + +```js +export interface ModalCustomizations { + wallets: OffboardingWallet[]; + theme?: Theme; + beginTrial?: BeginTrialCustomizations, + trialOver?: TrialOverCustomizations, + invalidAction?: InvalidActionCustomizations, + insufficientBalance?: InsufficientBalanceCustomizations, +} +``` + +#### Wallets + +The only required field is `wallets`. This should be a list of valid domains that support trial account offboarding. Each of the wallets in the list will be displayed as a button once the trial is over. + +```js +export interface OffboardingWallet { + name: string; + description: string; + iconUrl: string; + redirectUrl: string; +} +``` + +For each wallet, you can specify a name to display, a description, an image (in the form of a URL), and where to redirect the user to once the button is clicked. The redirect URL follows the same format as the trial account URL and should look like this: + +```js +https://app.mynearwallet.com/linkdrop/ACCOUNT_ID/SECRET_KEY +``` + +The URL *must* have the `ACCOUNT_ID` and `SECRET_KEY` placeholders. + +### Theme And CSS + +The modal used by Keypom uses the same CSS as the official wallet selector modal behind the scenes. To learn how to customize the theme to match your app, see the selector's [documentation](https://github.com/near/wallet-selector/tree/main/packages/modal-ui#react--vue). + +If you only wish to change the theme between light and dark mode, you can pass in a `theme` field in the modal options. This field should be either `light` or `dark`. + +### Modal Text + +In addition to the modal style, you have complete control over the text that is displayed at each stage of the claiming process. To see the default text, see the [Default Text](#modal-default-text) section. + +For the trial account creation process, there are currently 3 modals that can be customized: + +1. Landing page: what the user sees when they first click the link + +```bash +landing?: { + title?: string; + body?: string; + fieldPlaceholder?: string; + buttonText?: string; + subText?: { + landing?: string; + invalidAccountId?: string; + accountIdTaken?: string; + accountIdAvailable?: string; + } +}, +``` + +2. Claiming: while the account is being created: +```bash +claiming?: { + title?: string; + body?: string; +}, +``` + +3. Claimed: once the account has been created: +```bash +claimed?: { + title?: string; + body?: string; + buttonText?: string; +} +``` + +The next stage that can be customized is what the user sees once their trial is over and they need to choose a wallet to offboard to. + +```bash +trialOver?: { + mainBody?: { + title?: string; + body?: string; + imageOne?: { + title: string; + body: string; + }, + imageTwo?: { + title: string; + body: string; + }, + button?: { + url?: string; + newTab?: boolean; + text?: string; + } + }, + offboardingOptions?: { + title?: string; + } +} +``` + +You can change the titles, descriptions, button text / behavior and more to tailor the experience to your app. Finally, you can change the text for when the user tries to perform an invalid action, or tries to spend more $NEAR than the account has available. + +## Example Trial Account Integration + +In the following example, you'll see how the trial account flow can be fully integrated into an application. The app has the domain `https://example.com` and the trial account modals should show up once the user lands on `https://example.com/trial-accounts`. In addition, the app doesn't want to expose the secret key in their analytics so they'll separate the account ID and secret key using a `#` instead of a `/`. + +The app will also support MyNEARWallet offboarding and will change the default text for the landing modal when the trial begins. + +```js +const NETWORK_ID = "testnet"; +const CONTRACT_ID = "example.near"; + +export const KEYPOM_OPTIONS = { + beginTrial: { + landing: { + title: "Welcome To My Cool Example App!", + }, + }, + wallets: [ + { + name: "MyNEARWallet", + description: "Secure your account with a Seed Phrase", + redirectUrl: "https://testnet.mynearwallet.com/linkdrop/ACCOUNT_ID/SECRET_KEY", + iconUrl: "INSERT_ICON_URL_HERE" + }, + ] +} + +const selector = await setupWalletSelector({ + network: NETWORK_ID, + modules: [ + setupMyNearWallet(), + ... + setupSender(), + setupKeypom({ + networkId: NETWORK_ID, + signInContractId: CONTRACT_ID, + trialAccountSpecs: { + url: "https://example.com/trial-accounts/ACCOUNT_ID#SECRET_KEY", + modalOptions: KEYPOM_OPTIONS + } + }) + ], +}); +``` + +# Keypom Instant Sign In Experiences + +Instant sign in experiences are a great way to reduce friction for users signing into applications. Currently, the sign in flow for a new user is as follows: +1. User creates an account. +2. They navigate to an application. +3. Sign-in is clicked. +4. The wallet selector modal is opened and the user needs to scroll to find their wallet. +5. The user clicks their wallet and is redirected to the wallet's website to approve a transaction. +6. The user is redirected back to the app and is signed in. + +As NEAR pushes to abstract the crypto complexities and jargon away from the end user, this current approach is not scalable. Not only is there a huge amount of clicks and redirects which leads to a loss in conversion, but the user is also expected to know which wallet they own. This is a huge barrier to entry as often times, the wallet logic will be abstracted from the user as seen with SWEAT. + +The flow that Keypom offers is as follows: +1. User creates an account. +2. User clicks discovers an application from their wallet. +3. User is instantly signed in and can start using the application. + +This flow is much more seamless and removes all the redirects and wallet selector modal friction. + +- Instant Sign-In [Demo](https://www.youtube.com/watch?v=p_NOcYbRlJw&feature=youtu.be) + +In order to support instant sign in, your app must have the `setupKeypom` function embedded within the wallet selector with the `instantSignInSpecs` parameter specified. + +## Instant Sign In Specs + +The instant sign in specifications allows the Keypom wallet selector to support instant sign on experiences for your app. In order to trigger the sign in flow, the user must be on the correct URL. This URL is specified in the specifications as a string and should look like this: + +```js +https://near.org/#trial-url/ACCOUNT_ID/SECRET_KEY/MODULE_ID +``` + +The URL *must* have the `ACCOUNT_ID`, `SECRET_KEY`, and `MODULE_ID` placeholders. + +Behind the scenes, Keypom will take the secret key and use it to sign transactions on behalf of the account whenever they perform an action. Since this key is limited access, there needs to be a way to approve any transaction that requires full access. This is why the `MODULE_ID` field is present. This is the ID of the wallet that the user will be redirected to in order to approve any full access key required transactions. + +Currently, Keypom supports: +- MyNEARWallet: `my-near-wallet`, +- NEAR Wallet: `near-wallet`, +- SWEAT Wallet: `sweat-wallet` + +As an example, if you wanted to support instant sign in for users once they reached `https://near.org/#instant-url/`, and you wanted the account and secret key to be separated using `#`, but the module ID and secret key to be separated by `/`, your specs should look like this: + +```js +instantSignInSpecs: { + url: "https://near.org/#instant-url/ACCOUNT_ID#SECRET_KEY/MODULE_ID", +} +``` + +> **NOTE:** The account ID must come first followed by the secret key and then finally the module ID. + +The wallet selector would then look as follows. + +```js +const selector = await setupWalletSelector({ + network: NETWORK_ID, + modules: [ + setupMyNearWallet(), + ... + setupSender(), + setupKeypom({ + networkId: NETWORK_ID, + signInContractId: CONTRACT_ID, + instantSignInSpecs: { + url: "https://near.org/#instant-url/ACCOUNT_ID#SECRET_KEY/MODULE_ID" + } + }) + ], +}); +``` + +From this point onwards, any app or wallet could create a limited access key for the contract that your app is using and then redirect the user to your instant sign in URL. An example could be that that account `benjiman.near` wants to use the `near.org` app and the contract being used there is `social.near`. Benji came from MyNEARWallet and so the URL would be: + +``` +https://near.org/#instant-url/benjiman.near#3C6rhKRWLFmho9bQo32EUmk9Ldx47paRSMUdaoR551EtcaNSPziave55HJosi71tfWSRQjjRrL4exfaBi9o7XKUG/my-near-wallet +``` + +At this point, Benji would be instantly signed into `near.org` and can start using the app. If anything requires a full access key, he would be redirected to MyNEARWallet to approve the transaction and come back. + +# Contributing + +First off, thanks for taking the time to contribute! Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are **greatly appreciated**. + +Please try to create bug reports that are: + +- _Reproducible._ Include steps to reproduce the problem. +- _Specific._ Include as much detail as possible: which version, what environment, etc. +- _Unique._ Do not duplicate existing opened issues. +- _Scoped to a Single Bug._ One bug per report. + +You can use [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) to check for common markdown style inconsistency. + +# License + +This project is licensed under the **GPL License**. diff --git a/versioned_sidebars/version-1.1-sidebars.json b/versioned_sidebars/version-1.1-sidebars.json deleted file mode 100644 index 445b351d..00000000 --- a/versioned_sidebars/version-1.1-sidebars.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "version-1.1/tutorialSidebar": [ - { - "type": "autogenerated", - "dirName": "." - } - ] -} diff --git a/versioned_sidebars/version-1.2-sidebars.json b/versioned_sidebars/version-1.2-sidebars.json deleted file mode 100644 index caea0c03..00000000 --- a/versioned_sidebars/version-1.2-sidebars.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "tutorialSidebar": [ - { - "type": "autogenerated", - "dirName": "." - } - ] -} diff --git a/versioned_sidebars/version-1.2.1-sidebars.json b/versioned_sidebars/version-1.2.1-sidebars.json deleted file mode 100644 index caea0c03..00000000 --- a/versioned_sidebars/version-1.2.1-sidebars.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "tutorialSidebar": [ - { - "type": "autogenerated", - "dirName": "." - } - ] -} diff --git a/versioned_sidebars/version-2.0-sidebars.json b/versioned_sidebars/version-2.0-sidebars.json new file mode 100644 index 00000000..4670a33f --- /dev/null +++ b/versioned_sidebars/version-2.0-sidebars.json @@ -0,0 +1,180 @@ +{ + "Concepts": [ + "Concepts/welcome", + "exec-summary", + { + "type": "category", + "label": "Linkdrops and Access Keys", + "collapsed": false, + "items": [ + "Concepts/LinkdropsAndAccessKeys/near-access-keys", + "Concepts/LinkdropsAndAccessKeys/linkdrop-basics" + ] + }, + { + "type": "category", + "label": "Keypom Protocol", + "collapsed": false, + "items": [ + "Concepts/KeypomProtocol/overview", + { + "type": "category", + "label": "Types of Drops", + "collapsed": true, + "items": [ + "Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/introduction", + "Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/simple-drops", + "Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/nft-drops", + "Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/ft-drops", + "Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/fc-drops" + ] + }, + "Concepts/KeypomProtocol/balances", + { + "type": "category", + "label": "Configuring Your Drop", + "collapsed": true, + "items": [ + "Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/customization-homepage", + "Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/drop-customization", + "Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/time-customization", + "Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/usage-customization", + "Concepts/KeypomProtocol/GithubReadme/TypesOfDrops/sale-customization" + ] + }, + "Concepts/KeypomProtocol/GithubReadme/password-protect", + { + "type": "category", + "label": "Overhead Items", + "collapsed": true, + "items": [ + "Concepts/KeypomProtocol/GithubReadme/costs", + "Concepts/KeypomProtocol/GithubReadme/querying", + "Concepts/KeypomProtocol/GithubReadme/testing", + "Concepts/KeypomProtocol/GithubReadme/contribute", + "Concepts/KeypomProtocol/GithubReadme/licenses" + ] + } + ] + } + ], + "Tutorials": [ + "Tutorials/welcome", + { + "type": "category", + "label": "Basics", + "collapsed": false, + "items": [ + "Tutorials/Basics/getting-started", + "Tutorials/Basics/simple-drops", + "Tutorials/Basics/nft-drops", + "Tutorials/Basics/ft-drops", + "Tutorials/Basics/fc-drops" + ] + }, + { + "type": "category", + "label": "Advanced", + "collapsed": false, + "items": [ + { + "type": "category", + "label": "Ticketing", + "collapsed": true, + "items": [ + "Tutorials/Advanced/ticketing/introduction", + "Tutorials/Advanced/ticketing/architecture", + "Tutorials/Advanced/ticketing/drop", + "Tutorials/Advanced/ticketing/drop-test", + "Tutorials/Advanced/ticketing/react-outline", + "Tutorials/Advanced/ticketing/user-code", + "Tutorials/Advanced/ticketing/scanner-code", + "Tutorials/Advanced/ticketing/final", + "Tutorials/Advanced/ticketing/analytics", + "Tutorials/Advanced/ticketing/bos-tool" + ] + }, + { + "type": "category", + "label": "DAO Auto-Registration", + "collapsed": true, + "items": [ + "Tutorials/Advanced/daos/introduction", + "Tutorials/Advanced/daos/architecture", + "Tutorials/Advanced/daos/drop", + "Tutorials/Advanced/daos/daobot", + "Tutorials/Advanced/daos/security", + "Tutorials/Advanced/daos/final" + ] + }, + { + "type": "category", + "label": "Recurring Payments", + "collapsed": true, + "items": [ + "Tutorials/Advanced/subscriptions/introduction" + ] + } + ] + }, + { + "type": "category", + "label": "BOS", + "collapsed": false, + "items": [ + "Tutorials/BOS/welcome" + ] + }, + "Tutorials/Advanced/homepage" + ], + "TrialAccounts": [ + "TrialAccounts/introduction", + { + "type": "category", + "label": "Creating Trial Experiences", + "collapsed": false, + "items": [ + "TrialAccounts/Creation/getting-started", + "TrialAccounts/Creation/understanding-trial-accounts", + "TrialAccounts/Creation/drop-creation", + "TrialAccounts/Creation/integration" + ] + }, + "TrialAccounts/offboarding" + ], + "Cookbook": [ + "Cookbook/welcome", + { + "type": "category", + "label": "Drops", + "collapsed": false, + "items": [ + "Cookbook/drops/NEAR", + "Cookbook/drops/nft", + "Cookbook/drops/ft", + "Cookbook/drops/fc", + "Cookbook/drops/trial", + { + "type": "category", + "label": "Customizations", + "collapsed": true, + "items": [ + "Cookbook/drops/customizations/password", + "Cookbook/drops/customizations/dropConfig", + "Cookbook/drops/customizations/timeConfig", + "Cookbook/drops/customizations/saleConfig", + "Cookbook/drops/customizations/usageConfig" + ] + } + ] + }, + "Cookbook/keys", + "Cookbook/balances" + ], + "TypeDocSDK": [ + { + "type": "autogenerated", + "dirName": "keypom-sdk" + } + ] +} diff --git a/versions.json b/versions.json index 6d3d1fb8..59f17b2b 100644 --- a/versions.json +++ b/versions.json @@ -1,5 +1,3 @@ [ - "1.2.1", - "1.2", - "1.1" + "2.0" ]