Published on

Token Entangler

Authors
  • Name
    Twitter

Token Entangler

What is the Token Entangler?

The Token Entangler is a program which enables you to tie together two NFTs. It was created to help the Exiled Apes community after the Degen Ape Academy's errornous mint. You can find more about the back story on the exiled apes website.

The idea behind the program was that the initially minted NFTs with damaged metadata could be swapped to new NFTs containing proper metadata. It could also be used for derugging projects or more creative use cases.

These swaps are possible back and forth at any given time, even if the NFT that is not in the escrow currently is sold to a different wallet the new wallet will be able to swap it back again.

How it works

For each NFT you want to entangle you need to mint the new NFT already. You then call the create_entangled_pair instruction where you have to define

  • The price of the initial swap (in SOL or SPL token)
  • If the price always has to be paid or just once
  • Which NFTs are entangled (Mint B has to be in your wallet)
  • The Authority of the entangler

After that the holder of the NFT A can call the swap instruction to exchange the NFT with the entangled one. This instruction can be used by the user as often as they want. For this instruction you need to

  • Own one of the two NFTs
  • Know the addresses of both NFTs and/or the address of the entanglement

As Authority you can also call update_entangled_pair to change the price, if the price has to be paid avery time and the authority. Again you need to know

  • the addresses of the NFTs
  • the authority
  • the new price
  • if the price should be paid every time

How to use

Options

There are different possible approaches for you to create your own entangled pairs, swap and update them:

  1. CLI
  2. Self-Hosted UI
  3. Use the instructions described above to build something yourself. It may help you to look into the generated TS in addition to the UI and CLI as basis

Each of those options has their own pros and cons. For example the UI makes the process easier to understand for you, and can be used to build a swap UI for your project, whereas the CLI allows you to test faster on the command line and might be used to automate the entanglement creation for larger projects that cannot be done manually in a reasonable timeframe.

CLI

Install

First you need to install the CLI by

  1. cloning the repository
  2. installing the dependencies by running yarn
  3. Runnig one of the commands further explained below
ts-node token-entangler-cli.ts
Usage: token-entangler-cli [options] [command]

Options:
  -V, --version                  output the version number
  -h, --help                     display help for command

Commands:
  show [options]
  create_entanglement [options]
  swap [options]
  update_entanglement [options]
  help [command]                 display help for command

create_entanglement

As explained above you first have to create the entanglement. Using the CLI you can call the following command:

ts-node token-entangler-cli.ts create_entanglement -k <wallet.json> -e <mainnet-beta|devnet> -p 1 -ma <token mint that you dont have to own> -mb <token mint that you own>

There are additional options which allow you to further configure the swap and are explained below:

Usage: ts-node token-entangler-cli.ts create_entanglement [options]

Options:
  -e, --env <string>                Solana cluster env name (default: "devnet")
  -k, --keypair <path>              Solana wallet location (default: "--keypair not provided")
  -l, --log-level <string>          log level
  -tm, --treasury-mint <string>     Mint address of treasury. If not used, default to SOL.
  -a, --authority <string>          Authority, defaults to keypair
  -p, --price <string>              Price for a swap
  -pet, --pays-every-time <string>  If true, the user must pay the swapping fee each swap
  -ma, --mint-a <string>            Mint a. You do not even need to own this token to create this entanglement.
  -mb, --mint-b <string>            Mint b. This token will be removed from your token account right now.
  -h, --help                        display help for command

swap

After the entanglement creation you can swap the token byeither knowing the entanglement address or the addresses of mint a and mint b

ts-node token-entangler-cli.ts swap -k <wallet.json> -e <mainnet-beta|devnet> -ma <mint a> -mb <mint b>

Usage: token-entangler-cli swap [options]

Options:
  -e, --env <string>              Solana cluster env name (default: "devnet")
  -k, --keypair <path>            Solana wallet location (default: "--keypair not provided")
  -l, --log-level <string>        log level
  -ep, --entangled-pair <string>  Optional. Overrides mint arguments.
  -ma, --mint-a <string>          Mint a.
  -mb, --mint-b <string>          Mint b.
  -h, --help                      display help for command

