naxios

وعد على أساس العقد ، بالقرب من المحفظة ، وبالقرب من عميل RPC للمستعرض. تم تصميم هذا لتسهيل تكامل رد الفعل مع قرب blockchain وتجنب صفيحة ضخمة لإنشاء محفظة وعقد.

الوثائق

جدول المحتويات

• سمات
• التثبيت
• كيفية استخدام
• utils
• المساهمة

سمات

• تكامل محفظة وعقد مبسطة
• يدعم واجهة برمجة تطبيقات الوعد
• من السهل إنشاء واجهة عقد
• وسيطة اتصال المحفظة ليتم استخدامها بسهولة
• التحويلات التلقائية لبيانات JSON
• الأحداث الجانبية للعميل لمعرفة متى تكون واجهة برمجة التطبيقات جاهزة
• خطافات رد فعل مفيدة
• نظام ذاكرة التخزين المؤقت view العقد

التثبيت

باستخدام NPM:

 # You can use any wallet selector version you want
npm install @wpdas/naxios @near-wallet-selector/[email protected]

باستخدام الغزل:

 # You can use any wallet selector version you want
yarn add @wpdas/naxios @near-wallet-selector/[email protected]

كيفية استخدام

إعداده

استيراد أنماط محدد المحفظة القريبة. يحتاج التطبيق إلى جعل محدد المحفظة بشكل صحيح.

 import '@near-wallet-selector/modal-ui/styles.css'

باستخدامه

من السهل للغاية الحصول على محفظة و/أو تعاقد مع واجهة برمجة تطبيقات في مكانها مرة واحدة. ألقِ نظرة:

 // web3Api.ts
import naxios from '@wpdas/naxios'

const naxiosInstance = new naxios ( {
  rpcNodeUrl : 'https://free.rpc.fastnear.com' , // optional
  contractId : CONTRACT_ID ,
  network : 'testnet' ,
} )

/**
 * NEAR Wallet API (Must be a single instance)
 */
export const walletApi = naxiosInstance . walletApi ( )

// Examples of contract API instance usage

/**
 * Contract API
 * This is going to use default contractId (CONTRACT_ID)
 */
export const contractApi = naxiosInstance . contractApi ( )

/**
 * Another Contract API
 */
export const socialDBcontractApi = naxiosInstance . contractApi ( { contractId : 'v1.social08.testnet' } )

/**
 * Greeting Contract API
 */
export const greetingContractApi = naxiosInstance . contractApi ( {
  contractId : 'dev-1692221685438-15421910364142' ,
} )

/**
 * NEAR RPC API
 */
export const rpcApi = naxiosInstance . rpcApi ( ) 

فتح وسيط محدد محفظة تسجيل الدخول

يمكنك فتح مشروط محدد المحفظة القريب عن طريق استدعاء signInModal() :

 import { walletApi } from './web3Api'

walletApi . signInModal ( ) 

تخصيص خيارات المحافظ لمحدد المحفظة القريب

بشكل افتراضي ، لا يستخدم Naxios سوى @قرب المحفوظات/المحفوظات الخاصة بي كوسيلة لتوصيل المحفظة. ومع ذلك ، يمكنك إضافة محددات محفظة أخرى على النحو التالي:

npm install @near-wallet-selector/ledger @near-wallet-selector/my-near-wallet

بعد ذلك ، يمكنك بدء Naxius على النحو التالي:

 import naxios from '@wpdas/naxios'
import { setupMyNearWallet } from '@near-wallet-selector/my-near-wallet'
import { setupLedger } from '@near-wallet-selector/ledger'

const naxiosInstance = new naxios ( {
  contractId : CONTRACT_ID ,
  network : 'testnet' , // or mainnet, localnet
  walletSelectorModules : [ setupMyNearWallet ( ) , setupLedger ( ) ] ,
} )

/**
 * NEAR Wallet API (Must be a single instance)
 */
