Cardinal
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.
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-payment-manager |
Handles payment splits and revenue sharing |  |
 |
@cardinal/token-manager |
TypeScript SDK for token-manager |  |
 |
Addresses
Program addresses are the same on devnet, testnet, and mainnet-beta.
- TokenManager:
mgr99QFMYByTqGPWmNqunV7vBLmWWXdSrHUfV8Jf3JM - PaidClaimApprover:
pcaBwhJ1YHp7UDA7HASpQsRUmUNwzgYaLQto2kSj1fR - TimeInvalidator:
tmeEDp1RgoDtZFtx6qod3HkbQmv9LMe36uqKVvsLTDE - UseInvalidator:
useZ65tbyvWpdYCLDJaegGK34Lnsi8S3jZdwx8122qp
Plugins
Cardinal token-manager is made to be composable. It allows for plugins for
- Claim approvers
- Transfer authorities
- Invalidators
- 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.
- 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.
- Paid claim approver, a program that is provided out of the box to enforce payment of a specified mint before claiming
- Checking ownership of a given NFT or token to only allow holders, members in DAOs etc to claim the token.
- 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
- A system that groups wallets together allowing transfer between "known" wallets all owned by the same user
- Encoding a transfer schedule in a program on-chain to approve a rotation of the token, similar to a time-share.
- A paid transfer that allows someone to pay some amount to the current holder in order to get approved for transfer
- KYC approval required before transfer
- Transfer between members of a DAO / multi-sig
- ...
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/cardinal-labs/cardinal-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
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 token issue 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 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 @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 team@cardinal.so 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.