update_entanglement

Allows you to change the price, if every swap has to be paid and the entangler authority. E.g. like this:

ts-node token-entangler-cli.ts swap -k <wallet.json> -e <mainnet-beta|devnet> -ma <mint a> -mb <mint b> -pet true -na <new authority wallet>

Usage: ts-node token-entangler-cli.ts update_entanglement [options]

Options:
  -e, --env <string>                Solana cluster env name (default: "devnet")
  -k, --keypair <path>              Solana wallet location (default: "--keypair not provided")
  -l, --log-level <string>          log level
  -ep, --entangled-pair <string>    Optional. Overrides mint arguments.
  -na, --new-authority <string>     Authority, defaults to keypair
  -p, --price <string>              Price for a swap
  -pet, --pays-every-time <string>  If true, the user must pay the swapping fee each swap
  -ma, --mint-a <string>            Mint a.
  -mb, --mint-b <string>            Mint b.
  -h, --help                        display help for command

show

Can be used to give you all the details about an entanglement like this: ts-node token-entangler-cli.ts show -k <wallet.json> -e <mainnet-beta|devnet> -ma <mint a> -mb <mint b>

Usage: ts-node token-entangler-cli.ts show [options]

Options:
  -e, --env <string>              Solana cluster env name (default: "devnet")
  -k, --keypair <path>            Solana wallet location (default: "--keypair not provided")
  -l, --log-level <string>        log level
  -ep, --entangled-pair <string>  Optional. Overrides mint arguments.
  -ma, --mint-a <string>          mint a
  -mb, --mint-b <string>          mint b
  -h, --help                      display help for command

UI

The UI is not user friendly, but might give you a better idea how the token entangler works and can also be used as a basis to create your own entangler site for your project.

The UI is not end user friendly and should be modified before being published for your users.

Install

First you need to install the CLI by

  1. cloning the repository
  2. installing the dependencies by running yarn
  3. Rename .env.example to .env and add your authority wallet REACT_APP_WHITELISTED_AUTHORITY=<public key>
  4. To enable all functionalities you have to add an array of all the entangled nfts of your project into src/utils/valid_mints.json
  5. Run yarn start and open the locally hosted website.
  6. If you want to host the UI for your users you need to deploy it e.g. to vercel or cloudflare

Options

The UI allows you to do everything the CLI does and more

  • create new entanglements
  • show entanglement details
  • swap NFTs
  • search entanglements by mint address and authority
  • wizard: searches your wallet for entangled NFTs

**Attention: **Wizard only works if you provide a different RPC which has to allow GPAs. There is currently no parameter for it in the .env but has to be hardcoded in src/contexts/ConnectionContext.tsx around line 105.

:warning: this should probably be removed, or more and additional information added

Further information

Instead of storing array with all pairs use GPA. Don't filter NFTs in wallet for your collection beforehand

const web3 = require('@solana/web3.js');
const { TOKEN_PROGRAM_ID } = require('@solana/spl-token');
(async () => {
  const connection = new web3.Connection(web3.clusterApiUrl('devnet'), 'confirmed');
  const entanglerAuthority = new web3.PublicKey('Tes1zkZkXhgTaMFqVgbgvMsVkRJpq4Y6g54SbDBeKVV');
  const minta = new web3.PublicKey('C8orW3yNKU4SzDwjMWTELQXJjHFUGKMds1q34tv6euRg');
  const mintb = new web3.PublicKey('H4eZ6hkih39Bac8pYfAGRueNdqshqZAqjEgALRZoXbAt');
  const accounts = await connection.getParsedProgramAccounts(
    new web3.PublicKey('qntmGodpGkrM42mN68VCZHXnKqDCT8rdY23wFcXCLPd'), // new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")
    {
      filters: [
        {
          dataSize: 412, // entangler account size
        },
        {
          memcmp: {
            offset: 40, // or 72 for mintb
            bytes: minta.toBase58(), // base58 encoded string
          },
        },
        {
          memcmp: {
            offset: 168,
            bytes: entanglerAuthority.toBase58(), // the authority wallets
          },
        },
      ],
    }
  );
})();
Discuss on Twitter