Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cardinal-labs/cardinal-token-manager

Token manager is a set of smart contracts on Solana to facilitate conditionally managed ownership. Using the invalidators and approvers in various ways allows for building rentals, expiring in-game items, subscriptions, permits, tickets, passes and more.
https://github.com/cardinal-labs/cardinal-token-manager

smart-contracts solana

Last synced: 26 days ago
JSON representation

Token manager is a set of smart contracts on Solana to facilitate conditionally managed ownership. Using the invalidators and approvers in various ways allows for building rentals, expiring in-game items, subscriptions, permits, tickets, passes and more.

Awesome Lists containing this project

README 

        
# Token Manager





    An open protocol for issuing managed tokens on Solana.




## Background



The Token Manager program is a wrapper protocol that achieves conditional ownership of Solana NFTs. It allows one to issue an NFT to another party with embedded mechanisms for programmatic management of the token while it sits in their wallet. Among others, things like time-based expiration, usage-based expiration, selective transferability, and non-transferability are possible with the Token Manager. Its modular design uses “plugin” invalidators, approval authorities, and transfer authorities modeled as separate smart contracts to allow for theoretically any custom invalidation, claiming, and transfer logic tied to on-chain data. We currently offer two out-of-the-box invalidator plugins to support basic time and usage-based expiration as well as a basic payment-based claim approver.



## Addresses



Program addresses are the same on devnet, testnet, and mainnet-beta.



