@phi-hub/lib
v1.1.0
Published
A lib to interact with Phi protocol
Downloads
164
Readme
Phi Lib
Phi Lib is a powerful, developer-friendly toolkit designed for seamless interaction with the Phi Protocol. It allows developers to create and manage credentials (Creds), issue artworks as non-fungible tokens (NFTs) tied to these credentials, and verify minting eligibility across multiple blockchain networks.
Features
- Create Merkle-based Creds from CSV or JSON files
- Create Signature-based Creds with customizable verification endpoints
- Buy/Sell shares for Cred
- Issue NFT Arts based on Creds
- Easy-to-use command-line interface (CLI)
- TypeScript support for improved code quality and developer experience
SDK
Overview
Phi SDK provides tools and libraries for programmatic interaction with the Phi Protocol. Through an intuitive and consistent API, developers can create credentials, manage NFTs, and interact with multiple blockchain networks.
Installation
To install the Phi SDK, run the following command:
bun add @phi-hub/lib
Usage
Importing the SDK
First, import the necessary modules from the Phi SDK:
import { CredManager, ArtManager, VerifierManager } from "@phi-hub/lib";
Creating a Merkle-based Cred
Use the CredManager
to create a Merkle-based credential:
const credManager = new CredManager(privateKey, chainId);
const input = {
creator: "0xYourAddress",
requirement: "YourRequirement",
description: "YourDescription",
imageData: "Base64EncodedImageData",
networks: [1, 4],
tags: ["tag1", "tag2"],
relatedLinks: ["https://example.com"],
signalRoyalty: 0.01,
unSignalRoyalty: 0.02,
verificationSource: "https://verificationsource.com",
addressList: "YourAddressListCSVData",
};
const credId = await credManager.createMerkleCred(input, chainId);
console.log(`Credential created successfully with ID: \${credId}`);
Signaling and Unsignaling Cred
Use the CredManager
to signal or unsignal a credential:
await credManager.signalCred(credId, amount);
await credManager.unsignalCred(credId, amount);
Uploading an art for a cred
Arts are of two types:
IMAGE
- static imageAPI_ENDPOINT
- dynamic image which can be fetched from an external source
Use the ArtManager
to create and upload art. The inputs will vary according to the artType
const artManager = new ArtManager(privateKey, artChainId, credChainId);
let inputs = {
artType: "IMAGE", // IMAGE | API_ENDPOINT
title: "Awesome Title",
network: 84532,
artist: "0xYourAddress",
receiver: "0xReceiverAddress",
description: "YourDescription",
externalURL: "https://example.com",
start: 1724681692,
end: 4880355292,
maxSupply: 100,
price: parseEther(new Big(1).toString()).toString(),
soulbound: false,
tags: ["tag1", "tag2"],
};
if(inputs.artType === 'IMAGE') {
inputs.imageData = "Base64EncodedImageData"
} else if(inputs.artType === 'API_ENDPOINT') {
inputs.endpoint = "https://api.example.com"
inputs.previewInput = {
address: "0xAnyAddress",
data: "AnyStringifiedData"
}
}
const artId = await artManager.createArt(inputs, credId);
console.log(`art created successfully with ID: \${artId}`);
Creating a verifier for a cred
Use the VerifierManager
to create a verifier.
const verifierManager = new VerifierManager(credChainId as CredChainId);
let inputs: AddVerifierInput = {
address,
endpoint,
verificationSource,
};
const arweaveId = await verifierManager.createVerifier(inputs, credId)
console.log(`verifier added successfully: \${arweaveId}`);
API Reference
CredManager
Constructor:
new CredManager(privateKey: string, chainId: CredentialChainId)
privateKey
: The private key of the user's account.chainId
: The ID of the blockchain network.
Methods:
createMerkleCred(input: MerkleCredCreateInput, chainId: CredentialChainId): Promise<string>
- Creates a Merkle-based credential.
input
: An object containing credential details.chainId
: The ID of the blockchain network.
signalCred(credId: string, amount: number): Promise<void>
- Signals a credential.
credId
: The ID of the credential.amount
: The amount to signal.
unsignalCred(credId: string, amount: number): Promise<void>
- Unsignals a credential.
credId
: The ID of the credential.amount
: The amount to unsignal.
ArtManager
Constructor:
new ArtManager(privateKey: Hex, artChainId: ArtChainId, credChainId: CredChainId)
privateKey
: The private key of the user's account.artChainId
: The ID of the blockchain network to upload the art to.credChainId
: The ID of the blockchain network where thecred
is.
Methods:
createArt(input: ArtCreateInput, credId: string | number): Promise<string | undefined>
- Creates and upload art and its metadata
input
: An object containing art details.credId
: The ID of thecred
.
VerifierManager
Constructor:
new VerifierManager(credChainId as CredChainId)
credChainId
: The ID of the blockchain network where thecred
is.
Methods:
createVerifier(input: AddVerifierInput, credId: string | number): Promise<string | undefined>
- Creates verifier for a cred
input
: An object containing verification details.credId
: The ID of thecred
.
config
- Methods:
setChain(chain: string): void
- Sets the default blockchain network.
setPrivateKey(privateKey: string): void
- Sets the private key for transactions.
Type Definitions
MerkleCredCreateInput
export interface MerkleCredCreateInput {
creator: string;
requirement: string;
description?: string;
imageData: string;
networks: number[];
tags?: string[];
relatedLinks?: string[];
signalRoyalty: number;
unSignalRoyalty: number;
verificationSource: string;
addressList: string;
}
ArtCreateInput
export interface BaseArtCreateInput {
artType: ArtType;
title: string;
network: ArtChainId;
artist: `0x${string}`;
receiver?: `0x${string}`;
description?: string;
externalURL?: string;
start?: number;
end?: number;
maxSupply?: number;
price?: string;
soulbound?: boolean;
tags?: string[];
}
export type ArtCreateInput =
| (BaseArtCreateInput & {
artType: "API_ENDPOINT";
endpoint: string;
previewInput: { address: string; data: string };
})
| (BaseArtCreateInput & { artType: "IMAGE"; imageData: string });
AddVerifierInput
export type AddVerifierInput = {
address: Address;
endpoint: string;
verificationSource: string;
}
CLI
Phi CLI is a command-line tool for interacting with the Phi Protocol. It provides an easy way to create credentials, manage NFTs, and configure the Phi SDK from the terminal.
Installation
To install the Phi CLI, run the following command:
bun add @phi-hub/lib
Usage For CLI
Link the Phi CLI to your environment:
bun link
bun link @phi-hub/lib
Creating a Merkle-based Cred
To create a Merkle-based Cred, use the phi cred create-merkle
command:
phi create-merkle [options]
Option | Required | Default |
|--------|----------|---------|
| --creator
| Yes | - |
| --signal-royalty
| Yes | - |
| --unsignal-royalty
| Yes | - |
| --data-file
| Yes | - |
| --chain
| Yes | - |
Note: For all options, if not provided via command line, the CLI will prompt the user for input interactively.
Example Usage
phi create-merkle \
--creator 0x1234567890abcdef1234567890abcdef12345678 \
--signal-royalty 0.1 \
--unsignal-royalty 0.05 \
--data-file ./address_list.csv \
--chain 84532
Creating Art for a Cred
To create art for a cred, use the phi create-art
command:
phi create-art [options]
| Option | Required | Default |
|--------|----------|---------|
| --cred-chain
| Yes | - |
| --cred
| Yes | - |
| --art-chain
| Yes | - |
| --type
| Yes | - |
| --title
| Yes | - |
| --artist
| Yes | - |
| --receiver
| No | Same as artist |
| --description
| No | "" (empty string) |
| --external-url
| No | "" (empty string) |
| --start
| No | Current timestamp |
| --end
| No | 100 years from now |
| --supply
| No | Unlimited (maxUint256) |
| --price
| No | 0 |
| --soulbound
| No | false |
| --tags
| No | [] (empty array) |
Note: For required options, if not provided via command line, the CLI will prompt the user for input interactively.
Example usage:
phi create-art \
--cred-chain 84532 \
--cred 0x1234567890abcdef1234567890abcdef12345678 \
--art-chain 84532 \
--type IMAGE \
--title "My Awesome NFT" \
--artist 0x9876543210fedcba9876543210fedcba98765432 \
--receiver 0xabcdef1234567890abcdef1234567890abcdef12 \
--description "A beautiful digital artwork created for Phi Protocol" \
--external-url https://example.com/my-awesome-nft \
--start 1625097600 \
--end 1640995200 \
--supply 100 \
--price 0.1 \
--soulbound false \
--tags art,nft,digital,phi
Create Verifier Command
To create a verifier for a cred, use the phi create-verifier
command:
phi create-verifier [options]
| Option | Required | Default |
|-----------|----------|---------|
| --cred-chain
| Yes | - |
| --cred
| Yes | - |
| --address
| Yes | - |
| --endpoint
| Yes | - |
| --source
| Yes | - |
Note: For all options, if not provided via command line, the CLI will prompt the user for input interactively.
Example Usage
phi create-verifier \
--cred-chain 84532 \
--cred 1 \
--address 0x1234567890abcdef1234567890abcdef12345678 \
--endpoint https://api.example.com/verify \
--source https://github.com/PHI-LABS-INC/verifier-template
Tutorial
# at root level
bun install
bun link
bun link phi-cli
- deposit to irys
https://provenance-toolkit.irys.xyz/fund-withdraw or https://docs.irys.xyz/developer-docs/cli/commands/fund
- update your env key
phi config set-private-key
- create Cred
phi create-merkle \
--creator 0x1234567890abcdef1234567890abcdef12345678 \
--signal-royalty 0.1 \
--unsignal-royalty 0.05 \
--data-file ./address_list.csv \
--chain 84532
For more information on the available commands and options, please refer to the CLI documentation.
CLI Configuration
To configure the Phi CLI, use the following commands:
- Set the default chain:
phi config set-chain <chain>
- Get the current default chain:
phi config get-chain
- Set the private key:
phi config set-private-key <privateKey>
Contributing
We welcome contributions to the Phi SDK! If you'd like to contribute, please follow these steps:
- Fork the repository
- Create a new branch for your feature or bug fix
- Make your changes and commit them with descriptive messages
- Push your changes to your forked repository
- Submit a pull request to the main repository
For more information on contributing, please see our contribution guidelines.
License
The Phi Lib is released under the MIT License.
Support
If you have any questions, issues, or suggestions regarding the Phi SDK, please open an issue on GitHub or contact our support team at [email protected].