Wallet partners

Wallet partners are organizations that provide wallet services and play a crucial role in the Calimero ecosystem. Integration with the Calimero API involves implementing essential features like consent prompts for user authentication and ensuring compatibility with the Calimero Network.

Wallet Integration

Here's a detailed breakdown of how you can integrate your wallet with the Calimero API:

Syncing Account from NEAR to Calimero

When a user selects the account they want to sync with the Calimero shard within their wallet, you need to make a POST request to the following endpoint:

https://app.calimero.network/api/public/sync2

Include the following request data in the request body:

• accountId: (string) The account to sync
• shardId: (string) The Calimero shard ID where the account should be synced

In the request header, set x-signature to be the JSON-serialized object encoded in base64: {challenge, publicKey, signature}.

The challenge can be obtained from this URL:

https://api.calimero.network/api/v1/shards/{shard_id}/wallet/api/v1/challenge

The signature is generated by signing the challenge with the private key associated with the account to be synced. You can follow the example below to generate the signature:

async function signatureFor(signer, accountId, challenge) {
    const signed = await signer.signMessage(
        Buffer.from(challenge),
        accountId,
        CONFIG.NETWORK_ID
    );
    const signature = Buffer.from(signed.signature).toString('base64');
    const publicKey = signed.publicKey.toString();
    return { challenge, signature, publicKey, accountId };
}

After the response is OK, there are two scenarios:

1. For a simple sync initiated by the user, the process is complete, and the account now exists on the Calimero chain.

2. If the sync was initiated from a Dapp, after the sync is successful, a function access key needs to be added on the Calimero side. This can be achieved through the near-api-js account object by calling the addKey method. The connection object to the Calimero shard should have 'x-signature' set under the request header, with the value being the signed challenge. Account.addKey should be provided with the publicKey associated with the Dapp, contractId, and method_names for which the function access key will be added. The parameters are passed to the wallet via URL.

Example:

// Init keystore, e.g.:
const keyStore = new keyStores.UnencryptedFileSystemKeyStore('/Users/username/.near-credentials');

// Create the signature and set in 'x-signature' header
let inMemSigner = new NearAPI.InMemorySigner(keyStore);
let sig = await signatureFor(inMemSigner, accountId, challenge);
let signatureHeader = Buffer.from(JSON.stringify(sig)).toString('base64');

// The connection to Calimero shard
const calimeroConnection = await NearAPI.connect({
    keyStore,
    networkId: calimero-network-id,
    nodeUrl: `https://api.dev.calimero.network/api/v1/shards/${calimero-network-id}/neard-rpc/`,
    headers: {
        'x-signature': signatureHeader
    },
});
// Now, use the calimeroConnection to send transactions and/or view blockchain state

Sending a Signed Transaction to Calimero

Here's a concise snippet illustrating how to send a signed transaction. The connection object to the Calimero shard should have 'x-signature' under the request header set to the signed challenge, as described in the previous section. Once the transaction is broadcasted to the Calimero RPC endpoint, if the signed message is valid and the account already exists on the Calimero chain, the transaction will be executed.

Performing View Calls to Contracts on Calimero

One key difference between Calimero and NEAR is that Calimero disallows anonymous view calls to read contract data. Instead, when viewing contract data, you need to provide the signature over a received challenge from the endpoint:

https://api.calimero.network/api/v1/shards/{shard_id}/wallet/api/v1/challenge

Include this signature under x-signature in the request header for secure access to contract data.

That's it! If you have any further questions or need assistance, please don't hesitate to reach out.