export const walletApi = naxiosInstance . walletApi ( )

اكتشف جميع محددات المحفظة القريبة هنا: محدد محفظة بالقرب من

مرجع العقد API

• view : قم بإجراء مكالمة للقراءة فقط لاسترداد المعلومات من الشبكة. لديها المعلمات التالية:
  • method : اسم طريقة العقد.
  • props? : معلمة اختيارية مع args لطريقة العقد.
  • config? : حاليا ، هذا لديه فقط useCache prop. عندما يكون Usecache صحيحًا ، فإن هذا سيستخدم البيانات المخزنة مؤقتًا غير متوقعة بدلاً من استدعاء طريقة العقد.
• call : استدعاء طريقة تغير حالة العقد. هذا مستحق الدفع. لديها المعلمات التالية:
  • method : اسم طريقة العقد
  • props? : معلمة اختيارية مع args لطريقة العقد ، gas ، deposit ليتم إرفاقها وربط callbackUrl إذا كنت ترغب في نقل المستخدم إلى صفحة معينة بعد نجاح المعاملة.
• callMultiple : اتصل بأساليب متعددة تغير حالة العقد. هذا مستحق الدفع وله المعلمات التالية:
  • transactionsList : قائمة الدعائم المعاملة. يمكنك استخدام buildTransaction(...) لمساعدتك
  • callbackUrl? : صفحة لنقل المستخدم إلى ما بعد تنجح جميع المعاملات.

مرجع API محفظة

• accounts : حسابات موقعة.
• accountId : معرف الحساب الرئيسي/الأول الموقّع في قائمة الحسابات.
• contractId : معرف العقد.
• initNear : تهيئة اتصال إلى blockchain القريبة. وهذا ما يسمى تلقائيا عندما يكون هناك أي تفاعل عقد.
• network : الشبكة الحالية ( testnet ، mainnet أو localnet ).
• recentlySignedInWallets : إرجاع معرف 5 من 5 موقعة مؤخرا في المحافظ.
• selectedWalletId : معرف محفظة محدد
• signInModal : افتح علامة محفظة Signin.
• wallet : مثيل محفظة.
• walletSelector : WalletSelector مثال.

عرض العقد

استخدام طريقة view مجانية.

 import { greetingContractApi } from './web3Api'

// [free]
greetingContractApi . view < string > ( 'get_greeting' ) . then ( ( response ) => console . log ( response ) )

مكالمة العقد

تحتاج إلى دفع ثمن كل طلب تقوم بتقديمه لطريقة call . هذا سيغير البيانات وتخزينها داخل blockchain.

 import { greetingContractApi } from './web3Api'

// Set greeting [payable]
const args : { message : 'Hi there!!!' }
greetingContractApi . call < string | undefined > ( 'set_greeting' , args ) . then ( ( response ) => console . log ( response || 'done!' ) )

عقد مكالمات متعددة في وقت واحد

بالإضافة إلى call ، ستحتاج إلى دفع مقابل كل طلب تقدمه. هذا سيغير البيانات وتخزينها داخل blockchain.

 import { buildTransaction } from '@wpdas/naxios'
import { contractApi } from './web3Api'

// Using the default instance's contract
const transactionA = buildTransaction ( 'set_greeting' , { args : { greeting : 'Hello my dear!' } } )
const transactionB = buildTransaction ( 'set_age' , { args : { age : 22 } } )
// Using diff contract
const transactionC = buildTransaction ( 'update_state' , {
  receiverId : 'my-state-contract.testnet' ,
  args : { allowed : true } ,
} )

// Optional
const callbackUrl = 'https://my-page.com/callback-success'

// [payable]
contractApi . callMultiple ( [ transactionA , transactionB , transactionC ] , callbackUrl ) . then ( ( ) => console . log ( 'Done!' ) )

نظام التخزين المؤقت

هناك نوعان من أنظمة ذاكرة التخزين المؤقت لاستخدامها. هم Memory Cache وذاكرة Storage Cache .

