calimero-sdk

Calimero SDK

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

Calimero Documentation

• Learn about Calimero Network
• To quickly get started with integrating Calimero Sdk in a project, check our Calimero examples repository.

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.