@phi-hub/lib

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:

1. IMAGE - static image
2. API_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 the cred 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 the cred.

VerifierManager

• Constructor: new VerifierManager(credChainId as CredChainId)

  • credChainId: The ID of the blockchain network where the cred 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 the cred.

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:

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Make your changes and commit them with descriptive messages
4. Push your changes to your forked repository
5. 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 [e-mail].