- TokenManager: [`mgr99QFMYByTqGPWmNqunV7vBLmWWXdSrHUfV8Jf3JM`](https://explorer.solana.com/address/mgr99QFMYByTqGPWmNqunV7vBLmWWXdSrHUfV8Jf3JM)

- PaidClaimApprover: [`pcaBwhJ1YHp7UDA7HASpQsRUmUNwzgYaLQto2kSj1fR`](https://explorer.solana.com/address/pcaBwhJ1YHp7UDA7HASpQsRUmUNwzgYaLQto2kSj1fR)

- TimeInvalidator: [`tmeEDp1RgoDtZFtx6qod3HkbQmv9LMe36uqKVvsLTDE`](https://explorer.solana.com/address/tmeEDp1RgoDtZFtx6qod3HkbQmv9LMe36uqKVvsLTDE)

- UseInvalidator: [`useZ65tbyvWpdYCLDJaegGK34Lnsi8S3jZdwx8122qp`](https://explorer.solana.com/address/useZ65tbyvWpdYCLDJaegGK34Lnsi8S3jZdwx8122qp)



## Plugins



Token-manager is made to be composable. It allows for plugins for



1. Claim approvers

2. Transfer authorities

3. Invalidators

4. Payment manager



When instantiating a token-manager, the issuer can set a claim approver, transfer authority and invalidators that can control the claim, transfer and invalidate mechanisms. These are all plugins that can be pointed to any program-derived account or user owned account. Out of the box, there are basic plugins to power use and time rentals and subscriptions.



All of these are modeled are separate programs so users can choose to implement custom logic in a separate program for claim, transfer and invalidation. Payment manager handles payment splits for all payments associated with the programs and also has built in support for paying out creator royalties.



# Documentation



## Invalidation Types



The program generalizes the concept of invalidation into a list of invalidators so any of those public keys can trigger the invalidation of the token. The invalidation type field is used to specify "what happens" when invalidation is triggered.



```

#[derive(Clone, Debug, PartialEq, AnchorSerialize, AnchorDeserialize)]

#[repr(u8)]

pub enum InvalidationType {

    /// Upon invalidation it will be returned to the issuer

    Return = 1,

    /// Upon invalidation it will remain marked as invalid

    Invalidate = 2,

    /// Upon invalidation the token manager will be deleted and thus the tokens are released

    Release = 3,

    /// Upon invalidation the token manager will be reset back to issued state

    Reissue = 4,

}

```



## Claim Authority



The concept of claim_authority allows for the issuer to specify specific public key that can approve claiming of the tokens. This can be used in a few contexts.



1. using Keypair.generate() to create a new private key and embed that into a URL as a one-time password. This allows only the recipient of this URL to claim the token. This provides an easy way to distribute tokens via off-chain systems like email.

2. Paid claim approver, a program that is provided out of the box to enforce payment of a specified mint before claiming

3. Checking ownership of a given NFT or token to only allow holders, members in DAOs etc to claim the token.

4. Many, many more!



If not set, this token can be claimed by anyone.



## Transfer Authority



Similar to claim_authority, but a specified publickey that can approve transfer of this token. Because the tokens by default are frozen, normal transfer does not work. Instead a transfer_authority can be used to allow transfers to specified wallet. By default, transfer_authority is set to the token_manager itself, rendering it non-transferable. If unset, the token can be freely transferred. The transfer is modeled by receiving a transfer_receipt that can be used to claim the token. Use cases of transfer_authority can include



1. A system that groups wallets together allowing transfer between "known" wallets all owned by the same user

2. Encoding a transfer schedule in a program on-chain to approve a rotation of the token, similar to a time-share.

3. A paid transfer that allows someone to pay some amount to the current holder in order to get approved for transfer

4. KYC approval required before transfer

5. Transfer between members of a DAO / multi-sig

6. ...



NOTE: Once approved for transfer, the approved party can claim the token from the current holder. This is due to the fact that as a recipient (new holder) you must sign the transaction to "accept" the tokens, because part of this process involved delegating the tokens back to the token-manager. This means that approved parties can effectively "take" the token from the current holder.



## Receipts



The concept of receipts allows the issuer of token(s) into a token-manager to mint a receipt NFT representing this token-manager. Coupled with InvalidationType::Return above, the receipt can be freely traded and represent the public key that the token(s) will be returned to when they are invalidated. This essentially represents the underlying asset during outstanding rentals.



- Receipts are dynamically minted using the image-generator in https://github.com/solana-nft-programs/generator. This allows it to be completely on-chain NFT

- Receipts are freely tradeable and represent the underlying asset for outstanding rentals.

- Receipts will become expired after the rental is over, This means the user must manual follow the links in the description to burn the expired receipt.



## Token Manager ERD



DIAGRAM

View Online: https://dbdiagram.io/d/6226977961d06e6eadbc77be



Documentation is a work in progress. For now, one should read [the tests](https://github.com/solana-nft-programs/token-manager/blob/main/tests/issueUnissue.spec.ts).



We soon plan on releasing a React library to make it easy to integrate ui components with your frontend.



## Example usage



#### All token issue parameters



```js

export type IssueParameters = {

  // Mint of the tokens this token manager will manager

  mint: PublicKey,



  // Amoun of tokens to put into token manager, for NFTs this should use the default of 1

  amount?: BN,



  // Token account where the token is currently held

  issuerTokenAccountId: PublicKey,



  // Whether anyone can claim this or only the specified person with the link

  visibility?: "private" | "public",



  // What kind of token manager this is

  // /// Token a managed rental and will use freeze authority to manage the token

  // Managed = 1,

  // /// Token is unmanaged and can be traded freely until expiration

  // Unmanaged = 2,

  // /// Token is a metaplex edition and so it uses metaplex program to freeze

  // Edition = 3,

  kind?: TokenManagerKind,



  // Optional parameters to specify an up front payment that must be paid before claim

  claimPayment?: {

    // Mint of the tokens required for payment

    paymentMint: PublicKey,

    // Amount of the tokens required for payment

    paymentAmount: number,

  },



  // Optional parameters to expire this token manager based on time

  timeInvalidation?: {

    // Optional payment manager to handle payment splits if multiple parties involved - should be a PDA initialized by payment manager program

    paymentManager?: PublicKey,

    // Optional duration after token is claimed in seconds

    durationSeconds?: number,

    // Optional exact fixed expiration in UTC seconds, not to be used along with durationSeconds

    maxExpiration?: number,

    // Optional extension parameters to extend duration

    extension?: {

      // The amount rate needed for extension

      extensionPaymentAmount: number,

      // The duration added based on amount paid

      extensionDurationSeconds: number,

      // The mint to accept payment for extension

      paymentMint: PublicKey,

      // Whether this rental allows for partial extension or only in increments of extensionDurationSeconds

      disablePartialExtension?: boolean,

    },

  },



  // Optional parameters to expire this token manager based on usage

  useInvalidation?: {

    // Optional payment manager to handle payment splits if multiple parties involved - should be a PDA initialized by payment manager program

    paymentManager?: PublicKey,

    // Optional total usages allocated

    totalUsages?: number,

    // Optional use authority who can use this token

    useAuthority?: PublicKey,

    // Optional extension parameters to extend usages

    extension?: {

      // Number of usages to extend for this payment amount

      extensionUsages: number,

      // The mint to accept payment for extension

      extensionPaymentMint: PublicKey,

      // The amount needed to extend usages

      extensionPaymentAmount: number,

      // Optional limit for how many usages can be extended

      maxUsages?: number,

    },

  },



  // What happens to the token upon invalidation

  // /// Upon invalidation it will be returned to the issuer

  // Return = 1,

  // /// Upon invalidation it will remain marked as invalid

  // Invalidate = 2,

  // /// Upon invalidation the token manager will be deleted and thus the tokens are released

  // Release = 3,

  invalidationType?: InvalidationType,



  // Whether the issuer wants to claim a receipt NFT from their rental - this receipt allows the issuer to trade the underlying asset and future rental income

  receipt?: boolean,

};

```



---



 



### Javascript create fixed price 24h rental



```

npm i @solana-nft-programs/token-manager

```



```javascript

import { Connection } from "@solana/web3.js";



// payment amount 10 for duration of 86400 seconds (24 hours)

const issueTokenParameters = {

  paymentAmount: new BN(10),

  paymentMint: new PublicKey("..."),

  durationSeconds: 86400,

  mint: new PublicKey("..."), // NFT rental mint

  issuerTokenAccountId: new PublicKey("..."),

  visibility: "public", // default public means anyone can claim this rental

  kind: TokenManagerKind.Edition, // used for metaplex master / editions,

  invalidationType: InvalidationType.Return, // indicates this token will be returned when invalidated

};



try {

  const [transaction] = await issueToken(issueTokenParameters);

  transaction.feePayer = wallet.publicKey;

  transaction.recentBlockhash = (

    await connection.getRecentBlockhash("max")

  ).blockhash;

  transaction.sign(wallet, masterEditionMint);

  await sendAndConfirmRawTransaction(connection, transaction.serialize(), {

    commitment: "confirmed",

  });

} catch (exception) {

  // handle exception

}

```



---



 



### Javascript create single use ticket example



```

npm i @solana-nft-programs/token-manager

```



```javascript

import { Connection } from "@solana/web3.js";



// no payment specified, 1 usage and private link means only the holder of the link can claim it

// Releases on use as a memento

const issueTokenParameters = {

  useInvalidation: { totalUsages: 1 }, // 1 use

  mint: new PublicKey("..."), // ticket mint

  issuerTokenAccountId: new PublicKey("..."),

  visibility: "private", // private so you can send this out via email

  kind: TokenManagerKind.Edition, // used for metaplex master / editions,

  invalidationType: InvalidationType.Release, // indicates this token will be released after being used

};



try {

  const [transaction] = await issueToken(issueTokenParameters);

  transaction.feePayer = wallet.publicKey;

  transaction.recentBlockhash = (

    await connection.getRecentBlockhash("max")

  ).blockhash;

  transaction.sign(wallet, masterEditionMint);

  await sendAndConfirmRawTransaction(connection, transaction.serialize(), {

    commitment: "confirmed",

  });

} catch (exception) {

  // handle exception

}

```



---



 



---