Cardinal

Background

Cardinal is a composable protocol for issuing conditional NFTs that are managed by the protocol. Using the invalidators and approvers in various ways allows for building rentals, expiring in-game items, subscriptions, permits, tickets, passes and more.

Carinal protocol provides a token-manager implementation as well as basic plugins for paid claim, permissioned transfer, and time invalidation. These plugins can be extended to support various use cases or similar ones built with entirely new logic for token handling the token invalidation.

Packages

| Package | Description | Version | Docs | | :----------------------------- | :-------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | | cardinal-token-manager | Manages conditionally owned tokens | | | | cardinal-paid-claim-approver | Approves users to claim tokens from a token-manager | | | | cardinal-time-invalidator | Invalidator for time-based token-managers | | | | cardinal-use-invalidator | Invalidator for use-based token-managers | | | | @cardinal/token-manager | TypeScript SDK for token-manager | | |

Addresses

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

• TokenManager: Ggot33rp5d9MbRP6Jd2UZ2QrEpvfmUpX58DNw3ZBGeqK
• PaidClaimApprover: yedA4fYUEv4SjFQCpZd71qH3eWid7FjYMZum4SuZEhT
• TimeInvalidator: 6pBkL3sgvaaPj226cY1huGCu9ytcYneQ2dZB49HY5CpG
• UseInvalidator: useZ65tbyvWpdYCLDJaegGK34Lnsi8S3jZdwx8122qp

Plugins

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

1. Claim approvers
2. Transfer authorities
3. Invalidators

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.

Documentation

Token Manager ERD

Documentation is a work in progress. For now, one should read the tests.

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

Example usage

All rental parameters

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 exact fixed expiration in UTC seconds, not to be used along with durationSeconds
    expiration?: number,
    // Optional duration after token is claimed in seconds
    durationSeconds?: 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,
      // The max expiration limit on how long a rental can be extended
      maxExpiration?: number,
      // 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 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 @cardinal/token-manager

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 @cardinal/token-manager

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
}

Image generator

Cardinal also provides an image generator API. You provide your NFT metadata and image, or a URL to where its hosted, and use the url https://api.cardinal.so/metadata/{mintId} when minting the token and the API will dynamically update the image and metadata based on usages or expiration associated with it so that its always up to date forever and wherever it is viewed.

Reach out to [email protected] if you are interested in using this service.

License

Cardinal Protocol is licensed under the GNU Affero General Public License v3.0.

In short, this means that any changes to this code must be made open source and available under the AGPL-v3.0 license, even if only used privately.