calimero-sdk
TypeScript icon, indicating that this package has built-in type declarations

0.0.11 • Public • Published

Calimero SDK

A JavaScript library for building decentralized applications, interacting with Calimero private shards, and managing NEAR wallets.

Calimero Documentation

Getting started

add calimero-sdk dependency to your project.

NPM

$ npm i calimero-sdk

Yarn

$ yarn add calimero-sdk

Usage

CalimeroSdk class

Method Description Paremeters Return
init ( config ) Initialize a new instance of CalimeroSdk. shardId : string
calimeroUrl : string
walletUrl : string
calimeroWebSdkService : string
CalimeroSdk : Object
connect() Connect to a Calimero private shard using NEAR wallet and near-api-js Connection : CalimeroConnection
config : CalimeroConfig

WalletConnection class

Method Description Parameters Return
new WalletConnection (
calimero,
appPrefix
)
Creates a new wallet connection instance which extends near-api-js WalletConnection calimero : CalimeroSdk
appPrefix : String
WalletConnection : WalletConnection
requestSignIn( successUrl ) Connect wallet with a Calimero private shard and sync account  successUrl : SignInOptions Promise : void
 requestSignTransactions (
transactions,
callbackUrl
)
Sign and approve requested transactions with wallet redirect  transactions : string
callbackUrl : string
  Promise : void
addFunctionKey (
contractAddress,
methodNames,
allowance,
xApiKey
)
Create and add function call key with allocated allowance for calling contract methods inside the Calimero private shard  contractAddress : string
methodNames : string[]
allowance : BN
xApiKey : string
 Promise : void

AddFunctionKey paremeters in depth

contractAddress : string - Address of account / contract located in the Calimero private shard. methodName : string[] - String array of change functions available in smart contract. allowance : BN - Amount allowed to spend with function key. BN simbolises big number (yoctoNEAR). xApiKey : string - Calimero Auth token key. Can be created from Calimero Console token page or fetched from local storage under 'AUTH_TOKEN_KEY'.

Examples

Initialise new CalimeroSdk instance

ReactJS example with environment variables.

# calimeroSdk.js

import { CalimeroSdk } from "calimero-auth-sdk";

export default CalimeroSdk.init({
  shardId: process.env.REACT_APP_CALIMERO_SHARD_ID,
  walletUrl: process.env.REACT_APP_WALLET_ENDPOINT_URL,
  calimeroUrl: process.env.REACT_APP_CALIMERO_ENDPOINT_URL,
  calimeroWebSdkService: process.env.REACT_APP_CALIMERO_WEB_SDK_SERVICE_URL,
});

Initialise new WalletConnection instance

ReactJS example with environment variables.

# walletConnection.js

import { WalletConnection } from "calimero-sdk";
import calimeroSdk from "./calimeroSdk";

export const walletConnection = async () => {
  const calimero = await calimeroSdk.connect();
  return new WalletConnection(calimero, "calimero");
};

export default walletConnection;

Create simple login flow with HTML and JavaScript in ReactJS

# index.js

import React, { useEffect, useState } from "react";
import calimeroSdk from "./calimeroSdk";
import walletConnection from "./walletConnection";

export default function Dashboard() {
  const [isSignedIn, setIsSignedIn] = useState(false);
  const [calimero, setCalimero] = useState();
  const [walletConnectionObject, setWalletConnectionObject] = useState();
  const PrivateComponent = () => (
        <div>
        <button onClick={() => walletConnectionObject.signOut() }> Logout </button>
        </div>
  );

  const PublicComponent = () => (
        <div>
        <button onClick={ () => walletConnectionObject.requestSignIn({}) }> Login </button>
        </div>
  );

  useEffect(() => {
    const initialiseWalletConnection = async () => {
      setIsSignedIn(walletConnectionObject.isSignedIn());
    };
    if (walletConnectionObject) {
      initialiseWalletConnection();
    }
  }, [walletConnectionObject]);

  useEffect(() => {
    const initializeCalimero = async () => {
      setCalimero(calimeroSdk);
      const wallet = await walletConnection();
      setWalletConnectionObject(wallet);
    };

    if (!calimero || !walletConnectionObject) {
      initializeCalimero();
    }
  }, [calimero, walletConnectionObject]);

  return isSignedIn ? <PrivateComponent /> : <PublicComponent />;
}

Additional notes

This library is designed to be used in conjunction with Calimero private shards, and requires that you have a NEAR wallet with a valid key pair and access to the Calimero Console. You will also need to have a valid xApiKey to interact with the Calimero private shard.

Please refer to the Calimero documentation and Calimero examples for further information and guidance on using the Calimero SDK.

Calimero Token

Calimero tokens are used to grant the user access to selected Calimero private shard RPC endpoints.

Generating Calimero Token

Calimero tokens are generated based on the user's account ID and the selected Calimero private shard ID. The token data also includes a start and expiry date. The maximum lifetime of a token is 30 days. The token data is sent to the NEAR wallet to be signed as a message, which does not require a blockchain transaction or gas usage. Once the authorization service verifies that the user's account ID has signed the message (containing token data), a Calimero Authorization Token is issued, allowing the user access to Calimero private shard RPC endpoints.

Usage

  • Create a CalimeroTokenData instance with the required data: accountId and shardId. The duration of the token is specified by the from and to fields, which are optional and default to Date.now() and Date.now() + MAX_CALIMERO_TOKEN_DURATION, respectively. Create CalimeroTokenData with the required data: accountId and shardId. Duration of the token:from and to fields are optional and default to Date.now() and Date.now() + MAX_CALIMERO_TOKEN_DURATION, respectively.
  • Serialize the data using calimeroTokenDataInstance.serialize() and use this as the message parameter to be signed by My NEAR Wallet. Store the data received from My NEAR Wallet in a WalletData instance.
  • Create a CalimeroToken with the WalletData and CalimeroTokenData instances: calimeroToken = new CalimeroToken(walletData, calimeroTokenData).
  • Verify the signed message by calling calimeroToken.verify(). This will check if the token is valid with respect to Date.now() and if the signature matches the public key of the user's account ID.
  • Access to the Calimero private shard RPC endpoint should be granted to tokens that return true from calimeroToken.verify().
Method Description Parameters Return
CalimeroToken ( walletData, tokenData ) Creates instance of Calimero Token with required wallet and token data. walletData : walletData
tokenData : CalimeroTokenData
constructor
CalimeroToken.isDurationValid()  Check if token has expired.    boolean
CalimeroToken.isSignatureValid()  Verifies the that user's signature is valid.    boolean
CalimeroToken.verify()  Verify the signed message.    boolean
WalletData (
accountId,
message,
message,
blockId,
publicKey,
signature
)
 Creates an instance of WalletData with data obtained from the NEAR wallet.  accountId : string
message : string
blockId: string
publicKey : string
signature : string
  constructor
WalletData.isSignatureValid() Verifies that the user's signature is valid.    boolean
CalimeroTokenData (
accountId,
shardId,
from,
to
)
Creates an instance of Calimero Token Data. accountId : string
shardId : string
from (optional) : Date
to (optional) : Date
 constructor
CalimeroTokenData.isDurationValid()  Checks if the expiry time is between 0 and 30 days.   boolean

License

This repository is distributed under the terms of both the MIT license and the Apache License (Version 2.0). See LICENSE and LICENSE-APACHE for details.

Readme

Keywords

none

Package Sidebar

Install

npm i calimero-sdk

Weekly Downloads

0

Version

0.0.11

License

(MIT)

Unpacked Size

155 kB

Total Files

31

Last publish

Collaborators

  • xilos
  • francalimero
  • igorcalimero