npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

shield-bridge-sdk

v0.0.1-beta.3

Published

Shield Bridge SDK

Downloads

18

Readme

Shield Bridge SDK

Shield Bridge SDK is a Typescript library that provides a simple interface to interact with the Shield Bridge smart contract on Tezos. It allows users to shield their tokens and tez to the deployed sapling shielded pools.

The Shield Bridge smart contract is a decentralized bridge that allows users to shield their FA1.2 tokens, FA2 tokens, and tez to the deployed sapling shielded pools. The shielded pools are used to mint shielded tokens that represent the underlying assets. The shielded tokens can be transferred to other users and can be redeemed for the underlying assets all while being obfuscated by the sapling protocol.

The advantage to using Shield Bridge is that all the underlying sapling shielded pools are deployed to a single smart contract which encourages network effects and reduces the need for users to deploy their own sapling shielded pools. This also means that multiple sapling transactions can be sent in a single operation for multiple tokens and tez which greatly reduces the overhead of interacting with multiple sapling shielded pool contracts.

Table of Contents

Getting Started

This section will guide you through the basic steps to install and use the Shield Bridge SDK.

Prerequisites

  • Node.js >= v18 and npm installed.

Installation

Install the package via npm:

npm install shield-bridge-sdk

Basic Usage

Initialize the Shield Bridge SDK against mainnet with the following code

import { TezosToolkit } from '@taquito/taquito';
import { InMemorySigner } from '@taquito/signer';
import ShieldBridge from 'shield-bridge-sdk';

const tezos = new TezosToolkit('https://mainnet.api.tez.ie');
const signerProvider = await InMemorySigner.fromSecretKey('edsk...');
tezos.setSignerProvider(signerProvider);

const shieldBridge = new ShieldBridge({
  client: tezos,
  saplingSecret: 'sask...',
});

Shield tokens to the sapling shielded pools

const op = await shieldBridge.shield([
  // Shield 10 tokens from FA1.2 contract KT1P8RdJ5MfHMK5phKJ5JsfNfask5v2b2NQS
  {
    amount: 10,
    contract: 'KT1P8RdJ5MfHMK5phKJ5JsfNfask5v2b2NQS',
  },
  // Shield 10 tokens from FA2 contract KT1LkNWZgVYh3zdaRkBb9aNgLEFCjVJwEKu2, tokenId 0
  {
    amount: 10,
    contract: 'KT1LkNWZgVYh3zdaRkBb9aNgLEFCjVJwEKu2',
    tokenId: 0,
  },
  // Shield 10 tez
  {
    amount: 10,
  },
]);

Unshield tokens from the sapling shielded pools

const op = await shieldBridge.unshield([
  // Unshield 10 tokens from FA1.2 contract KT1P8RdJ5MfHMK5phKJ5JsfNfask5v2b2NQS
  {
    amount: 10,
    contract: 'KT1P8RdJ5MfHMK5phKJ5JsfNfask5v2b2NQS',
  },
  // Unshield 10 tokens from FA2 contract KT1LkNWZgVYh3zdaRkBb9aNgLEFCjVJwEKu2, tokenId 0
  {
    amount: 10,
    contract: 'KT1LkNWZgVYh3zdaRkBb9aNgLEFCjVJwEKu2',
    tokenId: 0,
  },
  // Unshield 10 tez
  {
    amount: 10,
  },
]);

Transfer shielded tokens within the sapling shielded pools

const op = await shieldBridge.transfer([
  // Transfer 10 tokens from FA1.2 contract KT1P8RdJ5MfHMK5phKJ5JsfNfask5v2b2NQS
  {
    transfers: [
      {
        amount: 10,
        to: 'zet13iuD1bKNE5MAEXN4JfVEnSKHyoCAwUhGzXFANZxmeof2DJXGX4F23jEW5zgf7LpdK',
        memo: 'multitxn',
      },
    ],
    contract: 'KT1P8RdJ5MfHMK5phKJ5JsfNfask5v2b2NQS',
  },
  // Transfer 10 tokens from FA2 contract KT1LkNWZgVYh3zdaRkBb9aNgLEFCjVJwEKu2, tokenId 0
  {
    transfers: [
      {
        amount: 10,
        to: 'zet13iuD1bKNE5MAEXN4JfVEnSKHyoCAwUhGzXFANZxmeof2DJXGX4F23jEW5zgf7LpdK',
        memo: 'multitxn',
      },
    ],
    contract: 'KT1LkNWZgVYh3zdaRkBb9aNgLEFCjVJwEKu2',
    tokenId: 0,
  },
  // Transfer 10 tez
  {
    transfers: [
      {
        amount,
        to: 'zet13iuD1bKNE5MAEXN4JfVEnSKHyoCAwUhGzXFANZxmeof2DJXGX4F23jEW5zgf7LpdK',
        memo: 'multitxn',
      },
    ],
  },
]);

