diff --git a/.wordlist.txt b/.wordlist.txt index 3737f91..2b7af09 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -459,4 +459,6 @@ Kiskesis CIDs setSpecsFromKeypomParams generatePerUsePasswords -ETHGlobal \ No newline at end of file +ETHGlobal +codeblock +Keypom diff --git a/docs/Cookbook/balances.md b/docs/Cookbook/balances.md index 8ee7cd7..5145bb1 100644 --- a/docs/Cookbook/balances.md +++ b/docs/Cookbook/balances.md @@ -31,6 +31,16 @@ const userBal = await getUserBalance({ console.log('userBal: ', userBal) ``` + + + +```rust +pub fn get_user_balance( + &self, + account_id: AccountId +) -> U128 +``` + @@ -49,6 +59,14 @@ await addToBalance({ }); ``` + + + +```rust +// Attached deposit will be added to predecessor's balance +pub fn add_to_balance(&mut self) +``` + @@ -66,6 +84,13 @@ await withdrawBalance({ account: fundingAccount }) ``` + + + +```rust +// Prececessor's balance will be withdrawn to their NEAR wallet + pub fn add_to_balance(&mut self) +``` diff --git a/docs/Cookbook/drops/NEAR.md b/docs/Cookbook/drops/NEAR.md index 7ec4112..265242c 100644 --- a/docs/Cookbook/drops/NEAR.md +++ b/docs/Cookbook/drops/NEAR.md @@ -28,11 +28,30 @@ const {keys} = await createDrop({ account: fundingAccount, numKeys: 2, depositPerUseNEAR: "0.1", -}); +}); console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -73,6 +92,54 @@ while (keysAdded < numKeys) { } ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + + + + + +___ + +## Viewing Drops by Owner +To view all drops created by one account, you can use the following. + + + + +```js +// Creating drop with 0 single use keys + const dropsForOwner = await getDrops({accountId: "minqi.testnet"}); +``` + + + + +```rust +pub fn get_drops_for_owner( + &self, + account_id: AccountId, + from_index: Option, + limit: Option, +) -> Vec +``` + @@ -82,6 +149,10 @@ ___ ## 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. +The Keypom contract does not have a `deleteDrops` equivalent function. Behind the scenes of the SDK, the keys are being collected, refunded and then deleted. + +The first step in this process is to use `get_key_supply_for_drop`. Once the total key supply is found, 50 keys at a time are retrieved using `get_keys_for_drop` and refunding their associated assets and deleting the keys using `refund_assets` and `delete_keys` respectively. + @@ -102,6 +173,39 @@ await deleteDrops({ }) ``` + + + +```rust +// Get total number of keys +pub fn get_key_supply_for_drop(&self, drop_id: DropIdJson) -> u64 + +// Get 50 keys at a time, this might need to be looped depending on key supply +pub fn get_keys_for_drop( + &self, + drop_id: DropIdJson, + from_index: Option, + limit: 50, +) -> Vec + +// Refund the assets in those keys +// assets_to_refund indicated the number of assets to refund. If not specified, all assets will be attempted to be refunded. +pub fn refund_assets( + &mut self, + drop_id: DropIdJson, + assets_to_refund: Option +) + +// Delete keys that were retrieved. +pub fn delete_keys( + &mut self, + drop_id: DropIdJson, + public_keys: Option>, + limit: Option, + delete_on_empty: Option, +) +``` + diff --git a/docs/Cookbook/drops/customizations/dropConfig.md b/docs/Cookbook/drops/customizations/dropConfig.md index 32ecafd..a9ab6f8 100644 --- a/docs/Cookbook/drops/customizations/dropConfig.md +++ b/docs/Cookbook/drops/customizations/dropConfig.md @@ -36,6 +36,28 @@ const {keys} = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + uses_per_key: u64 + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -66,6 +88,30 @@ const {keys} = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + usage:{ + root_account_id: "mint-brigade.testnet" + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + diff --git a/docs/Cookbook/drops/customizations/password.md b/docs/Cookbook/drops/customizations/password.md index 84a7571..d9244bf 100644 --- a/docs/Cookbook/drops/customizations/password.md +++ b/docs/Cookbook/drops/customizations/password.md @@ -34,6 +34,32 @@ let {keys, dropId} = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + // Passwords for the keys + passwords_per_use: Option>>> +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -106,6 +132,46 @@ let {keys, dropId} = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + // Passwords for the keys + passwords_per_use: [ + [ + { + pw: hash(hash("my_first_pw")) + key_use: 1 + } + ], + [ + { + pw: "" + key_use: 2 + } + ], + [ + { + pw: hash(hash("my_next_pw")) + key_use: 3 + } + ], + ] +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -115,6 +181,10 @@ ___ ## 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. +The Keypom contract does not have a `deleteDrops` equivalent function. Behind the scenes of the SDK, the keys are being collected, refunded and then deleted. + +The first step in this process is to use `get_key_supply_for_drop`. Once the total key supply is found, 50 keys at a time are retrieved using `get_keys_for_drop` and refunding their associated assets and deleting the keys using `refund_assets` and `delete_keys` respectively. + @@ -135,6 +205,39 @@ await deleteDrops({ }) ``` + + + +```rust +// Get total number of keys +pub fn get_key_supply_for_drop(&self, drop_id: DropIdJson) -> u64 + +// Get 50 keys at a time, this might need to be looped depending on key supply +pub fn get_keys_for_drop( + &self, + drop_id: DropIdJson, + from_index: Option, + limit: 50, +) -> Vec + +// Refund the assets in those keys +// assets_to_refund indicated the number of assets to refund. If not specified, all assets will be attempted to be refunded. +pub fn refund_assets( + &mut self, + drop_id: DropIdJson, + assets_to_refund: Option +) + +// Delete keys that were retrieved. +pub fn delete_keys( + &mut self, + drop_id: DropIdJson, + public_keys: Option>, + limit: Option, + delete_on_empty: Option, +) +``` + diff --git a/docs/Cookbook/drops/customizations/saleConfig.md b/docs/Cookbook/drops/customizations/saleConfig.md index 24c49bb..0f1d3e4 100644 --- a/docs/Cookbook/drops/customizations/saleConfig.md +++ b/docs/Cookbook/drops/customizations/saleConfig.md @@ -38,6 +38,35 @@ const { keys, dropId } = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + sale:{ + /// Maximum number of keys that can be added to this drop. If None, there is no max. + max_num_keys: Option, + + /// 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. + price_per_key: Option, + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -69,6 +98,38 @@ const { keys, dropId } = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + sale:{ + /// Maximum number of keys that can be added to this drop. If None, there is no max. + max_num_keys: Option, + + /// 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. + price_per_key: Option, + + /// Which accounts are allowed to add keys? + allowlist: Option>, + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -102,6 +163,38 @@ const { keys, dropId } = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + sale:{ + /// Maximum number of keys that can be added to this drop. If None, there is no max. + max_num_keys: Option, + + /// 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. + price_per_key: Option, + + /// Which accounts are NOT allowed to add keys? + blocklist: Option>, + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -133,6 +226,19 @@ await addKeys({ }) ``` + + + +```rust +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -179,6 +285,50 @@ await addToSaleAllowlist({ }); ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + sale:{ + /// Maximum number of keys that can be added to this drop. If None, there is no max. + max_num_keys: Option, + + /// 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. + price_per_key: Option, + + /// Which accounts are NOT allowed to add keys? + allowlist: Option>, + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option + +pub fn add_to_sale_allowlist( + &mut self, + drop_id: DropIdJson, + account_ids: Vec +) + +pub fn remove_from_sale_allowlist( + &mut self, + drop_id: DropIdJson, + account_ids: Vec +) +``` + @@ -219,6 +369,50 @@ await addToSaleBlocklist({ }); ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + sale:{ + /// Maximum number of keys that can be added to this drop. If None, there is no max. + max_num_keys: Option, + + /// 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. + price_per_key: Option, + + /// Which accounts are NOT allowed to add keys? + blocklist: Option>, + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option + +pub fn add_to_sale_blocklist( + &mut self, + drop_id: DropIdJson, + account_ids: Vec +) + +pub fn remove_from_sale_blocklist( + &mut self, + drop_id: DropIdJson, + account_ids: Vec +) +``` + diff --git a/docs/Cookbook/drops/customizations/timeConfig.md b/docs/Cookbook/drops/customizations/timeConfig.md index f691c21..b0e98cb 100644 --- a/docs/Cookbook/drops/customizations/timeConfig.md +++ b/docs/Cookbook/drops/customizations/timeConfig.md @@ -47,6 +47,31 @@ const {keys, dropId} = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + time:{ + start: Option, + end: Option + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -79,6 +104,30 @@ const {keys} = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + time:{ + throttle: Option + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -123,6 +172,32 @@ const {keys} = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + time:{ + start: Option, + end: Option, + interval: Option + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + diff --git a/docs/Cookbook/drops/customizations/usageConfig.md b/docs/Cookbook/drops/customizations/usageConfig.md index 0059455..0ac8b5c 100644 --- a/docs/Cookbook/drops/customizations/usageConfig.md +++ b/docs/Cookbook/drops/customizations/usageConfig.md @@ -39,6 +39,30 @@ const { keys } = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + usage:{ + permissions: "create_account_and_claim" + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -68,6 +92,30 @@ const { keys } = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + usage:{ + permissions: "claim" + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -94,6 +142,30 @@ const { keys } = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + usage:{ + refund_deposit: true + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -121,6 +193,30 @@ const { keys } = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + usage:{ + auto_delete_drop: true + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -155,6 +251,31 @@ const { keys } = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + usage:{ + auto_withdraw: true, + auto_delete_drop: true + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -200,6 +321,34 @@ let {keys, dropId} = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config:{ + usage:{ + permissions: "create_account_and_claim", + accountCreationFields: { + funder_id_field: "funder_id" + }, + root_account_id: "mint-brigade.testnet" + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + diff --git a/docs/Cookbook/drops/fc.md b/docs/Cookbook/drops/fc.md index c8d9c2f..5d4bc70 100644 --- a/docs/Cookbook/drops/fc.md +++ b/docs/Cookbook/drops/fc.md @@ -50,6 +50,42 @@ let {keys} = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + fc: { + methods:{ + [ + { + /// Contract that will be called + receiver_id: String, + /// Method to call on receiver_id contract + method_name: String, + /// Arguments to pass in (stringified JSON) + args: String, + /// Amount of yoctoNEAR to attach along with the call + attached_deposit: U128, + } + ] + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option + +``` + @@ -106,6 +142,61 @@ let {keys} = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config: { + uses_per_key: u64 + } + fc: { + methods:{ + // First key use + [ + { + /// Contract that will be called + receiver_id: String, + /// Method to call on receiver_id contract + method_name: String, + /// Arguments to pass in (stringified JSON) + args: String, + /// Amount of yoctoNEAR to attach along with the call + attached_deposit: U128, + } + ], + // Second key use + null, + // Third key use + [ + { + /// Contract that will be called + receiver_id: String, + /// Method to call on receiver_id contract + method_name: String, + /// Arguments to pass in (stringified JSON) + args: String, + /// Amount of yoctoNEAR to attach along with the call + attached_deposit: U128, + } + ] + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option + +``` + @@ -155,6 +246,57 @@ let {keys} = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config: { + uses_per_key: u64 + } + fc: { + methods:{ + // First key use + [ + { + /// Contract that will be called + receiver_id: String, + /// Method to call on receiver_id contract + method_name: String, + /// Arguments to pass in (stringified JSON) + args: String, + /// Amount of yoctoNEAR to attach along with the call + attached_deposit: U128, + }, + null, + { + /// Contract that will be called + receiver_id: String, + /// Method to call on receiver_id contract + method_name: String, + /// Arguments to pass in (stringified JSON) + args: String, + /// Amount of yoctoNEAR to attach along with the call + attached_deposit: U128, + } + ] + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option + +``` + @@ -242,7 +384,70 @@ console.log(keys) ``` + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config: { + uses_per_key: u64 + } + fc: { + methods:{ + // First key use + [ + { + /// Contract that will be called + receiver_id: String, + /// Method to call on receiver_id contract + method_name: String, + /// Arguments to pass in (stringified JSON) + args: String, + /// Amount of yoctoNEAR to attach along with the call + attached_deposit: U128, + } + ], + // Second key use + null, + // First key use + [ + { + /// Contract that will be called + receiver_id: String, + /// Method to call on receiver_id contract + method_name: String, + /// Arguments to pass in (stringified JSON) + args: String, + /// Amount of yoctoNEAR to attach along with the call + attached_deposit: U128, + }, + { + /// Contract that will be called + receiver_id: String, + /// Method to call on receiver_id contract + method_name: String, + /// Arguments to pass in (stringified JSON) + args: String, + /// Amount of yoctoNEAR to attach along with the call + attached_deposit: U128, + } + ] + } + } +) -> Option +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option + +``` + ___ @@ -290,6 +495,54 @@ let {keys, dropId} = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + fc: { + methods:{ + [ + { + /// Contract that will be called + receiver_id: String, + /// Method to call on receiver_id contract + method_name: String, + /// Arguments to pass in (stringified JSON) + args: String, + /// Amount of yoctoNEAR to attach along with the call + attached_deposit: U128, + /// Specifies what field the claiming account ID should go in when calling the function + /// If None, this isn't attached to the args + account_id_field: Option, + /// Specifies what field the drop ID should go in when calling the function. To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + /// If Some(String), attach drop ID to args. Else, don't attach. + drop_id_field: Option, + /// Specifies what field the key ID should go in when calling the function. To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + /// If Some(String), attach key ID to args. Else, don't attach. + key_id_field: Option, + // Specifies what field the funder id should go in when calling the function. To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + // If Some(string), attach the funder ID to the args. Else, don't attach. + funder_id_field: Option, + } + ] + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option + +``` + @@ -354,6 +607,98 @@ await createNFTSeries({ }); ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + fc: { + methods:{ + [ + { + /// Contract that will be called + receiver_id: "nft-v2.keypom.testnet", + /// Method to call on receiver_id contract + method_name: "nft_mint", + /// Arguments to pass in (stringified JSON) + args: "", + /// Amount of yoctoNEAR to attach along with the call + attached_deposit: 100000000000, + /// Specifies what field the claiming account ID should go in when calling the function + /// If None, this isn't attached to the args + account_id_field: "receiver_id", + /// Specifies what field the drop ID should go in when calling the function. To insert into nested objects, use periods to separate. For example, to insert into args.metadata.field, you would specify "metadata.field" + /// If Some(String), attach drop ID to args. Else, don't attach. + drop_id_field: "mint_id", + } + ] + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option + +// create an NFT series using create_series on nft-v2.keypom.testnet +// pub fn create_series( +// &mut self, +// mint_id: Option, <-- MAKE THIS YOUR DROP ID FROM ABOVE +// metadata: { +// pub title: Option, // ex. "Arch Nemesis: Mail Carrier" or "Parcel #5055" +// pub description: Option, // free-form description +// pub media: Option, // URL to associated media, preferably to decentralized, content-addressed storage +// pub media_hash: Option, // Base64-encoded sha256 hash of content referenced by the `media` field. Required if `media` is included. +// pub copies: Option, // number of copies of this set of metadata in existence when token was minted. +// pub issued_at: Option, // When token was issued or minted, Unix epoch in milliseconds +// pub expires_at: Option, // When token expires, Unix epoch in milliseconds +// pub starts_at: Option, // When token starts being valid, Unix epoch in milliseconds +// pub updated_at: Option, // When token was last updated, Unix epoch in milliseconds +// pub extra: Option, // anything extra the NFT wants to store on-chain. Can be stringified JSON. +// pub reference: Option, // URL to an off-chain JSON file with more info. +// pub reference_hash: Option, // Base64-encoded sha256 hash of JSON from reference field. Required if `reference` is included. +// }, +// royalty: Option>, +// ) + +``` + + + + + +___ + +## Viewing Drops by Owner +To view all drops created by one account, you can use the following. + + + + +```js +// Creating drop with 0 single use keys + const dropsForOwner = await getDrops({accountId: "minqi.testnet"}); +``` + + + + +```rust +pub fn get_drops_for_owner( + &self, + account_id: AccountId, + from_index: Option, + limit: Option, +) -> Vec +``` + @@ -363,6 +708,10 @@ ___ ## 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. +The Keypom contract does not have a `deleteDrops` equivalent function. Behind the scenes of the SDK, the keys are being collected, refunded and then deleted. + +The first step in this process is to use `get_key_supply_for_drop`. Once the total key supply is found, 50 keys at a time are retrieved using `get_keys_for_drop` and refunding their associated assets and deleting the keys using `refund_assets` and `delete_keys` respectively. + @@ -383,6 +732,39 @@ await deleteDrops({ }) ``` + + + +```rust +// Get total number of keys +pub fn get_key_supply_for_drop(&self, drop_id: DropIdJson) -> u64 + +// Get 50 keys at a time, this might need to be looped depending on key supply +pub fn get_keys_for_drop( + &self, + drop_id: DropIdJson, + from_index: Option, + limit: 50, +) -> Vec + +// Refund the assets in those keys +// assets_to_refund indicated the number of assets to refund. If not specified, all assets will be attempted to be refunded. +pub fn refund_assets( + &mut self, + drop_id: DropIdJson, + assets_to_refund: Option +) + +// Delete keys that were retrieved. +pub fn delete_keys( + &mut self, + drop_id: DropIdJson, + public_keys: Option>, + limit: Option, + delete_on_empty: Option, +) +``` + diff --git a/docs/Cookbook/drops/ft.md b/docs/Cookbook/drops/ft.md index 2323182..aedda92 100644 --- a/docs/Cookbook/drops/ft.md +++ b/docs/Cookbook/drops/ft.md @@ -42,6 +42,60 @@ const { keys } = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + ft: { + contract_id: AccountId, + sender_id: Option, + balance_per_use: U128, + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option + +``` + + + + + +___ + +## Viewing Drops by Owner +To view all drops created by one account, you can use the following. + + + + +```js +// Creating drop with 0 single use keys + const dropsForOwner = await getDrops({accountId: "minqi.testnet"}); +``` + + + + +```rust +pub fn get_drops_for_owner( + &self, + account_id: AccountId, + from_index: Option, + limit: Option, +) -> Vec +``` + @@ -51,6 +105,10 @@ ___ ## 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. +The Keypom contract does not have a `deleteDrops` equivalent function. Behind the scenes of the SDK, the keys are being collected, refunded and then deleted. + +The first step in this process is to use `get_key_supply_for_drop`. Once the total key supply is found, 50 keys at a time are retrieved using `get_keys_for_drop` and refunding their associated assets and deleting the keys using `refund_assets` and `delete_keys` respectively. + @@ -71,6 +129,39 @@ await deleteDrops({ }) ``` + + + +```rust +// Get total number of keys +pub fn get_key_supply_for_drop(&self, drop_id: DropIdJson) -> u64 + +// Get 50 keys at a time, this might need to be looped depending on key supply +pub fn get_keys_for_drop( + &self, + drop_id: DropIdJson, + from_index: Option, + limit: 50, +) -> Vec + +// Refund the assets in those keys +// assets_to_refund indicated the number of assets to refund. If not specified, all assets will be attempted to be refunded. +pub fn refund_assets( + &mut self, + drop_id: DropIdJson, + assets_to_refund: Option +) + +// Delete keys that were retrieved. +pub fn delete_keys( + &mut self, + drop_id: DropIdJson, + public_keys: Option>, + limit: Option, + delete_on_empty: Option, +) +``` + diff --git a/docs/Cookbook/drops/nft.md b/docs/Cookbook/drops/nft.md index 02309f3..721262c 100644 --- a/docs/Cookbook/drops/nft.md +++ b/docs/Cookbook/drops/nft.md @@ -45,6 +45,59 @@ const { keys } = await createDrop({ console.log(keys) ``` + + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + nft: { + sender_id: Option, + contract_id: AccountId, + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option + +``` + + + + + +___ + +## Viewing Drops by Owner +To view all drops created by one account, you can use the following. + + + + +```js +// Creating drop with 0 single use keys + const dropsForOwner = await getDrops({accountId: "minqi.testnet"}); +``` + + + + +```rust +pub fn get_drops_for_owner( + &self, + account_id: AccountId, + from_index: Option, + limit: Option, +) -> Vec +``` + @@ -54,6 +107,10 @@ ___ ## 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. +The Keypom contract does not have a `deleteDrops` equivalent function. Behind the scenes of the SDK, the keys are being collected, refunded and then deleted. + +The first step in this process is to use `get_key_supply_for_drop`. Once the total key supply is found, 50 keys at a time are retrieved using `get_keys_for_drop` and refunding their associated assets and deleting the keys using `refund_assets` and `delete_keys` respectively. + @@ -74,6 +131,39 @@ await deleteDrops({ }) ``` + + + +```rust +// Get total number of keys +pub fn get_key_supply_for_drop(&self, drop_id: DropIdJson) -> u64 + +// Get 50 keys at a time, this might need to be looped depending on key supply +pub fn get_keys_for_drop( + &self, + drop_id: DropIdJson, + from_index: Option, + limit: 50, +) -> Vec + +// Refund the assets in those keys +// assets_to_refund indicated the number of assets to refund. If not specified, all assets will be attempted to be refunded. +pub fn refund_assets( + &mut self, + drop_id: DropIdJson, + assets_to_refund: Option +) + +// Delete keys that were retrieved. +pub fn delete_keys( + &mut self, + drop_id: DropIdJson, + public_keys: Option>, + limit: Option, + delete_on_empty: Option, +) +``` + diff --git a/docs/Cookbook/drops/trial.md b/docs/Cookbook/drops/trial.md index 865b8a3..479113b 100644 --- a/docs/Cookbook/drops/trial.md +++ b/docs/Cookbook/drops/trial.md @@ -20,6 +20,9 @@ These scripts will not run without the proper setup shown in the [introduction p 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. +:::tip +A short explanation for Rust version is found below the codeblock. +::: @@ -61,14 +64,83 @@ console.log(keys) ``` + + +```rust +pub fn create_drop( + &mut self, + // How much $NEAR should be transferred everytime a key is used? Can be 0. + deposit_per_use: U128, + config: { + uses_per_key: u64 + } + fc: { + methods:{ + // First key use + [ + // First method to be called will be `create_account_advanced` on the drop's `root_account_id`. + // This will be called with the args shown here: https://github.com/keypom/keypom-js/blob/5e4c7f3524c9e2b5be537a779e3ebf41bcafc357/packages/core/src/lib/trial-accounts/pre-trial.ts#L319-L333 + { + /// Contract that will be called + receiver_id: String, + /// Method to call on receiver_id contract + method_name: "create_account_advanced", + /// Arguments to pass in (stringified JSON) + args: String, + /// Amount of yoctoNEAR to attach along with the call + attached_deposit: U128, + }, + // Second method will be the `setup` method on the newly created account from above. This is done using the `receiver_to_claimer` boolean + // Args for this function call can be seen here: https://github.com/keypom/keypom-js/blob/5e4c7f3524c9e2b5be537a779e3ebf41bcafc357/packages/core/src/lib/trial-accounts/pre-trial.ts#L341-L351 + { + /// Contract that will be called + receiver_id: : "", + /// Method to call on receiver_id contract + method_name: "setup", + /// Arguments to pass in (stringified JSON) + args: String, + /// Amount of yoctoNEAR to attach along with the call + attached_deposit: U128, + /// Call newly created account + receiver_to_claimer: true + } + ] + } + } +) -> Option + +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option + +``` + +At its core, a trial account drop is just a FunctionCall drop that uses the function calls to creates an account with a contract deployed to it, and then calls the `setup` method on that newly created account. Since there is no `createTrialAccountDrop` equivalent baked into the protocol, you will need to manually setup all the FC drop arguments. + +The first half, creating an account with a contract deployed to it, is done using the [`create_account_advanced`](https://github.com/near/near-linkdrop/blob/49279e529c254fa7736465b4a39d05cb8f1e5443/src/lib.rs#L156) method. If you have used a custom drop root using the [`root_account_id`](../../keypom-sdk/Core/interfaces/ProtocolReturnedDropConfig.md#root_account_id) parameter, you must ensure the contract deployed to that account has the `create_account_advanced` method exposed. + +A sample set of arguments passed into `create_account_advanced` for a trial account drop can be found [here](https://github.com/keypom/keypom-js/blob/5e4c7f3524c9e2b5be537a779e3ebf41bcafc357/packages/core/src/lib/trial-accounts/pre-trial.ts#L319-L333). + +The second half is the `setup` method, which defines the trial account's allowed contracts, methods and max deposits etc. It's important to understand that the `setup` method is being called on the contract deployed to the trial account during `create_account_advanced`. To do this, the `receiver_to_claimer` must be set to `true`. + +A sample set of arguments passed into `setup` can be found [here](https://github.com/keypom/keypom-js/blob/5e4c7f3524c9e2b5be537a779e3ebf41bcafc357/packages/core/src/lib/trial-accounts/pre-trial.ts#L341-L351). + ___ ## 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. +The Keypom contract does not have a `deleteDrops` equivalent function. Behind the scenes of the SDK, the keys are being collected, refunded and then deleted. + +The first step in this process is to use `get_key_supply_for_drop`. Once the total key supply is found, 50 keys at a time are retrieved using `get_keys_for_drop` and refunding their associated assets and deleting the keys using `refund_assets` and `delete_keys` respectively. + @@ -89,6 +161,39 @@ await deleteDrops({ }) ``` + + + +```rust +// Get total number of keys +pub fn get_key_supply_for_drop(&self, drop_id: DropIdJson) -> u64 + +// Get 50 keys at a time, this might need to be looped depending on key supply +pub fn get_keys_for_drop( + &self, + drop_id: DropIdJson, + from_index: Option, + limit: 50, +) -> Vec + +// Refund the assets in those keys +// assets_to_refund indicated the number of assets to refund. If not specified, all assets will be attempted to be refunded. +pub fn refund_assets( + &mut self, + drop_id: DropIdJson, + assets_to_refund: Option +) + +// Delete keys that were retrieved. +pub fn delete_keys( + &mut self, + drop_id: DropIdJson, + public_keys: Option>, + limit: Option, + delete_on_empty: Option, +) +``` + diff --git a/docs/Cookbook/keys.md b/docs/Cookbook/keys.md index 1e3f9af..5b8c92b 100644 --- a/docs/Cookbook/keys.md +++ b/docs/Cookbook/keys.md @@ -38,6 +38,19 @@ const {keys} = await addKeys({ }) ``` + + + +```rust +pub fn add_keys( + &mut self, + // Public keys to add + public_keys: Vec, + // Overload the specific drop ID + drop_id: DropIdJson, +) -> Option +``` + @@ -70,6 +83,19 @@ await deleteKeys({ }) ``` + + + +```rust +pub fn delete_keys( + &mut self, + drop_id: DropIdJson, + public_keys: Option>, + limit: Option, + delete_on_empty: Option, +) +``` + @@ -94,6 +120,37 @@ const keyUsage = keyInfos[0].remaining_uses console.log(keyUsage) ``` + + + +```rust +pub fn get_key_information( + &self, + key: PublicKey +) -> Option + +// pub struct JsonKeyInfo { +// // Drop ID for the specific drop +// pub drop_id: DropIdJson, +// pub pk: PublicKey, + +// // Which use is the current key on? +// pub cur_key_use: u64, + +// // 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, +// } +``` + @@ -118,6 +175,37 @@ const keyBalance = keyInfos[0].allowance console.log(keyBalance) ``` + + + +```rust +pub fn get_key_information( + &self, + key: PublicKey +) -> Option + +// pub struct JsonKeyInfo { +// // Drop ID for the specific drop +// pub drop_id: DropIdJson, +// pub pk: PublicKey, + +// // Which use is the current key on? +// pub cur_key_use: u64, + +// // 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, +// } +``` + @@ -139,6 +227,16 @@ const keySupply = await getKeySupplyForDrop({ console.log(keySupply) ``` + + + +```rust +pub fn get_key_supply_for_drop( + &self, + drop_id: DropIdJson +) -> u64 +``` +