Memory Cache : سيتم مسحها عند تحديث التطبيق ، حيث تعيش بياناته في الذاكرة فقط.
Storage Cache : ستبقى البيانات حتى عندما يتم تحديث علامة التبويب المتصفح. تم استمرار البيانات باستخدام التخزين المحلي.

عند إنشاء ذاكرة التخزين المؤقت ، تحتاج إلى توفير expirationTime (بالثواني). يستخدم هذا لمعرفة متى يجب إرجاع ذاكرة التخزين المؤقت بدلاً من إجراء مكالمة عقد حقيقية. عندما تنتهي صلاحية ذاكرة التخزين المؤقت ، يتم إجراء مكالمة حقيقية للعقد. طريقة كل عقد لها وقت انتهاء الصلاحية.

 // web3Api.ts
import naxios , { StorageCache } from '@wpdas/naxios'

// ...

/**
 * Cached - Greeting Contract API
 */
export const cachedGreetingContractApi = naxiosInstance . contractApi ( {
  contractId : 'dev-1692221685438-15421910364142' ,
  cache : new StorageCache ( { expirationTime : 5 * 60 } ) , // 5 minutes
} )

بعد ذلك ، لاستخدام view المخزن المؤقت ، يمكنك فقط تمرير كائن التكوين الذي يقول إنك تريد استخدام البيانات المخزنة مؤقتًا.

 import { cachedGreetingContractApi } from './web3Api'

// Fetch Greetings [free]
const args : { }
const config : { useCache : true }
cachedGreetingContractApi . view < string > ( 'get_greeting' , args , config ) . then ( ( response ) => console . log ( response ) )

بالقرب من RPC API

يوفر Naxios أيضًا الوصول إلى API القريب من RPC ، بحيث يمكنك الاستعلام عن أي بيانات تريدها. قم بزيارة بالقرب من مستندات API RPC لمعرفة كيفية استخدامه.

 import { rpcApi } from './web3Api'

// Viewing account using Near RPC API
rpcApi
  . query ( {
    request_type : 'view_account' ,
    finality : 'final' ,
    account_id : 'wendersonpires.near' ,
  } )
  . then ( ( data ) => console . log ( 'Account Data:' , data ) ) 

utils

buildTransaction

تعد طريقة buildTransaction مفيدة عندما تحتاج إلى إنشاء هيئة معاملات العقد ، وذلك أساسًا عندما ترغب في إجراء مكالمات متعددة للعقود .

انظر المرجع هنا.

validateNearAddress

يتم استخدام هذا للتحقق مما إذا كان العنوان هو عنوان قريب صالح.

 import { validateNearAddress } from '@wpdas/naxios'

console . log ( validateNearAddress ( 'fake.near' ) ) // true
console . log ( validateNearAddress ( 'fake.nears' ) ) // false
console . log ( validateNearAddress ( 'fake.testnet' ) ) // true
console . log ( validateNearAddress ( 'fake' ) ) // false 

calculateDepositByDataSize

حساب الإيداع المطلوب للبيانات التي يتم تخزينها. (~ 0.00001n لكل بايت) مع القليل من العازلة للمخزن المؤقت

 import { calculateDepositByDataSize } from '@wpdas/naxios'

const myData = { age : 22 , name : 'user name' }
console . log ( calculateDepositByDataSize ( myData ) ) // 0.00087 Near (not yocto NEAR) 

isClient

مدقق بسيط ليقول ما إذا كان هذا قيد التشغيل على الخادم أو العميل.

 import { isClient } from '@wpdas/naxios'

if ( isClient ( ) ) {
  console . log ( 'Hi from client' )
} else {
  console . log ( 'Hi from server' )
} 

المساهمة

لا تتردد في فتح المشكلات أو سحب الطلبات. للتغييرات الرئيسية ، يرجى فتح مشكلة أولاً لمناقشة ما تريد تغييره.