https://github.com/metaplex-foundation/mpl-token-auth-rules
A program that provides the ability to create and execute rules to restrict common token operations such as transferring and selling.
https://github.com/metaplex-foundation/mpl-token-auth-rules
blockchain metaplex nft rust solana
Last synced: 11 months ago
JSON representation
A program that provides the ability to create and execute rules to restrict common token operations such as transferring and selling.
- Host: GitHub
- URL: https://github.com/metaplex-foundation/mpl-token-auth-rules
- Owner: metaplex-foundation
- License: other
- Created: 2022-11-16T17:37:30.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-12-02T12:08:09.000Z (over 1 year ago)
- Last Synced: 2025-05-08T19:11:56.232Z (about 1 year ago)
- Topics: blockchain, metaplex, nft, rust, solana
- Language: HTML
- Homepage: https://mpl-token-auth-rules.typedoc.metaplex.com
- Size: 9.63 MB
- Stars: 25
- Watchers: 5
- Forks: 28
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Metaplex Token Authorization Rules
A program that provides the ability to create and execute rules to restrict common token operations such as transferring and selling.
Read the official documentation [here](https://developers.metaplex.com/token-auth-rules).
## Overview
Authorization rules are variants of a `Rule` enum that implements a `validate()` function.
There are **Primitive Rules** and **Composed Rules** that are created by combining of one or more primitive rules.
**Primitive Rules** store any accounts or data needed for evaluation, and at runtime will produce a true or false output based on accounts and a well-defined `Payload` that are passed into the `validate()` function.
**Composed Rules** return a true or false based on whether any or all of the primitive rules return true. Composed rules can then be combined into higher-level composed rules that implement more complex boolean logic. Because of the recursive definition of the `Rule` enum, calling `validate()` on a top-level composed rule will start at the top and validate at every level, down to the component primitive rules.
## Getting Started
The packages below can be used to interact with Token Authorization Rules (Token Auth Rules) program.
### TypeScript
```sh
npm install @metaplex-foundation/mpl-token-auth-rules
```
[See typedoc documentation](https://mpl-token-auth-rules-js-docs.vercel.app/).
### Rust
```sh
cargo add mpl-token-auth-rules
```
[See crate documentation](https://docs.rs/mpl-token-auth-rules/latest/mpl_token_auth_rules/).
## Building
From the root directory of the repository:
- Install the required packages:
```sh
pnpm install
```
- Build the program:
```sh
pnpm programs:build
```
This will create the program binary at `/programs/.bin`
## Testing
Token Auth Rules includes three sets of tests: BPF, TypeScript for the JS Client, and Legacy Typescript for the Solita-based JS Client.
### BPF
From the root directory of the repository:
```sh
pnpm programs:test
```
### TypeScript
From the root directory of the repository:
```sh
pnpm validator
```
This will start a local validator using [Amman](https://github.com/metaplex-foundation/amman).
After starting the validator, go to the folder `/clients/js` and run:
```sh
pnpm install
```
This will install the required packages for the tests. Then, run:
```sh
pnpm build && pnpm test
```
### Legacy Typescript
Follow all the same steps as for the TypeScript tests above, including starting the validator in the root directory, but for building and running the tests, navigate to the folder `/clients/js-solita`.
## CLI
The folder `cli` contains a typescript CLI to manage rule set revisions:
```
Usage: auth [options] [command]
CLI for managing RuleSet revisions.
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
create [options] creates a new rule set revision
convert [options] converts a rule set revision from V1 to V2
print [options] prints the latest rule set revision as a JSON object
help [command] display help for command
```
To start the CLI, navigate to the folder `./cli` and run
```
$ yarn install
```
Then, the CLI can be used as
```
$ yarn start
```
The folder `./examples` contain several examples of rule sets. You will need to replace the `owner` pubkey value with the pubkey used to run the CLI.
> Note that you need to first build the JS SDK.
## Examples
### Rust
**Note: Additional Rust examples can be found in the [program/tests](https://github.com/metaplex-foundation/mpl-token-auth-rules/tree/main/program/tests) directory.**
```rust
use mpl_token_auth_rules::{
instruction::{
builders::{CreateOrUpdateBuilder, ValidateBuilder},
CreateOrUpdateArgs, InstructionBuilder, ValidateArgs,
},
payload::{Payload, PayloadType},
state::{CompareOp, Rule, RuleSetV1},
};
use num_derive::ToPrimitive;
use rmp_serde::Serializer;
use serde::Serialize;
use solana_client::rpc_client::RpcClient;
use solana_sdk::{
instruction::AccountMeta, native_token::LAMPORTS_PER_SOL, signature::Signer,
signer::keypair::Keypair, transaction::Transaction,
};
#[repr(C)]
#[derive(ToPrimitive)]
pub enum Operation {
OwnerTransfer,
Delegate,
SaleTransfer,
}
impl ToString for Operation {
fn to_string(&self) -> String {
match self {
Operation::OwnerTransfer => "OwnerTransfer".to_string(),
Operation::Delegate => "Delegate".to_string(),
Operation::SaleTransfer => "SaleTransfer".to_string(),
}
}
}
fn main() {
let url = "https://api.devnet.solana.com".to_string();
let rpc_client = RpcClient::new(url);
let payer = Keypair::new();
let signature = rpc_client
.request_airdrop(&payer.pubkey(), LAMPORTS_PER_SOL)
.unwrap();
loop {
let confirmed = rpc_client.confirm_transaction(&signature).unwrap();
if confirmed {
break;
}
}
// --------------------------------
// Create RuleSet
// --------------------------------
// Find RuleSet PDA.
let (rule_set_addr, _ruleset_bump) = mpl_token_auth_rules::pda::find_rule_set_address(
payer.pubkey(),
"test rule_set".to_string(),
);
// Additional signer.
let adtl_signer = Keypair::new();
// Create some rules.
let adtl_signer_rule = Rule::AdditionalSigner {
account: adtl_signer.pubkey(),
};
let amount_rule = Rule::Amount {
amount: 1,
operator: CompareOp::LtEq,
field: "Amount".to_string(),
};
let overall_rule = Rule::All {
rules: vec![adtl_signer_rule, amount_rule],
};
// Create a RuleSet.
let mut rule_set = RuleSetV1::new("test rule_set".to_string(), payer.pubkey());
rule_set
.add(Operation::OwnerTransfer.to_string(), overall_rule)
.unwrap();
println!("{:#?}", rule_set);
// Serialize the RuleSet using RMP serde.
let mut serialized_rule_set = Vec::new();
rule_set
.serialize(&mut Serializer::new(&mut serialized_rule_set))
.unwrap();
// Create a `create` instruction.
let create_ix = CreateOrUpdateBuilder::new()
.payer(payer.pubkey())
.rule_set_pda(rule_set_addr)
.build(CreateOrUpdateArgs::V1 {
serialized_rule_set,
})
.unwrap()
.instruction();
// Add it to a transaction.
let latest_blockhash = rpc_client.get_latest_blockhash().unwrap();
let create_tx = Transaction::new_signed_with_payer(
&[create_ix],
Some(&payer.pubkey()),
&[&payer],
latest_blockhash,
);
// Send and confirm transaction.
let signature = rpc_client.send_and_confirm_transaction(&create_tx).unwrap();
println!("Create tx signature: {}", signature);
// --------------------------------
// Validate Operation
// --------------------------------
// Create a Keypair to simulate a token mint address.
let mint = Keypair::new().pubkey();
// Store the payload of data to validate against the rule definition.
let payload = Payload::from([("Amount".to_string(), PayloadType::Number(1))]);
// Create a `validate` instruction with the additional signer.
let validate_ix = ValidateBuilder::new()
.rule_set_pda(rule_set_addr)
.mint(mint)
.additional_rule_accounts(vec![AccountMeta::new_readonly(adtl_signer.pubkey(), true)])
.build(ValidateArgs::V1 {
operation: Operation::OwnerTransfer.to_string(),
payload,
update_rule_state: false,
rule_set_revision: None,
})
.unwrap()
.instruction();
// Add it to a transaction.
let latest_blockhash = rpc_client.get_latest_blockhash().unwrap();
let validate_tx = Transaction::new_signed_with_payer(
&[validate_ix],
Some(&payer.pubkey()),
&[&payer, &adtl_signer],
latest_blockhash,
);
// Send and confirm transaction.
let signature = rpc_client
.send_and_confirm_transaction(&validate_tx)
.unwrap();
println!("Validate tx signature: {}", signature);
}
```
### JavaScript
**Note: Additional JS examples can be found in the [/cli/](https://github.com/metaplex-foundation/mpl-token-auth-rules/tree/cli) source along with the example rulesets in [/cli/examples/](https://github.com/metaplex-foundation/mpl-token-auth-rules/tree/cli/examples)**
```js
import { createCreateInstruction, createTokenAuthorizationRules, PREFIX, PROGRAM_ID } from './helpers/mpl-token-auth-rules';
import { Keypair, Connection, PublicKey, Transaction, SystemProgram } from '@solana/web3.js';
import {
findRuleSetPDA,
getRuleSetRevisionFromJson,
serializeRuleSetRevision,
} from '@metaplex-foundation/mpl-token-auth-rules';
export const findRuleSetPDA = async (payer: PublicKey, name: string) => {
return await PublicKey.findProgramAddress(
[
Buffer.from(PREFIX),
payer.toBuffer(),
Buffer.from(name),
],
PROGRAM_ID,
);
}
export const createTokenAuthorizationRules = async (
connection: Connection,
payer: Keypair,
name: string,
data: Uint8Array,
) => {
const ruleSetAddress = await findRuleSetPDA(payer.publicKey, name);
let createIX = createCreateOrUpdateInstruction(
{
payer: payer.publicKey,
ruleSetPda: ruleSetAddress[0],
systemProgram: SystemProgram.programId,
},
{
createOrUpdateArgs: {__kind: "V1", serializedRuleSet: data },
},
PROGRAM_ID,
)
const tx = new Transaction().add(createIX);
const { blockhash } = await connection.getLatestBlockhash();
tx.recentBlockhash = blockhash;
tx.feePayer = payer.publicKey;
const sig = await connection.sendTransaction(tx, [payer]);
await connection.confirmTransaction(sig, "finalized");
return ruleSetAddress[0];
}
const connection = new Connection("", "finalized");
let payer = Keypair.generate()
const revision = getRuleSetRevisionFromJson(JSON.parse(fs.readFileSync("./examples/v2/pubkey-list-match.json")));
// Create the rule set revision
await createTokenAuthorizationRules(connection, payer, name, serializeRuleSetRevision(revision));
```