From 39e29718581b6bbaf2b7d4735732baa8a91bb709 Mon Sep 17 00:00:00 2001 From: Georgi Tsonev Date: Mon, 12 Aug 2024 15:10:08 +0300 Subject: [PATCH 1/5] Add missing descriptions --- .../src/fungible_token/core_impl.ts | 2 +- .../src/fungible_token/resolver.ts | 3 +++ .../src/non_fungible_token/core/resolver.ts | 2 +- .../src/non_fungible_token/token.ts | 2 +- .../src/non_fungible_token/utils.ts | 2 +- packages/near-sdk-js/README.md | 10 +++++----- packages/near-sdk-js/src/api.ts | 4 ++-- .../cli/build-tools/near-bindgen-exporter.ts | 4 ++-- packages/near-sdk-js/src/cli/post-install.ts | 4 ++-- packages/near-sdk-js/src/near-bindgen.ts | 2 +- packages/near-sdk-js/src/promise.ts | 18 +++++++++--------- packages/near-sdk-js/src/types/collections.ts | 2 +- packages/near-sdk-js/src/types/public_key.ts | 2 ++ 13 files changed, 31 insertions(+), 26 deletions(-) diff --git a/packages/near-contract-standards/src/fungible_token/core_impl.ts b/packages/near-contract-standards/src/fungible_token/core_impl.ts index 5d281316a..3be4af86f 100644 --- a/packages/near-contract-standards/src/fungible_token/core_impl.ts +++ b/packages/near-contract-standards/src/fungible_token/core_impl.ts @@ -123,7 +123,7 @@ export class FungibleToken implements FungibleTokenCore, StorageManagement, Fung // Get the unused amount from the `ft_on_transfer` call result. let unused_amount: Balance; try { - const promise_result = near.promiseResult(0).replace(/"*/g, ''); //TODO: why promiseResult returnes result with brackets? + const promise_result = near.promiseResult(0).replace(/"*/g, ''); //TODO: why promiseResult returns result with brackets? unused_amount = this.bigIntMin(amount, BigInt(promise_result)); } catch (e) { if (e.message.includes('Failed')) { diff --git a/packages/near-contract-standards/src/fungible_token/resolver.ts b/packages/near-contract-standards/src/fungible_token/resolver.ts index 6f2d0a12e..94dbbc0a0 100644 --- a/packages/near-contract-standards/src/fungible_token/resolver.ts +++ b/packages/near-contract-standards/src/fungible_token/resolver.ts @@ -1,5 +1,8 @@ import { AccountId, Balance } from "near-sdk-js"; +/** + * Provides token transfer resolve functionality. + */ export interface FungibleTokenResolver { ft_resolve_transfer({ sender_id, diff --git a/packages/near-contract-standards/src/non_fungible_token/core/resolver.ts b/packages/near-contract-standards/src/non_fungible_token/core/resolver.ts index f073653c3..be2bbc8d8 100644 --- a/packages/near-contract-standards/src/non_fungible_token/core/resolver.ts +++ b/packages/near-contract-standards/src/non_fungible_token/core/resolver.ts @@ -23,7 +23,7 @@ export interface NonFungibleTokenResolver { * @param previous_owner_id - The owner prior to the call to `nft_transfer_call` * @param receiver_id - The `receiver_id` argument given to `nft_transfer_call` * @param token_id - The `token_id` argument given to `ft_transfer_call` - * @param approvals - If using Approval Management, contract MUST provide + * @param approved_account_ids - If using Approval Management, contract MUST provide * set of original approved accounts in this argument, and restore these * approved accounts in case of revert. * diff --git a/packages/near-contract-standards/src/non_fungible_token/token.ts b/packages/near-contract-standards/src/non_fungible_token/token.ts index 09f5d002f..567aa4858 100644 --- a/packages/near-contract-standards/src/non_fungible_token/token.ts +++ b/packages/near-contract-standards/src/non_fungible_token/token.ts @@ -1,7 +1,7 @@ import { TokenMetadata } from "./metadata"; import { AccountId } from "near-sdk-js"; -/** Note that token IDs for NFTs are strings on NEAR. It's still fine to use autoincrementing numbers as unique IDs if desired, but they should be stringified. This is to make IDs more future-proof as chain-agnostic conventions and standards arise, and allows for more flexibility with considerations like bridging NFTs across chains, etc. */ +/** Note that token IDs for NFTs are strings on NEAR. It's still fine to use auto incrementing numbers as unique IDs if desired, but they should be stringified. This is to make IDs more future-proof as chain-agnostic conventions and standards arise, and allows for more flexibility with considerations like bridging NFTs across chains, etc. */ export type TokenId = string; /** In this implementation, the Token struct takes two extensions standards (metadata and approval) as optional fields, as they are frequently used in modern NFTs. */ diff --git a/packages/near-contract-standards/src/non_fungible_token/utils.ts b/packages/near-contract-standards/src/non_fungible_token/utils.ts index 97a4889ff..4fa1c7046 100644 --- a/packages/near-contract-standards/src/non_fungible_token/utils.ts +++ b/packages/near-contract-standards/src/non_fungible_token/utils.ts @@ -32,7 +32,7 @@ export function refund_deposit_to_account( } } -/** Assumes that the precedecessor will be refunded */ +/** Assumes that the predecessor will be refunded */ export function refund_deposit(storage_used: bigint): void { refund_deposit_to_account(storage_used, near.predecessorAccountId()); } diff --git a/packages/near-sdk-js/README.md b/packages/near-sdk-js/README.md index b87c215b5..cbdd32bd1 100644 --- a/packages/near-sdk-js/README.md +++ b/packages/near-sdk-js/README.md @@ -61,7 +61,7 @@ All NEAR blockchain provided functionality (host functions) are defined in `src/ ```js import { near } from "near-sdk-js"; -// near.. e.g.: +// near.. e.g.: let signer = near.signerAccountId(); ``` @@ -70,7 +70,7 @@ let signer = near.signerAccountId(); NEAR-SDK-JS is written in TypeScript, so every API function has a type specified by signature that looks familiar to JavaScript/TypeScript Developers. Two types in the signature need a special attention: - Most of the API take `bigint` instead of Number as type. This because JavaScript Number cannot hold 64 bit and 128 bit integer without losing precision. -- For those API that takes or returns raw bytes, it is a JavaScript `Uint8Array`. You can use standard `Uint8Array` methods on it or decode it to string with `decode` or `str`. The differece between `decode` and `str` is: `decode` decode the array as UTF-8 sequence. `str` simply converts each Uint8 to one char with that char code. +- For those API that takes or returns raw bytes, it is a JavaScript `Uint8Array`. You can use standard `Uint8Array` methods on it or decode it to string with `decode` or `str`. The difference between `decode` and `str` is: `decode` decode the array as UTF-8 sequence. `str` simply converts each Uint8 to one char with that char code. ### Context API @@ -465,7 +465,7 @@ someMethod() { } ``` -### Highlevel Promise APIs +### High level Promise APIs Within a contract class that decorated by `@Nearbindgen`, you can work a high level JavaScript class, called `NearPromise`. It's equivalently expressive as promise batch APIs but much shorter to write and can be chained like a JavaScript Promise. @@ -527,7 +527,7 @@ return promise; ### Types -NEAR-SDK-JS also includes type defintions that are equivalent to that in Rust SDK / nearcore. You can browse them in near-sdk-js/src/types. Most of them are just type alias to string and bigint. +NEAR-SDK-JS also includes type definitions that are equivalent to that in Rust SDK / nearcore. You can browse them in near-sdk-js/src/types. Most of them are just type alias to string and bigint. #### Public Key @@ -582,5 +582,5 @@ In order to use WSL2, follow the next steps: In case of any issues of setting up WSL2 make sure that: - Your Windows OS is up to date -- Virtualisation is turned on in BIOS +- Virtualization is turned on in BIOS - `Windows Subsystem for Linux` and `Virtual Machine Platform` are turned on in `Windows Features` (Start -> Search -> Turn Windows Feature On or Off) diff --git a/packages/near-sdk-js/src/api.ts b/packages/near-sdk-js/src/api.ts index a02108315..a29be3ea5 100644 --- a/packages/near-sdk-js/src/api.ts +++ b/packages/near-sdk-js/src/api.ts @@ -303,7 +303,7 @@ export function storageRead(key: string): string | null { } /** - * Checks for the existance of a value under the provided key in NEAR storage. + * Checks for the existence of a value under the provided key in NEAR storage. * * @param key - The key to check for in storage. */ @@ -312,7 +312,7 @@ export function storageHasKeyRaw(key: Uint8Array): boolean { } /** - * Checks for the existance of a value under the provided utf-8 string key in NEAR storage. + * Checks for the existence of a value under the provided utf-8 string key in NEAR storage. * * @param key - The utf-8 string key to check for in storage. */ diff --git a/packages/near-sdk-js/src/cli/build-tools/near-bindgen-exporter.ts b/packages/near-sdk-js/src/cli/build-tools/near-bindgen-exporter.ts index 922266d40..9c9f5ce37 100644 --- a/packages/near-sdk-js/src/cli/build-tools/near-bindgen-exporter.ts +++ b/packages/near-sdk-js/src/cli/build-tools/near-bindgen-exporter.ts @@ -189,7 +189,7 @@ function collectArguments(classId: t.Identifier): t.VariableDeclaration { } /** - * A helper function that inserts a contract method call expresion. + * A helper function that inserts a contract method call expression. * It calls the appropriate contract method and passes the collected _\_args_. * * ```typescript @@ -306,7 +306,7 @@ function executePromise(classId: t.Identifier): t.IfStatement { } /** - * A helper function that inserts the overriden function declaration into the class. + * A helper function that inserts the overridden function declaration into the class. * * @param classId - The class ID of the class being extended. * @param methodName - The name of the method being called. diff --git a/packages/near-sdk-js/src/cli/post-install.ts b/packages/near-sdk-js/src/cli/post-install.ts index e2095bc8e..3ea007ed0 100644 --- a/packages/near-sdk-js/src/cli/post-install.ts +++ b/packages/near-sdk-js/src/cli/post-install.ts @@ -18,8 +18,8 @@ const PLATFORM = os.platform(); const ARCH = os.arch(); console.log(`Current platform: ${PLATFORM}, current architecture: ${ARCH}`); -const SUPPORTED_PLATFORMS = ["linux", "darwin"]; // Unsaported platforms: 'win32', 'aix', 'freebsd', 'openbsd', 'sunos', 'android' -const SUPPORTED_ARCH = ["x64", "arm64"]; // Unsaported arch: 'arm', 'ia32', 'mips','mipsel', 'ppc', 'ppc64', 's390', 's390x', 'x32' +const SUPPORTED_PLATFORMS = ["linux", "darwin"]; // Unsupported platforms: 'win32', 'aix', 'freebsd', 'openbsd', 'sunos', 'android' +const SUPPORTED_ARCH = ["x64", "arm64"]; // Unsupported arch: 'arm', 'ia32', 'mips','mipsel', 'ppc', 'ppc64', 's390', 's390x', 'x32' if (!SUPPORTED_PLATFORMS.includes(PLATFORM)) { console.error(`Platform ${PLATFORM} is not supported at the moment`); diff --git a/packages/near-sdk-js/src/near-bindgen.ts b/packages/near-sdk-js/src/near-bindgen.ts index df1e04a2f..ec1f2653f 100644 --- a/packages/near-sdk-js/src/near-bindgen.ts +++ b/packages/near-sdk-js/src/near-bindgen.ts @@ -63,7 +63,7 @@ export function view(_empty: EmptyParameterObject): DecoratorFunction { /** * Tells the SDK to expose this function as a call function. - * Adds the neccessary checks if the function is private or payable. + * Adds the necessary checks if the function is private or payable. * * @param options - Options to configure the function behaviour. * @param options.privateFunction - Whether the function can be called by other contracts. diff --git a/packages/near-sdk-js/src/promise.ts b/packages/near-sdk-js/src/promise.ts index 5e63cb3b3..493cbac75 100644 --- a/packages/near-sdk-js/src/promise.ts +++ b/packages/near-sdk-js/src/promise.ts @@ -185,7 +185,7 @@ export class FunctionCallWeightRaw extends PromiseAction { */ export class Transfer extends PromiseAction { /** - * @param amount - The amount of NEAR to tranfer. + * @param amount - The amount of NEAR to transfer. */ constructor(public amount: Balance) { super(); @@ -203,7 +203,7 @@ export class Transfer extends PromiseAction { */ export class Stake extends PromiseAction { /** - * @param amount - The amount of NEAR to tranfer. + * @param amount - The amount of NEAR to transfer. * @param publicKey - The public key to use for staking. */ constructor(public amount: Balance, public publicKey: PublicKey) { @@ -252,7 +252,7 @@ export class AddAccessKey extends PromiseAction { * @param publicKey - The public key to add as a access key. * @param allowance - The allowance for the key in yoctoNEAR. * @param receiverId - The account ID of the receiver. - * @param functionNames - The names of funcitons to authorize. + * @param functionNames - The names of functions to authorize. * @param nonce - The nonce to use. */ constructor( @@ -301,7 +301,7 @@ export class DeleteKey extends PromiseAction { */ export class DeleteAccount extends PromiseAction { /** - * @param beneficiaryId - The beneficiary of the account deletion - the account to recieve all of the remaining funds of the deleted account. + * @param beneficiaryId - The beneficiary of the account deletion - the account to receive all of the remaining funds of the deleted account. */ constructor(public beneficiaryId: AccountId) { super(); @@ -486,7 +486,7 @@ export class NearPromise { /** * Creates a transfer promise action and adds it to the current promise. * - * @param amount - The amount of NEAR to tranfer. + * @param amount - The amount of NEAR to transfer. */ transfer(amount: Balance): NearPromise { return this.addAction(new Transfer(amount)); @@ -495,7 +495,7 @@ export class NearPromise { /** * Creates a stake promise action and adds it to the current promise. * - * @param amount - The amount of NEAR to tranfer. + * @param amount - The amount of NEAR to transfer. * @param publicKey - The public key to use for staking. */ stake(amount: Balance, publicKey: PublicKey): NearPromise { @@ -530,7 +530,7 @@ export class NearPromise { * @param publicKey - The public key to add as a access key. * @param allowance - The allowance for the key in yoctoNEAR. * @param receiverId - The account ID of the receiver. - * @param functionNames - The names of funcitons to authorize. + * @param functionNames - The names of functions to authorize. */ addAccessKey( publicKey: PublicKey, @@ -554,7 +554,7 @@ export class NearPromise { * @param publicKey - The public key to add as a access key. * @param allowance - The allowance for the key in yoctoNEAR. * @param receiverId - The account ID of the receiver. - * @param functionNames - The names of funcitons to authorize. + * @param functionNames - The names of functions to authorize. * @param nonce - The nonce to use. */ addAccessKeyWithNonce( @@ -581,7 +581,7 @@ export class NearPromise { /** * Creates a delete account promise action and adds it to the current promise. * - * @param beneficiaryId - The beneficiary of the account deletion - the account to recieve all of the remaining funds of the deleted account. + * @param beneficiaryId - The beneficiary of the account deletion - the account to receive all of the remaining funds of the deleted account. */ deleteAccount(beneficiaryId: AccountId): NearPromise { return this.addAction(new DeleteAccount(beneficiaryId)); diff --git a/packages/near-sdk-js/src/types/collections.ts b/packages/near-sdk-js/src/types/collections.ts index b48aab1e9..33c28c2eb 100644 --- a/packages/near-sdk-js/src/types/collections.ts +++ b/packages/near-sdk-js/src/types/collections.ts @@ -3,7 +3,7 @@ */ export interface GetOptions { /** - * A constructor function to call after deserializing a value. Tipically this is a constructor of the class you are storing. + * A constructor function to call after deserializing a value. Typically this is a constructor of the class you are storing. * * @param value - The value returned from deserialization - either the provided `deserializer` or default deserialization function. */ diff --git a/packages/near-sdk-js/src/types/public_key.ts b/packages/near-sdk-js/src/types/public_key.ts index 5360b7a6f..e345db4b8 100644 --- a/packages/near-sdk-js/src/types/public_key.ts +++ b/packages/near-sdk-js/src/types/public_key.ts @@ -77,6 +77,8 @@ export class UnknownCurve extends ParsePublicKeyError { /** * A abstraction on top of the NEAR public key string. + * Public key in a binary format with base58 string serialization with human-readable curve. + * The key types currently supported are `secp256k1` and `ed25519`. */ export class PublicKey { /** From bc2424064350c1ba9e3fb58c091560c44c168d4c Mon Sep 17 00:00:00 2001 From: Dimitar Daskalov Date: Tue, 13 Aug 2024 17:02:20 +0300 Subject: [PATCH 2/5] enhance parts of the documentation of methods and fix typos --- benchmark/__tests__/util.js | 2 ++ benchmark/src/deploy-contract.js | 5 +++++ benchmark/src/expensive-calc.js | 5 +++++ benchmark/src/highlevel-collection.js | 4 ++++ benchmark/src/highlevel-minimal.js | 4 ++++ benchmark/src/lowlevel-api.js | 8 ++++++++ benchmark/src/lowlevel-minimal.js | 4 ++++ .../lib/fungible_token/core_impl.js | 2 +- .../lib/fungible_token/resolver.d.ts | 18 +++++++++++++----- packages/near-sdk-js/lib/api.d.ts | 2 +- packages/near-sdk-js/lib/api.js | 2 +- packages/near-sdk-js/src/api.ts | 2 +- tests/src/alt_bn128_api.js | 2 ++ tests/src/bigint-serialization.ts | 8 ++++++++ tests/src/bytes.js | 2 ++ tests/src/context_api.js | 2 ++ tests/src/date-serialization.ts | 8 ++++++++ tests/src/decorators/payable.ts | 13 +++++++++++++ tests/src/decorators/private.ts | 13 +++++++++++++ tests/src/decorators/require_init_false.ts | 10 ++++++++++ tests/src/decorators/require_init_true.ts | 10 ++++++++++ tests/src/function-params.js | 8 +++++++- tests/src/highlevel-promise.js | 3 +++ tests/src/log_panic_api.js | 2 ++ tests/src/lookup-map.js | 12 ++++++++++++ tests/src/lookup-set.js | 11 +++++++++++ tests/src/math_api.js | 2 ++ tests/src/middlewares.ts | 5 +++++ tests/src/migrate.ts | 9 +++++++++ tests/src/model.js | 14 ++++++++++++++ tests/src/promise_api.js | 2 ++ tests/src/promise_batch_api.js | 2 ++ tests/src/public-key.js | 2 ++ tests/src/storage_api.js | 2 ++ tests/src/unordered-map.js | 16 ++++++++++++++++ tests/src/unordered-set.js | 16 ++++++++++++++++ tests/src/vector.js | 19 +++++++++++++++++++ 37 files changed, 241 insertions(+), 10 deletions(-) diff --git a/benchmark/__tests__/util.js b/benchmark/__tests__/util.js index c43f502c3..64bd14fa5 100644 --- a/benchmark/__tests__/util.js +++ b/benchmark/__tests__/util.js @@ -1,3 +1,5 @@ +// Functions consumed by the benchmark contracts tests + export function formatGas(gas) { if (gas < 10 ** 12) { let tGas = gas / 10 ** 12; diff --git a/benchmark/src/deploy-contract.js b/benchmark/src/deploy-contract.js index b5a82fa39..a73f905b8 100644 --- a/benchmark/src/deploy-contract.js +++ b/benchmark/src/deploy-contract.js @@ -1,5 +1,10 @@ import { near } from "near-sdk-js"; +/** + * Used for contract deployment. More information for that + * can be found in the README.md + * - Deploy and cross contract call + */ export function deploy_contract() { let promiseId = near.promiseBatchCreate("a.caller.test.near"); near.promiseBatchActionCreateAccount(promiseId); diff --git a/benchmark/src/expensive-calc.js b/benchmark/src/expensive-calc.js index c5a18731b..75e813a48 100644 --- a/benchmark/src/expensive-calc.js +++ b/benchmark/src/expensive-calc.js @@ -1,5 +1,10 @@ import { NearBindgen, call, near } from "near-sdk-js"; +/** + * ExpensiveCalc is connected to the expensive contract. More information for that + * can be found in the README.md + * - Computational expensive contract + */ @NearBindgen({}) export class ExpensiveCalc { @call({}) diff --git a/benchmark/src/highlevel-collection.js b/benchmark/src/highlevel-collection.js index 435951e3e..a9a2e8ed1 100644 --- a/benchmark/src/highlevel-collection.js +++ b/benchmark/src/highlevel-collection.js @@ -1,5 +1,9 @@ import { NearBindgen, call, UnorderedMap } from "near-sdk-js"; +/** + * More information for that can be found in the README.md + * - Highlevel collection + */ @NearBindgen({}) export class HighlevelCollection { constructor() { diff --git a/benchmark/src/highlevel-minimal.js b/benchmark/src/highlevel-minimal.js index f540e7eef..410278793 100644 --- a/benchmark/src/highlevel-minimal.js +++ b/benchmark/src/highlevel-minimal.js @@ -1,5 +1,9 @@ import { NearBindgen, call } from "near-sdk-js"; +/** + * More information for that can be found in the README.md + * - A highlevel minimal contract (using nearbindgen) + */ @NearBindgen({}) export class HighlevelMinimal { @call({}) diff --git a/benchmark/src/lowlevel-api.js b/benchmark/src/lowlevel-api.js index b2e1ec558..db4b18bef 100644 --- a/benchmark/src/lowlevel-api.js +++ b/benchmark/src/lowlevel-api.js @@ -1,10 +1,18 @@ import { near } from "near-sdk-js"; +/** + * Helper method for the low level api. More information for that can be found in the README.md + * - Low level API + */ export function lowlevel_storage_write() { let data = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); near.storageWriteRaw(data, data); } +/** + * Helper method for the low level api. More information for that can be found in the README.md + * - Low level API + */ export function lowlevel_storage_write_many() { let data = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); near.storageWriteRaw(data, data); diff --git a/benchmark/src/lowlevel-minimal.js b/benchmark/src/lowlevel-minimal.js index 1611536f4..de03c685b 100644 --- a/benchmark/src/lowlevel-minimal.js +++ b/benchmark/src/lowlevel-minimal.js @@ -1,3 +1,7 @@ import { near } from "near-sdk-js"; +/** + * More information for that can be found in the README.md + * - A minimal contract + */ export function empty() {} diff --git a/packages/near-contract-standards/lib/fungible_token/core_impl.js b/packages/near-contract-standards/lib/fungible_token/core_impl.js index ff180195a..01a2abd39 100644 --- a/packages/near-contract-standards/lib/fungible_token/core_impl.js +++ b/packages/near-contract-standards/lib/fungible_token/core_impl.js @@ -84,7 +84,7 @@ export class FungibleToken { // Get the unused amount from the `ft_on_transfer` call result. let unused_amount; try { - const promise_result = near.promiseResult(0).replace(/"*/g, ''); //TODO: why promiseResult returnes result with brackets? + const promise_result = near.promiseResult(0).replace(/"*/g, ''); //TODO: why promiseResult returns result with brackets? unused_amount = this.bigIntMin(amount, BigInt(promise_result)); } catch (e) { diff --git a/packages/near-contract-standards/lib/fungible_token/resolver.d.ts b/packages/near-contract-standards/lib/fungible_token/resolver.d.ts index f8d5255d9..4b2998acd 100644 --- a/packages/near-contract-standards/lib/fungible_token/resolver.d.ts +++ b/packages/near-contract-standards/lib/fungible_token/resolver.d.ts @@ -1,8 +1,16 @@ import { AccountId, Balance } from "near-sdk-js"; + +/** + * Provides token transfer resolve functionality. + */ export interface FungibleTokenResolver { - ft_resolve_transfer({ sender_id, receiver_id, amount, }: { - sender_id: AccountId; - receiver_id: AccountId; - amount: Balance; - }): Balance; + ft_resolve_transfer({ + sender_id, + receiver_id, + amount, + }: { + sender_id: AccountId; + receiver_id: AccountId; + amount: Balance; + }): Balance; } diff --git a/packages/near-sdk-js/lib/api.d.ts b/packages/near-sdk-js/lib/api.d.ts index 595388fbc..2c3b31ea5 100644 --- a/packages/near-sdk-js/lib/api.d.ts +++ b/packages/near-sdk-js/lib/api.d.ts @@ -404,7 +404,7 @@ export declare function validatorTotalStake(): bigint; * Computes multiexp on alt_bn128 curve using Pippenger's algorithm \sum_i * mul_i g_{1 i} should be equal result. * - * @param value - equence of (g1:G1, fr:Fr), where + * @param value - sequence of (g1:G1, fr:Fr), where * G1 is point (x:Fq, y:Fq) on alt_bn128, * alt_bn128 is Y^2 = X^3 + 3 curve over Fq. * `value` is encoded as packed, little-endian diff --git a/packages/near-sdk-js/lib/api.js b/packages/near-sdk-js/lib/api.js index db5127114..e52919333 100644 --- a/packages/near-sdk-js/lib/api.js +++ b/packages/near-sdk-js/lib/api.js @@ -572,7 +572,7 @@ export function validatorTotalStake() { * Computes multiexp on alt_bn128 curve using Pippenger's algorithm \sum_i * mul_i g_{1 i} should be equal result. * - * @param value - equence of (g1:G1, fr:Fr), where + * @param value - sequence of (g1:G1, fr:Fr), where * G1 is point (x:Fq, y:Fq) on alt_bn128, * alt_bn128 is Y^2 = X^3 + 3 curve over Fq. * `value` is encoded as packed, little-endian diff --git a/packages/near-sdk-js/src/api.ts b/packages/near-sdk-js/src/api.ts index a29be3ea5..172b05914 100644 --- a/packages/near-sdk-js/src/api.ts +++ b/packages/near-sdk-js/src/api.ts @@ -967,7 +967,7 @@ export function validatorTotalStake(): bigint { * Computes multiexp on alt_bn128 curve using Pippenger's algorithm \sum_i * mul_i g_{1 i} should be equal result. * - * @param value - equence of (g1:G1, fr:Fr), where + * @param value - sequence of (g1:G1, fr:Fr), where * G1 is point (x:Fq, y:Fq) on alt_bn128, * alt_bn128 is Y^2 = X^3 + 3 curve over Fq. * `value` is encoded as packed, little-endian diff --git a/tests/src/alt_bn128_api.js b/tests/src/alt_bn128_api.js index 0789d3dfa..5699fa50d 100644 --- a/tests/src/alt_bn128_api.js +++ b/tests/src/alt_bn128_api.js @@ -1,5 +1,7 @@ import { near, bytes } from "near-sdk-js"; +// Functions consumed by the altBn128PairingCheck tests + export function test_alt_bn128_g1_sum() { // Originated from https://github.com/near/nearcore/blob/8cd095ffc98a6507ed2d2a8982a6a3e42ebc1b62/runtime/near-test-contracts/estimator-contract/src/lib.rs#L557-L720 let buffer = new Uint8Array([ diff --git a/tests/src/bigint-serialization.ts b/tests/src/bigint-serialization.ts index c7f9c6038..69121b315 100644 --- a/tests/src/bigint-serialization.ts +++ b/tests/src/bigint-serialization.ts @@ -1,5 +1,13 @@ import { near, NearBindgen, call, view } from "near-sdk-js"; +/** + * Simple class used for testing of the `bigintField`. + * - Includes methods: + * - `getBigintField()` - returns the current `bigintField` value. + * - `setBigintField(args: { bigintField })` - used to change the current `bigintField` value. + * - `increment()` - increases the `bigintField` value by `1n`. + * @param bigintField - Simple bigint used for testing. + */ @NearBindgen({}) export class BigIntSerializationTest { bigintField: bigint; diff --git a/tests/src/bytes.js b/tests/src/bytes.js index a8829bf72..af868173d 100644 --- a/tests/src/bytes.js +++ b/tests/src/bytes.js @@ -1,5 +1,7 @@ import { near, bytes, str, encode, decode, assert } from "near-sdk-js"; +// Functions consumed by the bytes tests + export function log_expected_input_tests() { // log ascii string near.log("abc"); diff --git a/tests/src/context_api.js b/tests/src/context_api.js index 05a6fadb0..895ed439e 100644 --- a/tests/src/context_api.js +++ b/tests/src/context_api.js @@ -1,5 +1,7 @@ import { near, bytes } from "near-sdk-js"; +// Functions consumed by the context api tests + export function get_current_account_id() { near.valueReturn(near.currentAccountId()); } diff --git a/tests/src/date-serialization.ts b/tests/src/date-serialization.ts index aeb0e817c..9a29a7aff 100644 --- a/tests/src/date-serialization.ts +++ b/tests/src/date-serialization.ts @@ -1,5 +1,13 @@ import { near, NearBindgen, call, view } from "near-sdk-js"; +/** + * Simple class used for testing of the `dateField`. + * - Includes methods: + * - `getDateField()` - returns the current `dateField` value. + * - `setDateField(args: { dateField })` - used to change the current `dateField` value. + * - `getDateFieldAsMilliseconds()` - returns the `dateField` value in milliseconds. + * @param dateField - Simple `Date` used for testing. + */ @NearBindgen({}) export class DateSerializationTest { dateField: Date; diff --git a/tests/src/decorators/payable.ts b/tests/src/decorators/payable.ts index 5400aaf4a..7f8401e63 100644 --- a/tests/src/decorators/payable.ts +++ b/tests/src/decorators/payable.ts @@ -1,5 +1,18 @@ import { near, NearBindgen, call, view } from "near-sdk-js"; +/** + * Simple class used for testing of the `@call` decorator method with `option.payableFunction`, + * which identifies whether the function can accept an attached deposit. + * - `option.payableFunction` set to `true` + * - `option.payableFunction` set to `false` + * - Includes methods: + * - `setValueWithPayableFunction({ value })` - used to change the current value and can accept an attached deposit. + * - `setValueWithNotPayableFunction({ value })` - used to change the current value and cannot accept an attached deposit. + * - `setValueWithNotPayableFunctionByDefault({ value })` - used to change the current value and cannot accept an attached deposit, + * default behavior. + * - `getValue()` - returns the current value + * @param value - Simple string used for testing. + */ @NearBindgen({}) export class PayableTest { value: string; diff --git a/tests/src/decorators/private.ts b/tests/src/decorators/private.ts index cad023dbe..5117aeed9 100644 --- a/tests/src/decorators/private.ts +++ b/tests/src/decorators/private.ts @@ -1,5 +1,18 @@ import { near, NearBindgen, call, view } from "near-sdk-js"; +/** + * Simple class used for testing of the `@call` decorator method with `option.privateFunction`, + * which identifies whether the function can be called by other contracts. + * - `option.privateFunction` set to `true` + * - `option.privateFunction` set to `false` + * - Includes methods: + * - `setValueWithPrivateFunction({ value })` - used to change the current value and cannot be called by other contracts. + * - `setValueWithNotPrivateFunction({ value })` - used to change the current value and can be called by other contracts. + * - `setValueWithNotPrivateFunctionByDefault({ value })` - used to change the current value and can be called by other contracts, + * default behavior. + * - `getValue()` - returns the current value + * @param value - Simple string used for testing. + */ @NearBindgen({}) export class PrivateTest { value: string; diff --git a/tests/src/decorators/require_init_false.ts b/tests/src/decorators/require_init_false.ts index 5c24c597e..afb2ef6a7 100644 --- a/tests/src/decorators/require_init_false.ts +++ b/tests/src/decorators/require_init_false.ts @@ -1,5 +1,15 @@ import { near, NearBindgen, call, view, initialize } from "near-sdk-js"; +/** + * Simple class used for testing of the `NearBindgen` decorator with `option.requireInit`, + * which identifies whether the contract requires initialization or not. + * - `option.requireInit` set to `false` - Contract does not require initialization. + * - Includes methods: + * - `init()` - used for initializing the class + * - `getStatus()` - used to get the current status param + * - `setStatus()` - used to change the current status + * @param status - Simple string used for testing. + */ @NearBindgen({ requireInit: false }) export class NBTest { status: string; diff --git a/tests/src/decorators/require_init_true.ts b/tests/src/decorators/require_init_true.ts index 6d813619b..a13547bc7 100644 --- a/tests/src/decorators/require_init_true.ts +++ b/tests/src/decorators/require_init_true.ts @@ -1,5 +1,15 @@ import { near, NearBindgen, call, view, initialize } from "near-sdk-js"; +/** + * Simple class used for testing of the `NearBindgen` decorator with `option.requireInit`, + * which identifies whether the contract requires initialization or not. + * - `option.requireInit` set to `true` - Contract requires initialization. + * - Includes methods: + * - `init()` - used for initializing the class + * - `getStatus()` - used to get the current status param + * - `setStatus()` - used to change the current status + * @param status - Simple string used for testing. + */ @NearBindgen({ requireInit: true }) export class NBTest { status: string; diff --git a/tests/src/function-params.js b/tests/src/function-params.js index 18253ea1c..599ef2b18 100644 --- a/tests/src/function-params.js +++ b/tests/src/function-params.js @@ -1,7 +1,13 @@ import { NearBindgen, call, view, near } from "near-sdk-js"; /** - * Simple contract to test function parameters + * Simple contract used to test function params. + * - Includes methods: + * - `set_values({ param1, param2, param3 })` - change all the values. + * - `get_values()` - returns an object containing all the values. + * @param val1 - Simple string used for testing. + * @param val2 - Simple string used for testing. + * @param val3 - Simple string used for testing. */ @NearBindgen({}) export class FunctionParamsTestContract { diff --git a/tests/src/highlevel-promise.js b/tests/src/highlevel-promise.js index adb49883a..cf8519b27 100644 --- a/tests/src/highlevel-promise.js +++ b/tests/src/highlevel-promise.js @@ -14,6 +14,9 @@ function arrayN(n) { return [...Array(Number(n)).keys()]; } +/** + * More information about this class, can be found in - benchmark/README.md/Highlevel collection + */ @NearBindgen({}) export class HighlevelPromiseContract { @call({}) diff --git a/tests/src/log_panic_api.js b/tests/src/log_panic_api.js index 1d386ca45..f75018f0a 100644 --- a/tests/src/log_panic_api.js +++ b/tests/src/log_panic_api.js @@ -1,5 +1,7 @@ import { near, bytes } from "near-sdk-js"; +// Functions consumed by the log panic tests + export function log_expected_input_tests() { // log ascii string near.log("abc"); diff --git a/tests/src/lookup-map.js b/tests/src/lookup-map.js index 2f7cc382b..f3c08b3c9 100644 --- a/tests/src/lookup-map.js +++ b/tests/src/lookup-map.js @@ -1,6 +1,18 @@ import { NearBindgen, call, view, LookupMap } from "near-sdk-js"; import { House, Room } from "./model.js"; +/** + * Simple contract used to test `lookupMap` functionality. + * - Includes methods: + * - `get({ key })` - Get the data stored at the provided key. + * - `containsKey({ key })` - Checks whether the collection contains the value. + * - `set({ key, value })` - Store a new value at the provided key. + * - `remove_key({ key })` - Removes and retrieves the element with the provided key. + * - `extend({ kvs })` - Extends the current collection with the passed in array of key-value pairs. + * - `add_house()` - Adds a test `House` object in the `lookupMap`. + * - `get_house()` - Returns a `string` containing the `house.describe()` + `room.describe()` results. + * @param lookupMap - Simple `LookupMap` used for testing. + */ @NearBindgen({}) export class LookupMapTestContract { constructor() { diff --git a/tests/src/lookup-set.js b/tests/src/lookup-set.js index f5dc9d2a9..ce5bc3582 100644 --- a/tests/src/lookup-set.js +++ b/tests/src/lookup-set.js @@ -1,6 +1,17 @@ import { NearBindgen, call, view, LookupSet } from "near-sdk-js"; import { House, Room } from "./model.js"; +/** + * Simple contract used to test `lookupSet` functionality. + * - Includes methods: + * - `contains({ key })` - Checks whether the value is present in the set. + * - `set({ key })` - f the set did not have this value present, `true` is returned. If the set did have this value present, `false` is returned. + * - `remove_key({ key })` - Removes and retrieves the element with the provided key. + * - `extend({ keys })` - Extends the current collection with the passed array of elements. + * - `add_house({ name, rooms })` - Adds a test `House` object in the `lookupSet`. + * - `house_exist({ name, rooms })` - Checks whether the value is present in the set, `true` if present, `false` if not. + * @param lookupSet - Simple `LookupSet` used for testing. + */ @NearBindgen({}) export class LookupSetTestContract { constructor() { diff --git a/tests/src/math_api.js b/tests/src/math_api.js index b7827ab4a..1befd6ce2 100644 --- a/tests/src/math_api.js +++ b/tests/src/math_api.js @@ -1,5 +1,7 @@ import { near, bytes } from "near-sdk-js"; +// Functions consumed by the math api tests + export function test_sha256() { near.valueReturnRaw(near.sha256(bytes("tesdsst"))); } diff --git a/tests/src/middlewares.ts b/tests/src/middlewares.ts index 7ea73a164..59779472c 100644 --- a/tests/src/middlewares.ts +++ b/tests/src/middlewares.ts @@ -7,6 +7,11 @@ import { middleware, } from "near-sdk-js"; +/** + * Simple contract used for testing the `@middleware` decorator. + * The method that gets called with the same arguments that are passed to the function it is wrapping. + * @param args - Arguments that will be passed to the function - immutable. + */ @NearBindgen({ requireInit: true }) export class Contract { @initialize({}) diff --git a/tests/src/migrate.ts b/tests/src/migrate.ts index eb5cd7f8c..91d47f60a 100644 --- a/tests/src/migrate.ts +++ b/tests/src/migrate.ts @@ -1,5 +1,14 @@ import { NearBindgen, near, call, view, migrate } from "near-sdk-js"; +/** + * Simple class used for testing. + * - `option.requireInit` set to `true` - Contract requires initialization. + * - Includes methods: + * - `increase({ n })` - increases the count with the given `n` + * - `getCount()` - get the current count + * - `migrFuncValueTo18()` - set the current count to `18` + * @param count - Simple number used for testing. + */ @NearBindgen({}) export class Counter { count = 0; diff --git a/tests/src/model.js b/tests/src/model.js index 28e4e72d8..af26fe9ef 100644 --- a/tests/src/model.js +++ b/tests/src/model.js @@ -1,3 +1,10 @@ +/** + * Simple model used for testing. + * - Includes methods: + * - `describe()` - returns a string `house ${this.name} has ${this.rooms.length} rooms.` + * @param name - Simple `string` used for testing. + * @param rooms - Simple `Room[]` used for testing. + */ export class House { constructor(name, rooms) { this.name = name; @@ -9,6 +16,13 @@ export class House { } } +/** + * Simple model used for testing. + * - Includes methods: + * - `describe()` - returns a string `room ${this.name} is ${this.size}.` + * @param name - Simple `string` used for testing. + * @param size - Simple `number` used for testing. + */ export class Room { constructor(name, size) { this.name = name; diff --git a/tests/src/promise_api.js b/tests/src/promise_api.js index 0775a2624..c40f430d8 100644 --- a/tests/src/promise_api.js +++ b/tests/src/promise_api.js @@ -1,5 +1,7 @@ import { near } from "near-sdk-js"; +// Functions consumed by the promise api tests + function arrayN(n) { return [...Array(Number(n)).keys()]; } diff --git a/tests/src/promise_batch_api.js b/tests/src/promise_batch_api.js index 2e78d7dee..e63ffe69b 100644 --- a/tests/src/promise_batch_api.js +++ b/tests/src/promise_batch_api.js @@ -1,5 +1,7 @@ import { near, includeBytes } from "near-sdk-js"; +// Functions consumed by the promise batch api tests + export function test_promise_batch_stake() { let promiseId = near.promiseBatchCreate("caller2.test.near"); near.promiseBatchActionStake( diff --git a/tests/src/public-key.js b/tests/src/public-key.js index 2aff98605..818f685de 100644 --- a/tests/src/public-key.js +++ b/tests/src/public-key.js @@ -2,6 +2,8 @@ import { near } from "near-sdk-js"; import { CurveType, PublicKey } from "near-sdk-js"; import { assert } from "near-sdk-js"; +// Functions consumed by the public key tests + function runtime_validate_public_key(prefix, public_key) { let promiseId = near.promiseBatchCreate(prefix + ".pk.test.near"); near.promiseBatchActionCreateAccount(promiseId); diff --git a/tests/src/storage_api.js b/tests/src/storage_api.js index c7c7e56fe..f562cc0dd 100644 --- a/tests/src/storage_api.js +++ b/tests/src/storage_api.js @@ -1,5 +1,7 @@ import { near, bytes } from "near-sdk-js"; +// Functions consumed by the storage api tests + export function test_storage_write() { near.valueReturnRaw( bytes( diff --git a/tests/src/unordered-map.js b/tests/src/unordered-map.js index 83451c35e..889065eb8 100644 --- a/tests/src/unordered-map.js +++ b/tests/src/unordered-map.js @@ -1,6 +1,22 @@ import { NearBindgen, call, view, UnorderedMap } from "near-sdk-js"; import { House, Room } from "./model.js"; +/** + * Simple contract used for testing the `unorderedMap`. + * - Includes methods: + * - `len()` - Returns the current number of elements present in the map. + * - `isEmpty()` - Checks whether the collection is empty. + * - `get({ key })` - Get the data stored at the provided key. + * - `set({ key, value })` - Store a new value at the provided key. + * - `remove_key({ key })` - Removes and retrieves the element with the provided key. + * - `clear()` - Remove all of the elements stored within the collection. + * - `toArray()` - Return a JavaScript array of the data stored within the collection. + * - `extend({ kvs })` - Extends the current collection with the passed in array of key-value pairs. + * - `add_house()` - Store a new `House` object in the `unorderedMap` instance. + * - `get_house()` - Retrieves the current `House` object from the `unorderedMap` and returns a string `house.describe() + room.describe()` + * - `keys({ start, limit })` - Converts the deserialized data from storage to a JavaScript instance of the collection. + * @param unorderedMap - Simple `UnorderedMap` used for testing. + */ @NearBindgen({}) export class UnorderedMapTestContract { constructor() { diff --git a/tests/src/unordered-set.js b/tests/src/unordered-set.js index a40e1d197..ec9b6c90f 100644 --- a/tests/src/unordered-set.js +++ b/tests/src/unordered-set.js @@ -1,6 +1,22 @@ import { NearBindgen, call, view, UnorderedSet } from "near-sdk-js"; import { House, Room } from "./model.js"; +/** + * Simple contract used for testing the `unorderedSet`. + * - Includes methods: + * - `len()` - Returns the current number of elements present in the set. + * - `isEmpty()` - Checks whether the collection is empty. + * - `contains({ element })` - Checks whether the collection contains the value. + * - `set({ element }) ` - Store a new value at the provided key. + * - `remove_key({ element })` - Removes and retrieves the element. + * - `clear()` - Remove all of the elements stored within the collection. + * - `toArray()` - Return a JavaScript array of the data stored within the collection. + * - `elements({ start, limit })` - Converts the deserialized data from storage to a JavaScript instance of the collection. + * - `extend({ elements })` - Extends the current collection with the passed in array of elements. + * - `add_house({ name, rooms })` - Store a new `House` object in the `unorderedMap` instance. + * - `house_exist({ name, rooms })` - Checks whether the collection contains the passed `House` object. + * @param unorderedSet - Simple `UnorderedSet` used for testing. + */ @NearBindgen({}) export class UnorderedSetTestContract { constructor() { diff --git a/tests/src/vector.js b/tests/src/vector.js index d1f873784..1f304ea8e 100644 --- a/tests/src/vector.js +++ b/tests/src/vector.js @@ -1,6 +1,25 @@ import { NearBindgen, call, view, Vector } from "near-sdk-js"; import { House, Room } from "./model.js"; +/** + * Simple contract used for testing the `vector`. + * - Includes methods: + * - `len()` - Returns the current number of elements. + * - `isEmpty()` - Checks whether the collection is empty. + * - `get({ index })` - Get the value at the current index. + * - `push({ value })` - Adds data to the collection. + * - `pop()` - Removes and retrieves the element with the highest index.. + * - `clear()` - Remove all of the elements stored within the collection. + * - `toArray()` - Return a JavaScript array of the data stored within the collection. + * - `extend({ kvs })` - Extends the current collection with the passed in array of elements. + * - `replace({ index, value })` - Replaces the data stored at the provided index with the provided data and returns the previously stored data. + * - `swapRemove({ index })` - Removes an element from the vector and returns it in serialized form. + * The removed element is replaced by the last element of the vector. + * Does not preserve ordering, but is `O(1)`. + * - `add_house()` - Store a new `House` object in the `unorderedMap` instance. + * - `get_house()` - Returns the `House` object at index `0`. + * @param vector - Simple `Vector` used for testing. + */ @NearBindgen({}) export class VectorTestContract { constructor() { From 7f4c32d152c77ff1750b2fd1709e062f4bbc3e1e Mon Sep 17 00:00:00 2001 From: Dimitar Daskalov Date: Fri, 16 Aug 2024 10:45:50 +0300 Subject: [PATCH 3/5] enhance part of the documentation with examples --- .../lib/fungible_token/core.d.ts | 54 ++++++++++- .../lib/fungible_token/metadata.d.ts | 4 + .../lib/fungible_token/metadata.js | 4 + .../lib/fungible_token/receiver.d.ts | 30 +++++++ .../lib/fungible_token/resolver.d.ts | 46 ++++++++++ .../lib/non_fungible_token/core/index.d.ts | 47 ++++++++++ .../lib/non_fungible_token/core/receiver.d.ts | 90 ++++++++++++++----- .../lib/non_fungible_token/core/resolver.d.ts | 38 +++++++- 8 files changed, 288 insertions(+), 25 deletions(-) diff --git a/packages/near-contract-standards/lib/fungible_token/core.d.ts b/packages/near-contract-standards/lib/fungible_token/core.d.ts index 84daf79e3..9bd857001 100644 --- a/packages/near-contract-standards/lib/fungible_token/core.d.ts +++ b/packages/near-contract-standards/lib/fungible_token/core.d.ts @@ -1,5 +1,57 @@ import { AccountId, PromiseOrValue, Balance } from "near-sdk-js"; import { Option } from "../non_fungible_token/utils"; + +/** + * The core methods for a basic fungible token. Extension standards may be + * added in addition to this interface. + * + * # Examples + * + * ```typescript + + * import { near, call, view, AccountId, PromiseOrValue, Balance } from "near-sdk-js"; + * import { Option } from "../non_fungible_token/utils"; + * import { FungibleTokenCore, FungibleToken } from "near-contract-standards/lib" + * + * @NearBindgen({ requireInit: false }) + * export class Contract implements FungibleTokenCore { + * private token: FungibleToken; + * + * constructor() { + * this.token = new FungibleToken(); + * } + * + * @call({}) + * ft_transfer({ receiver_id, amount, memo }: { + * receiver_id: AccountId, + * amount: Balance, + * memo?: String + * }): void { + * this.token.ft_transfer({ receiver_id, amount, memo }); + * } + * + * @call({}) + * ft_transfer_call({ receiver_id, amount, memo, msg }: { + * receiver_id: AccountId, + * amount: Balance, + * memo?: Option, + * msg: String + * }): PromiseOrValue { + * return this.token.ft_transfer_call({ receiver_id, amount, memo, msg }); + * } + * + * @view({}) + * ft_total_supply(): Balance { + * return this.token.ft_total_supply(); + * } + * + * @view({}) + * ft_balance_of({ account_id }: { account_id: AccountId }): Balance { + * return this.token.ft_balance_of({ account_id }); + * } + * } + * ``` + */ export interface FungibleTokenCore { /** * Transfers positive `amount` of tokens from the `near.predecessorAccountId()` to `receiver_id`. @@ -54,5 +106,5 @@ export interface FungibleTokenCore { /** Returns the balance of the account. If the account doesn't exist must returns `"0"`. */ ft_balance_of({ account_id }: { account_id: AccountId; - }): Balance; + }): Balance; } diff --git a/packages/near-contract-standards/lib/fungible_token/metadata.d.ts b/packages/near-contract-standards/lib/fungible_token/metadata.d.ts index 5db30b4cd..ea16fd080 100644 --- a/packages/near-contract-standards/lib/fungible_token/metadata.d.ts +++ b/packages/near-contract-standards/lib/fungible_token/metadata.d.ts @@ -1,4 +1,8 @@ import { Option } from "../non_fungible_token/utils"; + +/** + * Return metadata for the token, up to contract to implement. + */ export declare class FungibleTokenMetadata { spec: string; name: string; diff --git a/packages/near-contract-standards/lib/fungible_token/metadata.js b/packages/near-contract-standards/lib/fungible_token/metadata.js index 82be61985..7067fe73d 100644 --- a/packages/near-contract-standards/lib/fungible_token/metadata.js +++ b/packages/near-contract-standards/lib/fungible_token/metadata.js @@ -1,5 +1,9 @@ import { assert, } from "near-sdk-js"; const FT_METADATA_SPEC = "ft-1.0.0"; + +/** + * Return metadata for the token, up to contract to implement. + */ export class FungibleTokenMetadata { constructor(spec, name, symbol, icon, referance, referance_hash, decimals) { this.spec = spec; diff --git a/packages/near-contract-standards/lib/fungible_token/receiver.d.ts b/packages/near-contract-standards/lib/fungible_token/receiver.d.ts index d63dfb404..f58d6b641 100644 --- a/packages/near-contract-standards/lib/fungible_token/receiver.d.ts +++ b/packages/near-contract-standards/lib/fungible_token/receiver.d.ts @@ -1,4 +1,34 @@ import { AccountId, PromiseOrValue } from "near-sdk-js"; + +/** + * Provides token transfer resolve functionality. + * + * # Examples + * + * ```typescript + + * import { AccountId, PromiseOrValue } from "near-sdk-js"; + * import { FungibleTokenCore, FungibleToken, FungibleTokenReceiver } from "near-contract-standards/lib" + * + * @NearBindgen({ requireInit: false }) + * export class Contract implements FungibleTokenCore, FungibleTokenReceiver { + * private token: FungibleToken; + * + * constructor() { + * this.token = new FungibleToken(); + * } + * + * @call({}) + * ft_on_transfer({ sender_id, amount, msg }: { + sender_id: AccountId; + amount: number; + msg: String; + }): PromiseOrValue { + return this.token.ft_on_transfer({ sender_id, amount, msg }); + }; + * } + * ``` + */ export interface FungibleTokenReceiver { /** * Called by fungible token contract after `ft_transfer_call` was initiated by diff --git a/packages/near-contract-standards/lib/fungible_token/resolver.d.ts b/packages/near-contract-standards/lib/fungible_token/resolver.d.ts index 4b2998acd..34e3366b8 100644 --- a/packages/near-contract-standards/lib/fungible_token/resolver.d.ts +++ b/packages/near-contract-standards/lib/fungible_token/resolver.d.ts @@ -2,8 +2,54 @@ import { AccountId, Balance } from "near-sdk-js"; /** * Provides token transfer resolve functionality. + * + * # Examples + * + * ```typescript + * import { AccountId, Balance, call } from "near-sdk-js"; + * import { + FungibleTokenCore, + FungibleTokenResolver, + FungibleToken, + * } from "near-contract-standards/lib" + * + * @NearBindgen({ requireInit: false }) + * export class Contract implements FungibleTokenCore, FungibleTokenResolver { + * private token: FungibleToken; + * + * constructor() { + * this.token = new FungibleToken(); + * } + * + * @call({ privateFunction: true }) + * ft_resolve_transfer({ + * sender_id, + * receiver_id, + * amount, + * }: { + * sender_id: AccountId, + * receiver_id: AccountId, + * amount: Balance + * }): Balance { + * const { used_amount, burned_amount } = this.token.internal_ft_resolve_transfer(sender_id, receiver_id, amount); + * if (burned_amount > 0) { + * console.log(`Account @${sender_id} burned ${burned_amount}`); + * } + * return used_amount; + * } + * } + * ``` */ export interface FungibleTokenResolver { + /** + * Resolves the transfer of tokens between `sender_id` and `receiver_id`. + * + * @param sender_id - The account ID of the sender. + * @param receiver_id - The account ID of the receiver. + * @param amount - The amount of tokens to resolve in a decimal string representation. + * + * @returns The amount of tokens used during the transfer, returning the balance as a `Balance`. + */ ft_resolve_transfer({ sender_id, receiver_id, diff --git a/packages/near-contract-standards/lib/non_fungible_token/core/index.d.ts b/packages/near-contract-standards/lib/non_fungible_token/core/index.d.ts index e3158367d..a7a2ba6c9 100644 --- a/packages/near-contract-standards/lib/non_fungible_token/core/index.d.ts +++ b/packages/near-contract-standards/lib/non_fungible_token/core/index.d.ts @@ -8,6 +8,53 @@ import { Option } from "../utils"; * understand how the cross-contract call work. * * [core non-fungible token standard]: + * + * # Examples + * + * ```typescript + + * import { AccountId } from "near-sdk-js"; + * import { Option } from "../non_fungible_token/utils"; + * import { Token, TokenId } from "../token"; + * import { NonFungibleTokenCore, NonFungibleToken } from "near-contract-standards/lib" + * + * @NearBindgen({ requireInit: false }) + * export class Contract implements NonFungibleTokenCore { + * private token: NonFungibleToken; + * + * constructor() { + * this.tokens = new NonFungibleToken(); + * } + * + * @call({}) + * nft_transfer({ receiver_id, token_id, approval_id, memo }: { + receiver_id: AccountId; + token_id: TokenId; + approval_id?: bigint; + memo?: string; + }): any { + * this.tokens.nft_transfer({ receiver_id, token_id, approval_id, memo }); + * } + * + * @call({}) + * nft_transfer_call({ receiver_id, token_id, approval_id, memo }: { + receiver_id: AccountId; + token_id: TokenId; + approval_id?: bigint; + memo?: string; + msg: string; + }): any { + * return this.tokens.nft_transfer_call({ receiver_id, token_id, approval_id, memo }); + * } + * + * @view({}) + * nft_token({ token_id }: { + token_id: TokenId; + }): Option { + return this.tokens.nft_token({ token_id }); + }; + * } + * ``` */ export interface NonFungibleTokenCore { /** Simple transfer. Transfer a given `token_id` from current owner to diff --git a/packages/near-contract-standards/lib/non_fungible_token/core/receiver.d.ts b/packages/near-contract-standards/lib/non_fungible_token/core/receiver.d.ts index 44048efc0..17f780aef 100644 --- a/packages/near-contract-standards/lib/non_fungible_token/core/receiver.d.ts +++ b/packages/near-contract-standards/lib/non_fungible_token/core/receiver.d.ts @@ -1,27 +1,71 @@ import { AccountId, PromiseOrValue } from "near-sdk-js"; import { TokenId } from "../token"; -/** Used when an NFT is transferred using `nft_transfer_call`. This interface is implemented on the receiving contract, not on the NFT contract. */ +/** Used when an NFT is transferred using `nft_transfer_call`. This interface is implemented on the receiving contract, not on the NFT contract. + * + * # Examples + * + * ```typescript + + * import { AccountId, PromiseOrValue } from "near-sdk-js"; + * import { TokenId } from "../token"; + * import { NonFungibleTokenCore, NonFungibleToken, NonFungibleTokenReceiver } from "near-contract-standards/lib" + * + * @NearBindgen({ requireInit: false }) + * export class Contract implements NonFungibleTokenCore, NonFungibleTokenReceiver { + * private token: NonFungibleToken; + * + * constructor() { + * this.tokens = new NonFungibleToken(); + * } + * + * @call({}) + * nft_on_transfer({ + sender_id, + previous_owner_id, + token_id, + msg, + }: { + sender_id: AccountId; + previous_owner_id: AccountId; + token_id: TokenId; + msg: string; + }): PromiseOrValue { + return this.tokens.nft_on_transfer({ + sender_id, + previous_owner_id, + token_id, + msg + }) + } + * } + * ``` +*/ export interface NonFungibleTokenReceiver { - /** Take some action after receiving a non-fungible token - * - * Requirements: - * - Contract MUST restrict calls to this function to a set of whitelisted NFT - * contracts - * - * @param sender_id - The sender of `nft_transfer_call` - * @param previous_owner_id - The account that owned the NFT prior to it being - * transferred to this contract, which can differ from `sender_id` if using - * Approval Management extension - * @param token_id - The `token_id` argument given to `nft_transfer_call` - * @param msg - Information necessary for this contract to know how to process the - * request. This may include method names and/or arguments. - * - * @returns true if token should be returned to `sender_id` - */ - nft_on_transfer({ sender_id, previous_owner_id, token_id, msg, }: { - sender_id: AccountId; - previous_owner_id: AccountId; - token_id: TokenId; - msg: string; - }): PromiseOrValue; + /** Take some action after receiving a non-fungible token + * + * Requirements: + * - Contract MUST restrict calls to this function to a set of whitelisted NFT + * contracts + * + * @param sender_id - The sender of `nft_transfer_call` + * @param previous_owner_id - The account that owned the NFT prior to it being + * transferred to this contract, which can differ from `sender_id` if using + * Approval Management extension + * @param token_id - The `token_id` argument given to `nft_transfer_call` + * @param msg - Information necessary for this contract to know how to process the + * request. This may include method names and/or arguments. + * + * @returns true if token should be returned to `sender_id` + */ + nft_on_transfer({ + sender_id, + previous_owner_id, + token_id, + msg, + }: { + sender_id: AccountId; + previous_owner_id: AccountId; + token_id: TokenId; + msg: string; + }): PromiseOrValue; } diff --git a/packages/near-contract-standards/lib/non_fungible_token/core/resolver.d.ts b/packages/near-contract-standards/lib/non_fungible_token/core/resolver.d.ts index 7dd48c2bc..75dd0751c 100644 --- a/packages/near-contract-standards/lib/non_fungible_token/core/resolver.d.ts +++ b/packages/near-contract-standards/lib/non_fungible_token/core/resolver.d.ts @@ -1,6 +1,42 @@ import { AccountId } from "near-sdk-js"; import { TokenId } from "../token"; -/** Used when an NFT is transferred using `nft_transfer_call`. This is the method that's called after `nft_on_transfer`. This interface is implemented on the NFT contract. */ +/** Used when an NFT is transferred using `nft_transfer_call`. This is the method that's called after `nft_on_transfer`. This interface is implemented on the NFT contract. + * + * # Examples + * + * ```typescript + + * import { AccountId } from "near-sdk-js"; + * import { TokenId } from "../token"; + * import { NonFungibleTokenCore, NonFungibleToken, NonFungibleTokenResolver } from "near-contract-standards/lib" + * + * @NearBindgen({ requireInit: false }) + * export class Contract implements NonFungibleTokenCore, NonFungibleTokenResolver { + * private token: NonFungibleToken; + * + * constructor() { + * this.tokens = new NonFungibleToken(); + * } + * + * @call({}) + * nft_resolve_transfer({ previous_owner_id, receiver_id, token_id, approved_account_ids, }: { + previous_owner_id: AccountId; + receiver_id: AccountId; + token_id: TokenId; + approved_account_ids?: { + [approval: AccountId]: bigint; + }; + }): boolean; { + return this.tokens.nft_resolve_transfer({ + previous_owner_id, + receiver_id, + token_id, + approved_account_ids, + }); + } + * } + * ``` +*/ export interface NonFungibleTokenResolver { /** Finalize an `nft_transfer_call` chain of cross-contract calls. * From 5cd8f627a3cccc19bc2760a9fabf3b37a1291cbd Mon Sep 17 00:00:00 2001 From: Georgi Tsonev Date: Mon, 30 Sep 2024 10:11:45 +0300 Subject: [PATCH 4/5] fix descriptions --- .../lib/fungible_token/core.d.ts | 3 +- .../lib/fungible_token/metadata.d.ts | 1 - .../lib/fungible_token/metadata.js | 1 - .../lib/fungible_token/receiver.d.ts | 3 +- .../lib/fungible_token/resolver.d.ts | 33 +++++------- .../lib/non_fungible_token/core/index.d.ts | 2 +- .../lib/non_fungible_token/core/resolver.d.ts | 6 +-- .../lib/non_fungible_token/token.d.ts | 2 +- .../lib/non_fungible_token/utils.d.ts | 2 +- .../lib/non_fungible_token/utils.js | 2 +- .../src/fungible_token/core.ts | 52 +++++++++++++++++++ .../src/fungible_token/metadata.ts | 3 ++ .../src/fungible_token/receiver.ts | 29 +++++++++++ .../src/fungible_token/resolver.ts | 48 ++++++++++++++++- .../src/non_fungible_token/core/index.ts | 47 +++++++++++++++++ .../src/non_fungible_token/core/resolver.ts | 38 +++++++++++++- packages/near-sdk-js/lib/api.d.ts | 4 +- packages/near-sdk-js/lib/api.js | 4 +- .../cli/build-tools/near-bindgen-exporter.js | 4 +- packages/near-sdk-js/lib/cli/post-install.js | 4 +- packages/near-sdk-js/lib/near-bindgen.d.ts | 2 +- packages/near-sdk-js/lib/promise.d.ts | 18 +++---- packages/near-sdk-js/lib/promise.js | 18 +++---- .../near-sdk-js/lib/types/collections.d.ts | 2 +- .../near-sdk-js/lib/types/public_key.d.ts | 2 + packages/near-sdk-js/lib/types/public_key.js | 2 + 26 files changed, 270 insertions(+), 62 deletions(-) diff --git a/packages/near-contract-standards/lib/fungible_token/core.d.ts b/packages/near-contract-standards/lib/fungible_token/core.d.ts index 9bd857001..eb98b1929 100644 --- a/packages/near-contract-standards/lib/fungible_token/core.d.ts +++ b/packages/near-contract-standards/lib/fungible_token/core.d.ts @@ -1,6 +1,5 @@ import { AccountId, PromiseOrValue, Balance } from "near-sdk-js"; import { Option } from "../non_fungible_token/utils"; - /** * The core methods for a basic fungible token. Extension standards may be * added in addition to this interface. @@ -106,5 +105,5 @@ export interface FungibleTokenCore { /** Returns the balance of the account. If the account doesn't exist must returns `"0"`. */ ft_balance_of({ account_id }: { account_id: AccountId; - }): Balance; + }): Balance; } diff --git a/packages/near-contract-standards/lib/fungible_token/metadata.d.ts b/packages/near-contract-standards/lib/fungible_token/metadata.d.ts index ea16fd080..bb9c21af5 100644 --- a/packages/near-contract-standards/lib/fungible_token/metadata.d.ts +++ b/packages/near-contract-standards/lib/fungible_token/metadata.d.ts @@ -1,5 +1,4 @@ import { Option } from "../non_fungible_token/utils"; - /** * Return metadata for the token, up to contract to implement. */ diff --git a/packages/near-contract-standards/lib/fungible_token/metadata.js b/packages/near-contract-standards/lib/fungible_token/metadata.js index 7067fe73d..ecd8c69f8 100644 --- a/packages/near-contract-standards/lib/fungible_token/metadata.js +++ b/packages/near-contract-standards/lib/fungible_token/metadata.js @@ -1,6 +1,5 @@ import { assert, } from "near-sdk-js"; const FT_METADATA_SPEC = "ft-1.0.0"; - /** * Return metadata for the token, up to contract to implement. */ diff --git a/packages/near-contract-standards/lib/fungible_token/receiver.d.ts b/packages/near-contract-standards/lib/fungible_token/receiver.d.ts index f58d6b641..b9ff12a10 100644 --- a/packages/near-contract-standards/lib/fungible_token/receiver.d.ts +++ b/packages/near-contract-standards/lib/fungible_token/receiver.d.ts @@ -1,8 +1,7 @@ import { AccountId, PromiseOrValue } from "near-sdk-js"; - /** * Provides token transfer resolve functionality. - * + * * # Examples * * ```typescript diff --git a/packages/near-contract-standards/lib/fungible_token/resolver.d.ts b/packages/near-contract-standards/lib/fungible_token/resolver.d.ts index 34e3366b8..6b73e3bf9 100644 --- a/packages/near-contract-standards/lib/fungible_token/resolver.d.ts +++ b/packages/near-contract-standards/lib/fungible_token/resolver.d.ts @@ -1,5 +1,4 @@ import { AccountId, Balance } from "near-sdk-js"; - /** * Provides token transfer resolve functionality. * @@ -41,22 +40,18 @@ import { AccountId, Balance } from "near-sdk-js"; * ``` */ export interface FungibleTokenResolver { - /** - * Resolves the transfer of tokens between `sender_id` and `receiver_id`. - * - * @param sender_id - The account ID of the sender. - * @param receiver_id - The account ID of the receiver. - * @param amount - The amount of tokens to resolve in a decimal string representation. - * - * @returns The amount of tokens used during the transfer, returning the balance as a `Balance`. - */ - ft_resolve_transfer({ - sender_id, - receiver_id, - amount, - }: { - sender_id: AccountId; - receiver_id: AccountId; - amount: Balance; - }): Balance; + /** + * Resolves the transfer of tokens between `sender_id` and `receiver_id`. + * + * @param sender_id - The account ID of the sender. + * @param receiver_id - The account ID of the receiver. + * @param amount - The amount of tokens to resolve in a decimal string representation. + * + * @returns The amount of tokens used during the transfer, returning the balance as a `Balance`. + */ + ft_resolve_transfer({ sender_id, receiver_id, amount, }: { + sender_id: AccountId; + receiver_id: AccountId; + amount: Balance; + }): Balance; } diff --git a/packages/near-contract-standards/lib/non_fungible_token/core/index.d.ts b/packages/near-contract-standards/lib/non_fungible_token/core/index.d.ts index a7a2ba6c9..41fcb1447 100644 --- a/packages/near-contract-standards/lib/non_fungible_token/core/index.d.ts +++ b/packages/near-contract-standards/lib/non_fungible_token/core/index.d.ts @@ -8,7 +8,7 @@ import { Option } from "../utils"; * understand how the cross-contract call work. * * [core non-fungible token standard]: - * + * * # Examples * * ```typescript diff --git a/packages/near-contract-standards/lib/non_fungible_token/core/resolver.d.ts b/packages/near-contract-standards/lib/non_fungible_token/core/resolver.d.ts index 75dd0751c..c34f4d68e 100644 --- a/packages/near-contract-standards/lib/non_fungible_token/core/resolver.d.ts +++ b/packages/near-contract-standards/lib/non_fungible_token/core/resolver.d.ts @@ -1,7 +1,7 @@ import { AccountId } from "near-sdk-js"; import { TokenId } from "../token"; -/** Used when an NFT is transferred using `nft_transfer_call`. This is the method that's called after `nft_on_transfer`. This interface is implemented on the NFT contract. - * +/** Used when an NFT is transferred using `nft_transfer_call`. This is the method that's called after `nft_on_transfer`. This interface is implemented on the NFT contract. + * * # Examples * * ```typescript @@ -58,7 +58,7 @@ export interface NonFungibleTokenResolver { * @param previous_owner_id - The owner prior to the call to `nft_transfer_call` * @param receiver_id - The `receiver_id` argument given to `nft_transfer_call` * @param token_id - The `token_id` argument given to `ft_transfer_call` - * @param approvals - If using Approval Management, contract MUST provide + * @param approved_account_ids - If using Approval Management, contract MUST provide * set of original approved accounts in this argument, and restore these * approved accounts in case of revert. * diff --git a/packages/near-contract-standards/lib/non_fungible_token/token.d.ts b/packages/near-contract-standards/lib/non_fungible_token/token.d.ts index cbe49f357..29f097cf9 100644 --- a/packages/near-contract-standards/lib/non_fungible_token/token.d.ts +++ b/packages/near-contract-standards/lib/non_fungible_token/token.d.ts @@ -1,6 +1,6 @@ import { TokenMetadata } from "./metadata"; import { AccountId } from "near-sdk-js"; -/** Note that token IDs for NFTs are strings on NEAR. It's still fine to use autoincrementing numbers as unique IDs if desired, but they should be stringified. This is to make IDs more future-proof as chain-agnostic conventions and standards arise, and allows for more flexibility with considerations like bridging NFTs across chains, etc. */ +/** Note that token IDs for NFTs are strings on NEAR. It's still fine to use auto incrementing numbers as unique IDs if desired, but they should be stringified. This is to make IDs more future-proof as chain-agnostic conventions and standards arise, and allows for more flexibility with considerations like bridging NFTs across chains, etc. */ export declare type TokenId = string; /** In this implementation, the Token struct takes two extensions standards (metadata and approval) as optional fields, as they are frequently used in modern NFTs. */ export declare class Token { diff --git a/packages/near-contract-standards/lib/non_fungible_token/utils.d.ts b/packages/near-contract-standards/lib/non_fungible_token/utils.d.ts index 61d03908e..506baf870 100644 --- a/packages/near-contract-standards/lib/non_fungible_token/utils.d.ts +++ b/packages/near-contract-standards/lib/non_fungible_token/utils.d.ts @@ -1,7 +1,7 @@ import { AccountId } from "near-sdk-js"; export declare function refund_storage_deposit(account_id: AccountId, storage_released: number): void; export declare function refund_deposit_to_account(storage_used: bigint, account_id: AccountId): void; -/** Assumes that the precedecessor will be refunded */ +/** Assumes that the predecessor will be refunded */ export declare function refund_deposit(storage_used: bigint): void; export declare function hash_account_id(account_id: AccountId): Uint8Array; /** Assert that at least 1 yoctoNEAR was attached. */ diff --git a/packages/near-contract-standards/lib/non_fungible_token/utils.js b/packages/near-contract-standards/lib/non_fungible_token/utils.js index a4a2ef0f7..22779d885 100644 --- a/packages/near-contract-standards/lib/non_fungible_token/utils.js +++ b/packages/near-contract-standards/lib/non_fungible_token/utils.js @@ -15,7 +15,7 @@ export function refund_deposit_to_account(storage_used, account_id) { near.promiseReturn(promise_id); } } -/** Assumes that the precedecessor will be refunded */ +/** Assumes that the predecessor will be refunded */ export function refund_deposit(storage_used) { refund_deposit_to_account(storage_used, near.predecessorAccountId()); } diff --git a/packages/near-contract-standards/src/fungible_token/core.ts b/packages/near-contract-standards/src/fungible_token/core.ts index f18152ab0..a179a8473 100644 --- a/packages/near-contract-standards/src/fungible_token/core.ts +++ b/packages/near-contract-standards/src/fungible_token/core.ts @@ -1,5 +1,57 @@ import { AccountId, PromiseOrValue, Balance } from "near-sdk-js" import { Option } from "../non_fungible_token/utils" + +/** + * The core methods for a basic fungible token. Extension standards may be + * added in addition to this interface. + * + * # Examples + * + * ```typescript + + * import { near, call, view, AccountId, PromiseOrValue, Balance } from "near-sdk-js"; + * import { Option } from "../non_fungible_token/utils"; + * import { FungibleTokenCore, FungibleToken } from "near-contract-standards/lib" + * + * @NearBindgen({ requireInit: false }) + * export class Contract implements FungibleTokenCore { + * private token: FungibleToken; + * + * constructor() { + * this.token = new FungibleToken(); + * } + * + * @call({}) + * ft_transfer({ receiver_id, amount, memo }: { + * receiver_id: AccountId, + * amount: Balance, + * memo?: String + * }): void { + * this.token.ft_transfer({ receiver_id, amount, memo }); + * } + * + * @call({}) + * ft_transfer_call({ receiver_id, amount, memo, msg }: { + * receiver_id: AccountId, + * amount: Balance, + * memo?: Option, + * msg: String + * }): PromiseOrValue { + * return this.token.ft_transfer_call({ receiver_id, amount, memo, msg }); + * } + * + * @view({}) + * ft_total_supply(): Balance { + * return this.token.ft_total_supply(); + * } + * + * @view({}) + * ft_balance_of({ account_id }: { account_id: AccountId }): Balance { + * return this.token.ft_balance_of({ account_id }); + * } + * } + * ``` + */ export interface FungibleTokenCore { /** * Transfers positive `amount` of tokens from the `near.predecessorAccountId()` to `receiver_id`. diff --git a/packages/near-contract-standards/src/fungible_token/metadata.ts b/packages/near-contract-standards/src/fungible_token/metadata.ts index 81380dc86..da89c7cba 100644 --- a/packages/near-contract-standards/src/fungible_token/metadata.ts +++ b/packages/near-contract-standards/src/fungible_token/metadata.ts @@ -6,6 +6,9 @@ import { Option } from "../non_fungible_token/utils"; const FT_METADATA_SPEC: string = "ft-1.0.0"; +/** + * Return metadata for the token, up to contract to implement. + */ export class FungibleTokenMetadata { spec: string; name: string; diff --git a/packages/near-contract-standards/src/fungible_token/receiver.ts b/packages/near-contract-standards/src/fungible_token/receiver.ts index 61f022e20..dce151994 100644 --- a/packages/near-contract-standards/src/fungible_token/receiver.ts +++ b/packages/near-contract-standards/src/fungible_token/receiver.ts @@ -1,5 +1,34 @@ import { AccountId, PromiseOrValue } from "near-sdk-js"; +/** + * Provides token transfer resolve functionality. + * + * # Examples + * + * ```typescript + + * import { AccountId, PromiseOrValue } from "near-sdk-js"; + * import { FungibleTokenCore, FungibleToken, FungibleTokenReceiver } from "near-contract-standards/lib" + * + * @NearBindgen({ requireInit: false }) + * export class Contract implements FungibleTokenCore, FungibleTokenReceiver { + * private token: FungibleToken; + * + * constructor() { + * this.token = new FungibleToken(); + * } + * + * @call({}) + * ft_on_transfer({ sender_id, amount, msg }: { + sender_id: AccountId; + amount: number; + msg: String; + }): PromiseOrValue { + return this.token.ft_on_transfer({ sender_id, amount, msg }); + }; + * } + * ``` + */ export interface FungibleTokenReceiver { /** * Called by fungible token contract after `ft_transfer_call` was initiated by diff --git a/packages/near-contract-standards/src/fungible_token/resolver.ts b/packages/near-contract-standards/src/fungible_token/resolver.ts index 94dbbc0a0..eda092bdf 100644 --- a/packages/near-contract-standards/src/fungible_token/resolver.ts +++ b/packages/near-contract-standards/src/fungible_token/resolver.ts @@ -1,9 +1,55 @@ import { AccountId, Balance } from "near-sdk-js"; -/** +/** * Provides token transfer resolve functionality. + * + * # Examples + * + * ```typescript + * import { AccountId, Balance, call } from "near-sdk-js"; + * import { + FungibleTokenCore, + FungibleTokenResolver, + FungibleToken, + * } from "near-contract-standards/lib" + * + * @NearBindgen({ requireInit: false }) + * export class Contract implements FungibleTokenCore, FungibleTokenResolver { + * private token: FungibleToken; + * + * constructor() { + * this.token = new FungibleToken(); + * } + * + * @call({ privateFunction: true }) + * ft_resolve_transfer({ + * sender_id, + * receiver_id, + * amount, + * }: { + * sender_id: AccountId, + * receiver_id: AccountId, + * amount: Balance + * }): Balance { + * const { used_amount, burned_amount } = this.token.internal_ft_resolve_transfer(sender_id, receiver_id, amount); + * if (burned_amount > 0) { + * console.log(`Account @${sender_id} burned ${burned_amount}`); + * } + * return used_amount; + * } + * } + * ``` */ export interface FungibleTokenResolver { + /** + * Resolves the transfer of tokens between `sender_id` and `receiver_id`. + * + * @param sender_id - The account ID of the sender. + * @param receiver_id - The account ID of the receiver. + * @param amount - The amount of tokens to resolve in a decimal string representation. + * + * @returns The amount of tokens used during the transfer, returning the balance as a `Balance`. + */ ft_resolve_transfer({ sender_id, receiver_id, diff --git a/packages/near-contract-standards/src/non_fungible_token/core/index.ts b/packages/near-contract-standards/src/non_fungible_token/core/index.ts index 624be9f97..f4ad83fb3 100644 --- a/packages/near-contract-standards/src/non_fungible_token/core/index.ts +++ b/packages/near-contract-standards/src/non_fungible_token/core/index.ts @@ -9,6 +9,53 @@ import { Option } from "../utils"; * understand how the cross-contract call work. * * [core non-fungible token standard]: + * + * # Examples + * + * ```typescript + + * import { AccountId } from "near-sdk-js"; + * import { Option } from "../non_fungible_token/utils"; + * import { Token, TokenId } from "../token"; + * import { NonFungibleTokenCore, NonFungibleToken } from "near-contract-standards/lib" + * + * @NearBindgen({ requireInit: false }) + * export class Contract implements NonFungibleTokenCore { + * private token: NonFungibleToken; + * + * constructor() { + * this.tokens = new NonFungibleToken(); + * } + * + * @call({}) + * nft_transfer({ receiver_id, token_id, approval_id, memo }: { + receiver_id: AccountId; + token_id: TokenId; + approval_id?: bigint; + memo?: string; + }): any { + * this.tokens.nft_transfer({ receiver_id, token_id, approval_id, memo }); + * } + * + * @call({}) + * nft_transfer_call({ receiver_id, token_id, approval_id, memo }: { + receiver_id: AccountId; + token_id: TokenId; + approval_id?: bigint; + memo?: string; + msg: string; + }): any { + * return this.tokens.nft_transfer_call({ receiver_id, token_id, approval_id, memo }); + * } + * + * @view({}) + * nft_token({ token_id }: { + token_id: TokenId; + }): Option { + return this.tokens.nft_token({ token_id }); + }; + * } + * ``` */ export interface NonFungibleTokenCore { /** Simple transfer. Transfer a given `token_id` from current owner to diff --git a/packages/near-contract-standards/src/non_fungible_token/core/resolver.ts b/packages/near-contract-standards/src/non_fungible_token/core/resolver.ts index be2bbc8d8..38a425cd1 100644 --- a/packages/near-contract-standards/src/non_fungible_token/core/resolver.ts +++ b/packages/near-contract-standards/src/non_fungible_token/core/resolver.ts @@ -1,7 +1,43 @@ import { AccountId } from "near-sdk-js"; import { TokenId } from "../token"; -/** Used when an NFT is transferred using `nft_transfer_call`. This is the method that's called after `nft_on_transfer`. This interface is implemented on the NFT contract. */ +/** Used when an NFT is transferred using `nft_transfer_call`. This is the method that's called after `nft_on_transfer`. This interface is implemented on the NFT contract. + * + * # Examples + * + * ```typescript + + * import { AccountId } from "near-sdk-js"; + * import { TokenId } from "../token"; + * import { NonFungibleTokenCore, NonFungibleToken, NonFungibleTokenResolver } from "near-contract-standards/lib" + * + * @NearBindgen({ requireInit: false }) + * export class Contract implements NonFungibleTokenCore, NonFungibleTokenResolver { + * private token: NonFungibleToken; + * + * constructor() { + * this.tokens = new NonFungibleToken(); + * } + * + * @call({}) + * nft_resolve_transfer({ previous_owner_id, receiver_id, token_id, approved_account_ids, }: { + previous_owner_id: AccountId; + receiver_id: AccountId; + token_id: TokenId; + approved_account_ids?: { + [approval: AccountId]: bigint; + }; + }): boolean; { + return this.tokens.nft_resolve_transfer({ + previous_owner_id, + receiver_id, + token_id, + approved_account_ids, + }); + } + * } + * ``` +*/ export interface NonFungibleTokenResolver { /** Finalize an `nft_transfer_call` chain of cross-contract calls. * diff --git a/packages/near-sdk-js/lib/api.d.ts b/packages/near-sdk-js/lib/api.d.ts index 2c3b31ea5..5a5f9274a 100644 --- a/packages/near-sdk-js/lib/api.d.ts +++ b/packages/near-sdk-js/lib/api.d.ts @@ -75,13 +75,13 @@ export declare function storageReadRaw(key: Uint8Array): Uint8Array | null; */ export declare function storageRead(key: string): string | null; /** - * Checks for the existance of a value under the provided key in NEAR storage. + * Checks for the existence of a value under the provided key in NEAR storage. * * @param key - The key to check for in storage. */ export declare function storageHasKeyRaw(key: Uint8Array): boolean; /** - * Checks for the existance of a value under the provided utf-8 string key in NEAR storage. + * Checks for the existence of a value under the provided utf-8 string key in NEAR storage. * * @param key - The utf-8 string key to check for in storage. */ diff --git a/packages/near-sdk-js/lib/api.js b/packages/near-sdk-js/lib/api.js index e52919333..49f915dcf 100644 --- a/packages/near-sdk-js/lib/api.js +++ b/packages/near-sdk-js/lib/api.js @@ -130,7 +130,7 @@ export function storageRead(key) { return null; } /** - * Checks for the existance of a value under the provided key in NEAR storage. + * Checks for the existence of a value under the provided key in NEAR storage. * * @param key - The key to check for in storage. */ @@ -138,7 +138,7 @@ export function storageHasKeyRaw(key) { return env.storage_has_key(key) === 1n; } /** - * Checks for the existance of a value under the provided utf-8 string key in NEAR storage. + * Checks for the existence of a value under the provided utf-8 string key in NEAR storage. * * @param key - The utf-8 string key to check for in storage. */ diff --git a/packages/near-sdk-js/lib/cli/build-tools/near-bindgen-exporter.js b/packages/near-sdk-js/lib/cli/build-tools/near-bindgen-exporter.js index 6cd1d9975..0cbf9308e 100644 --- a/packages/near-sdk-js/lib/cli/build-tools/near-bindgen-exporter.js +++ b/packages/near-sdk-js/lib/cli/build-tools/near-bindgen-exporter.js @@ -124,7 +124,7 @@ function collectArguments(classId) { ]); } /** - * A helper function that inserts a contract method call expresion. + * A helper function that inserts a contract method call expression. * It calls the appropriate contract method and passes the collected _\_args_. * * ```typescript @@ -178,7 +178,7 @@ function executePromise(classId) { ])))); } /** - * A helper function that inserts the overriden function declaration into the class. + * A helper function that inserts the overridden function declaration into the class. * * @param classId - The class ID of the class being extended. * @param methodName - The name of the method being called. diff --git a/packages/near-sdk-js/lib/cli/post-install.js b/packages/near-sdk-js/lib/cli/post-install.js index 700fee80a..1094f9418 100644 --- a/packages/near-sdk-js/lib/cli/post-install.js +++ b/packages/near-sdk-js/lib/cli/post-install.js @@ -13,8 +13,8 @@ process.chdir(DEPS); const PLATFORM = os.platform(); const ARCH = os.arch(); console.log(`Current platform: ${PLATFORM}, current architecture: ${ARCH}`); -const SUPPORTED_PLATFORMS = ["linux", "darwin"]; // Unsaported platforms: 'win32', 'aix', 'freebsd', 'openbsd', 'sunos', 'android' -const SUPPORTED_ARCH = ["x64", "arm64"]; // Unsaported arch: 'arm', 'ia32', 'mips','mipsel', 'ppc', 'ppc64', 's390', 's390x', 'x32' +const SUPPORTED_PLATFORMS = ["linux", "darwin"]; // Unsupported platforms: 'win32', 'aix', 'freebsd', 'openbsd', 'sunos', 'android' +const SUPPORTED_ARCH = ["x64", "arm64"]; // Unsupported arch: 'arm', 'ia32', 'mips','mipsel', 'ppc', 'ppc64', 's390', 's390x', 'x32' if (!SUPPORTED_PLATFORMS.includes(PLATFORM)) { console.error(`Platform ${PLATFORM} is not supported at the moment`); process.exit(1); diff --git a/packages/near-sdk-js/lib/near-bindgen.d.ts b/packages/near-sdk-js/lib/near-bindgen.d.ts index c17aaca60..af350c64b 100644 --- a/packages/near-sdk-js/lib/near-bindgen.d.ts +++ b/packages/near-sdk-js/lib/near-bindgen.d.ts @@ -20,7 +20,7 @@ export declare function initialize(_empty: EmptyParameterObject): DecoratorFunct export declare function view(_empty: EmptyParameterObject): DecoratorFunction; /** * Tells the SDK to expose this function as a call function. - * Adds the neccessary checks if the function is private or payable. + * Adds the necessary checks if the function is private or payable. * * @param options - Options to configure the function behaviour. * @param options.privateFunction - Whether the function can be called by other contracts. diff --git a/packages/near-sdk-js/lib/promise.d.ts b/packages/near-sdk-js/lib/promise.d.ts index d5f4186ff..b9b735ccb 100644 --- a/packages/near-sdk-js/lib/promise.d.ts +++ b/packages/near-sdk-js/lib/promise.d.ts @@ -121,7 +121,7 @@ export declare class FunctionCallWeightRaw extends PromiseAction { export declare class Transfer extends PromiseAction { amount: Balance; /** - * @param amount - The amount of NEAR to tranfer. + * @param amount - The amount of NEAR to transfer. */ constructor(amount: Balance); add(promiseIndex: PromiseIndex): void; @@ -135,7 +135,7 @@ export declare class Stake extends PromiseAction { amount: Balance; publicKey: PublicKey; /** - * @param amount - The amount of NEAR to tranfer. + * @param amount - The amount of NEAR to transfer. * @param publicKey - The public key to use for staking. */ constructor(amount: Balance, publicKey: PublicKey); @@ -171,7 +171,7 @@ export declare class AddAccessKey extends PromiseAction { * @param publicKey - The public key to add as a access key. * @param allowance - The allowance for the key in yoctoNEAR. * @param receiverId - The account ID of the receiver. - * @param functionNames - The names of funcitons to authorize. + * @param functionNames - The names of functions to authorize. * @param nonce - The nonce to use. */ constructor(publicKey: PublicKey, allowance: Balance, receiverId: AccountId, functionNames: string, nonce: Nonce); @@ -198,7 +198,7 @@ export declare class DeleteKey extends PromiseAction { export declare class DeleteAccount extends PromiseAction { beneficiaryId: AccountId; /** - * @param beneficiaryId - The beneficiary of the account deletion - the account to recieve all of the remaining funds of the deleted account. + * @param beneficiaryId - The beneficiary of the account deletion - the account to receive all of the remaining funds of the deleted account. */ constructor(beneficiaryId: AccountId); add(promiseIndex: PromiseIndex): void; @@ -288,13 +288,13 @@ export declare class NearPromise { /** * Creates a transfer promise action and adds it to the current promise. * - * @param amount - The amount of NEAR to tranfer. + * @param amount - The amount of NEAR to transfer. */ transfer(amount: Balance): NearPromise; /** * Creates a stake promise action and adds it to the current promise. * - * @param amount - The amount of NEAR to tranfer. + * @param amount - The amount of NEAR to transfer. * @param publicKey - The public key to use for staking. */ stake(amount: Balance, publicKey: PublicKey): NearPromise; @@ -320,7 +320,7 @@ export declare class NearPromise { * @param publicKey - The public key to add as a access key. * @param allowance - The allowance for the key in yoctoNEAR. * @param receiverId - The account ID of the receiver. - * @param functionNames - The names of funcitons to authorize. + * @param functionNames - The names of functions to authorize. */ addAccessKey(publicKey: PublicKey, allowance: Balance, receiverId: AccountId, functionNames: string): NearPromise; /** @@ -330,7 +330,7 @@ export declare class NearPromise { * @param publicKey - The public key to add as a access key. * @param allowance - The allowance for the key in yoctoNEAR. * @param receiverId - The account ID of the receiver. - * @param functionNames - The names of funcitons to authorize. + * @param functionNames - The names of functions to authorize. * @param nonce - The nonce to use. */ addAccessKeyWithNonce(publicKey: PublicKey, allowance: Balance, receiverId: AccountId, functionNames: string, nonce: Nonce): NearPromise; @@ -343,7 +343,7 @@ export declare class NearPromise { /** * Creates a delete account promise action and adds it to the current promise. * - * @param beneficiaryId - The beneficiary of the account deletion - the account to recieve all of the remaining funds of the deleted account. + * @param beneficiaryId - The beneficiary of the account deletion - the account to receive all of the remaining funds of the deleted account. */ deleteAccount(beneficiaryId: AccountId): NearPromise; /** diff --git a/packages/near-sdk-js/lib/promise.js b/packages/near-sdk-js/lib/promise.js index b29c840df..e0528352d 100644 --- a/packages/near-sdk-js/lib/promise.js +++ b/packages/near-sdk-js/lib/promise.js @@ -135,7 +135,7 @@ export class FunctionCallWeightRaw extends PromiseAction { */ export class Transfer extends PromiseAction { /** - * @param amount - The amount of NEAR to tranfer. + * @param amount - The amount of NEAR to transfer. */ constructor(amount) { super(); @@ -152,7 +152,7 @@ export class Transfer extends PromiseAction { */ export class Stake extends PromiseAction { /** - * @param amount - The amount of NEAR to tranfer. + * @param amount - The amount of NEAR to transfer. * @param publicKey - The public key to use for staking. */ constructor(amount, publicKey) { @@ -193,7 +193,7 @@ export class AddAccessKey extends PromiseAction { * @param publicKey - The public key to add as a access key. * @param allowance - The allowance for the key in yoctoNEAR. * @param receiverId - The account ID of the receiver. - * @param functionNames - The names of funcitons to authorize. + * @param functionNames - The names of functions to authorize. * @param nonce - The nonce to use. */ constructor(publicKey, allowance, receiverId, functionNames, nonce) { @@ -232,7 +232,7 @@ export class DeleteKey extends PromiseAction { */ export class DeleteAccount extends PromiseAction { /** - * @param beneficiaryId - The beneficiary of the account deletion - the account to recieve all of the remaining funds of the deleted account. + * @param beneficiaryId - The beneficiary of the account deletion - the account to receive all of the remaining funds of the deleted account. */ constructor(beneficiaryId) { super(); @@ -367,7 +367,7 @@ export class NearPromise { /** * Creates a transfer promise action and adds it to the current promise. * - * @param amount - The amount of NEAR to tranfer. + * @param amount - The amount of NEAR to transfer. */ transfer(amount) { return this.addAction(new Transfer(amount)); @@ -375,7 +375,7 @@ export class NearPromise { /** * Creates a stake promise action and adds it to the current promise. * - * @param amount - The amount of NEAR to tranfer. + * @param amount - The amount of NEAR to transfer. * @param publicKey - The public key to use for staking. */ stake(amount, publicKey) { @@ -407,7 +407,7 @@ export class NearPromise { * @param publicKey - The public key to add as a access key. * @param allowance - The allowance for the key in yoctoNEAR. * @param receiverId - The account ID of the receiver. - * @param functionNames - The names of funcitons to authorize. + * @param functionNames - The names of functions to authorize. */ addAccessKey(publicKey, allowance, receiverId, functionNames) { return this.addAccessKeyWithNonce(publicKey, allowance, receiverId, functionNames, 0n); @@ -419,7 +419,7 @@ export class NearPromise { * @param publicKey - The public key to add as a access key. * @param allowance - The allowance for the key in yoctoNEAR. * @param receiverId - The account ID of the receiver. - * @param functionNames - The names of funcitons to authorize. + * @param functionNames - The names of functions to authorize. * @param nonce - The nonce to use. */ addAccessKeyWithNonce(publicKey, allowance, receiverId, functionNames, nonce) { @@ -436,7 +436,7 @@ export class NearPromise { /** * Creates a delete account promise action and adds it to the current promise. * - * @param beneficiaryId - The beneficiary of the account deletion - the account to recieve all of the remaining funds of the deleted account. + * @param beneficiaryId - The beneficiary of the account deletion - the account to receive all of the remaining funds of the deleted account. */ deleteAccount(beneficiaryId) { return this.addAction(new DeleteAccount(beneficiaryId)); diff --git a/packages/near-sdk-js/lib/types/collections.d.ts b/packages/near-sdk-js/lib/types/collections.d.ts index c67d1724a..773fc3197 100644 --- a/packages/near-sdk-js/lib/types/collections.d.ts +++ b/packages/near-sdk-js/lib/types/collections.d.ts @@ -3,7 +3,7 @@ */ export interface GetOptions { /** - * A constructor function to call after deserializing a value. Tipically this is a constructor of the class you are storing. + * A constructor function to call after deserializing a value. Typically this is a constructor of the class you are storing. * * @param value - The value returned from deserialization - either the provided `deserializer` or default deserialization function. */ diff --git a/packages/near-sdk-js/lib/types/public_key.d.ts b/packages/near-sdk-js/lib/types/public_key.d.ts index 6b31d021b..cfa7bef2e 100644 --- a/packages/near-sdk-js/lib/types/public_key.d.ts +++ b/packages/near-sdk-js/lib/types/public_key.d.ts @@ -19,6 +19,8 @@ export declare class UnknownCurve extends ParsePublicKeyError { } /** * A abstraction on top of the NEAR public key string. + * Public key in a binary format with base58 string serialization with human-readable curve. + * The key types currently supported are `secp256k1` and `ed25519`. */ export declare class PublicKey { /** diff --git a/packages/near-sdk-js/lib/types/public_key.js b/packages/near-sdk-js/lib/types/public_key.js index f778e20ce..2c0a7bca6 100644 --- a/packages/near-sdk-js/lib/types/public_key.js +++ b/packages/near-sdk-js/lib/types/public_key.js @@ -75,6 +75,8 @@ export class UnknownCurve extends ParsePublicKeyError { } /** * A abstraction on top of the NEAR public key string. + * Public key in a binary format with base58 string serialization with human-readable curve. + * The key types currently supported are `secp256k1` and `ed25519`. */ export class PublicKey { /** From 0270ec87a1841588c5bf7a3eaf5b2558d3ca2088 Mon Sep 17 00:00:00 2001 From: Georgi Tsonev Date: Mon, 30 Sep 2024 16:48:44 +0300 Subject: [PATCH 5/5] fix formatting --- .../lib/fungible_token/receiver.d.ts | 14 +++++++------- .../lib/fungible_token/resolver.d.ts | 6 +++--- .../src/fungible_token/receiver.ts | 14 +++++++------- .../src/fungible_token/resolver.ts | 6 +++--- 4 files changed, 20 insertions(+), 20 deletions(-) diff --git a/packages/near-contract-standards/lib/fungible_token/receiver.d.ts b/packages/near-contract-standards/lib/fungible_token/receiver.d.ts index b9ff12a10..a35770c4c 100644 --- a/packages/near-contract-standards/lib/fungible_token/receiver.d.ts +++ b/packages/near-contract-standards/lib/fungible_token/receiver.d.ts @@ -17,14 +17,14 @@ import { AccountId, PromiseOrValue } from "near-sdk-js"; * this.token = new FungibleToken(); * } * - * @call({}) + * @call({}) * ft_on_transfer({ sender_id, amount, msg }: { - sender_id: AccountId; - amount: number; - msg: String; - }): PromiseOrValue { - return this.token.ft_on_transfer({ sender_id, amount, msg }); - }; + * sender_id: AccountId; + * amount: number; + * msg: String; + * }): PromiseOrValue { + * return this.token.ft_on_transfer({ sender_id, amount, msg }); + * }; * } * ``` */ diff --git a/packages/near-contract-standards/lib/fungible_token/resolver.d.ts b/packages/near-contract-standards/lib/fungible_token/resolver.d.ts index 6b73e3bf9..9c2424f11 100644 --- a/packages/near-contract-standards/lib/fungible_token/resolver.d.ts +++ b/packages/near-contract-standards/lib/fungible_token/resolver.d.ts @@ -7,9 +7,9 @@ import { AccountId, Balance } from "near-sdk-js"; * ```typescript * import { AccountId, Balance, call } from "near-sdk-js"; * import { - FungibleTokenCore, - FungibleTokenResolver, - FungibleToken, + * FungibleTokenCore, + * FungibleTokenResolver, + * FungibleToken, * } from "near-contract-standards/lib" * * @NearBindgen({ requireInit: false }) diff --git a/packages/near-contract-standards/src/fungible_token/receiver.ts b/packages/near-contract-standards/src/fungible_token/receiver.ts index dce151994..963b97d7b 100644 --- a/packages/near-contract-standards/src/fungible_token/receiver.ts +++ b/packages/near-contract-standards/src/fungible_token/receiver.ts @@ -18,14 +18,14 @@ import { AccountId, PromiseOrValue } from "near-sdk-js"; * this.token = new FungibleToken(); * } * - * @call({}) + * @call({}) * ft_on_transfer({ sender_id, amount, msg }: { - sender_id: AccountId; - amount: number; - msg: String; - }): PromiseOrValue { - return this.token.ft_on_transfer({ sender_id, amount, msg }); - }; + * sender_id: AccountId; + * amount: number; + * msg: String; + * }): PromiseOrValue { + * return this.token.ft_on_transfer({ sender_id, amount, msg }); + * }; * } * ``` */ diff --git a/packages/near-contract-standards/src/fungible_token/resolver.ts b/packages/near-contract-standards/src/fungible_token/resolver.ts index eda092bdf..4a41a3d1f 100644 --- a/packages/near-contract-standards/src/fungible_token/resolver.ts +++ b/packages/near-contract-standards/src/fungible_token/resolver.ts @@ -8,9 +8,9 @@ import { AccountId, Balance } from "near-sdk-js"; * ```typescript * import { AccountId, Balance, call } from "near-sdk-js"; * import { - FungibleTokenCore, - FungibleTokenResolver, - FungibleToken, + * FungibleTokenCore, + * FungibleTokenResolver, + * FungibleToken, * } from "near-contract-standards/lib" * * @NearBindgen({ requireInit: false })