Get the balance of all shielded tokens

const balances = await shieldBridge.getAllShieldedBalances();

Get the transaction history for a shielded token / tez

// Get the transaction history for FA1.2 contract KT1P8RdJ5MfHMK5phKJ5JsfNfask5v2b2NQS
const transactions = await shieldBridge.getShieldedTransactions(
  'KT1P8RdJ5MfHMK5phKJ5JsfNfask5v2b2NQS',
);

// Get the transaction history for FA2 contract KT1LkNWZgVYh3zdaRkBb9aNgLEFCjVJwEKu2, tokenId 0
const transactions = await shieldBridge.getShieldedTransactions(
  'KT1LkNWZgVYh3zdaRkBb9aNgLEFCjVJwEKu2',
  0,
);

// Get the transaction history for tez
const transactions = await shieldBridge.getShieldedTransactions();

Advanced Usage

Initialize the Shield Bridge SDK against ghostnet

import { TezosToolkit } from '@taquito/taquito';
import { InMemorySigner } from '@taquito/signer';
import ShieldBridge, { saplingStateMapContract } from 'shield-bridge-sdk';

const tezos = new TezosToolkit('https://ghostnet.api.tez.ie');
const signerProvider = await InMemorySigner.fromSecretKey('edsk...');
tezos.setSignerProvider(signerProvider);

const shieldBridge = new ShieldBridge({
  client: tezos,
  saplingSecret: 'sask...',
  tzktApi: 'ghostnet',
  saplingStateMapContract: saplingStateMapContract.ghostnet,
});

Initialize the Shield Bridge SDK with an alternate configuration

const shieldBridge = new ShieldBridge({
  client: tezos,
  saplingMnemonic: 'grunt inmate sword ...', // Use a mnemonic instead of a secret key
  saplingStateMapContract: 'KT1...', // Use a custom sapling state map contract
  tzktApi: 'ghostnet', // Use the ghostnet tzkt API for token metadata information
  gasLimitBuffer: 3000, // Increase the gas limit buffer
  storageLimitBuffer: 600, // Increase the storage limit buffer
  minConfirmations: 2, // Wait for 2 confirmations before returning from the operation
  useBaseUnits: true, // Use base units for token amounts. Using 1 mutez instead of 0.000001 tez
});

Modify the gas and storage limit buffers

The Shield Bridge SDK uses a gas and storage limit buffer to ensure that the operation has enough gas and storage to complete successfully. The default gas limit buffer is 2000 and the default storage limit buffer is 500. You can modify these values by passing them to the Shield Bridge constructor. In most cases, the default values should be sufficient. However, the operations may require a higher gas or storage limit due to other simultaneous calls to the Shield Bridge contract. You can also lower the gas and storage limit buffers, but you may experience more failed operations due to insufficient gas or storage limit errors.

const shieldBridge = new ShieldBridge({
  client: tezos,
  saplingSecret: 'sask...',
  gasLimitBuffer: 1000,
  storageLimitBuffer: 100,
});

FAQs

How do I create a saplingSecret?

A sapling secret key can be generated using the Octez client and issuing the command:

./octez-client sapling gen key test-sapling-key --unencrypted

This will generate a mnemonic and a secret key. The secret key can be found in ~/.tezos-client/sapling_keys. Otherwise, you can use any bip39 mnemonic generator to generate a 24 word mnemonic.

const mnemonic = bip39.generateMnemonic(256);

How do I add a new token and sapling pool to the Shield Bridge state map contract?

The Shield Bridge SDK uses a state map contract to store the sapling pool addresses and token metadata. The state map contract is used to look up the sapling pool for a given token contract. If you want to add a new token and sapling pool to the state map contract, you can do so by calling the init_token_sapling_pool method in the Shield Bridge contract, or by calling the initTokenSaplingPool method in the Shield Bridge SDK.

const op = await shieldBridge.initTokenSaplingPool(
  'KT1LkNWZgVYh3zdaRkBb9aNgLEFCjVJwEKu2',
  0,
);

This will add the token contract KT1LkNWZgVYh3zdaRkBb9aNgLEFCjVJwEKu2 with token id 0 to the state map contract. The contract will check if the token contract is a FA1.2 or FA2 contract by testing for the existence of the required entrypoints and will add the sapling pool address to the state map contract if the contract is valid.