@campnetwork/origin 1.3.1 → 1.4.0-alpha.0

package/README.md

@@ -31,7 +31,7 @@ The Origin SDK currently exposes the following modules:
 - **Flexible Storage** - Custom storage adapters for session persistence
 - **Multiple License Types** - Duration-based, single payment, and X402 micropayment licenses
 - **Dispute Resolution** - Raise and resolve IP disputes with CAMP token voting
-- **NFT Fractionalization** - Fractionalize IP NFTs into tradable ERC20 tokens
+- **Royalty Vault System** - Deploy revenue vaults for IP NFTs and claim royalties with Royalty Tokens
 - **App Revenue Sharing** - Built-in app fee support via AppRegistry
 - **Bulk Operations** - Purchase multiple IP NFTs in a single transaction
 
@@ -70,6 +70,7 @@ The Auth class is the entry point for authenticating users with the Origin SDK.
   - `spotify` - The URI to redirect to after the user completes oauth for Spotify.
 - `environment` - `string` - The environment to use. Can be either `DEVELOPMENT` or `PRODUCTION`. Defaults to `DEVELOPMENT`.
 - `baseParentId` - `bigint` - A valid tokenID to be used as the parent of all IPNFTs minted on your platform, making them all derivatives of your base asset.
+- `appId` - `string` - The app ID of your app. This is used to identify your app in the AppRegistry smart contract and to apply any app fees or revenue sharing that you have set up.
 
 You may use the `redirectUri` object to redirect the user to different pages based on the social they are linking.
 You may only define the URIs for the socials you are using, the rest will default to `window.location.href`.
@@ -80,6 +81,7 @@ import { Auth } from "@campnetwork/origin";
 const auth = new Auth({
   clientId: string,
   redirectUri: string | object,
+  appId?: string,
 });
 ```
 
@@ -494,8 +496,7 @@ import {
   BulkCostPreview,
   VoteEligibility,
   DisputeProgress,
-  FractionOwnership,
-  FractionalizeEligibility,
+  RoyaltyTokenBalance,
 } from "@campnetwork/origin";
 ```
 
@@ -542,6 +543,7 @@ It can also take the following optional props:
 - `environment` - `string` - The environment to use. Can be either `DEVELOPMENT` or `PRODUCTION`. Defaults to `DEVELOPMENT`.
 - - the `DEVELOPMENT` environment uses the Camp Testnet while the `PRODUCTION` environment uses the Camp Mainnet.
 - `baseParentId` - `string | bigint` - A valid tokenID to be used as the parent of all IPNFTs minted on your platform, making them all derivatives of your base asset.
+- `appId` - `string` - The app ID of your app. This is used to identify your app in the AppRegistry smart contract and to apply any app fees or revenue sharing that you have set up.
 
 ```jsx
 import { CampProvider } from "@campnetwork/origin/react";
@@ -552,6 +554,7 @@ function App() {
       clientId="your-client-id"
       redirectUri="https://your-website.com"
       environment="DEVELOPMENT"
+      appId="your-app-id"
     >
       <div>Your app</div>
     </CampProvider>
@@ -1201,7 +1204,6 @@ Most methods mirror smart contract functions and require appropriate permissions
 - `bulkMintTolerant(mints)` — Low-level tolerant bulk mint (partial success allowed, returns success/failure counts)
 - `updateTerms(tokenId, license)` — Update license terms
 - `finalizeDelete(tokenId)` — Finalize deletion of an IP NFT
-- `getOrCreateRoyaltyVault(tokenId)` — Get or create Token Bound Account for royalties
 - `getTerms(tokenId)` — Get license terms for a token
 - `ownerOf(tokenId)` — Get owner address
 - `balanceOf(owner)` — Get token count for an owner
@@ -1374,80 +1376,59 @@ if (progress.timeline.canResolveNow) {
 }
 ```
 
-#### Fractionalizer Module Methods
+#### Royalty Vault Module Methods
 
-Methods for fractionalizing IP NFTs into ERC20 tokens:
+Methods for managing royalty vaults and claiming revenue from IP NFTs. The royalty vault system deploys a revenue vault per NFT and issues 100 Royalty Tokens (RT) with real revenue-claiming rights. The NFT stays with the owner.
 
-- `fractionalize(tokenId)` — Fractionalize an NFT into ERC20 tokens
-- `fractionalizeWithApproval(tokenId)` — Fractionalize with automatic approval (recommended)
-- `redeem(tokenId)` — Redeem fractional tokens for the underlying NFT
-- `redeemIfComplete(tokenId)` — Redeem only if holding 100% of tokens (recommended)
-- `getTokenForNFT(tokenId)` — Get the ERC20 token address for a fractionalized NFT
-- `getFractionOwnership(tokenId, owner?)` — Get user's ownership percentage of fractional tokens
-- `canFractionalize(tokenId, owner?)` — Check if user can fractionalize an NFT
+- `getRoyaltyVault(tokenId)` — Get the royalty vault address for a token (returns `null` if no vault exists)
+- `getVaultRevenueTokens(tokenId)` — Get the list of ERC20 revenue token addresses in a vault
+- `claimableRevenue(tokenId, revenueToken, holder?)` — Check how much revenue is claimable by a holder
+- `claimRevenue(tokenId, revenueToken)` — Claim revenue for a single revenue token
+- `claimRevenueBatch(tokenId, revenueTokens)` — Claim revenue for multiple revenue tokens in one transaction
+- `deployVaultForExistingNFT(tokenId)` — Deploy a vault for an NFT minted before the vault system (migration)
+- `getRoyaltyTokenBalance(tokenId, holder?)` — Get Royalty Token balance and ownership percentage
 
-**FractionOwnership Interface:**
+**RoyaltyTokenBalance Interface:**
 
 ```typescript
-interface FractionOwnership {
-  tokenId: bigint;
-  erc20Address: Address; // Zero if not fractionalized
-  isFractionalized: boolean;
-  balance: bigint; // User's fractional token balance
-  totalSupply: bigint; // Total supply of fractional tokens
-  ownershipPercentage: number; // 0-100
-  canRedeem: boolean; // True if owns 100%
-  decimals: number;
-}
-```
-
-**FractionalizeEligibility Interface:**
-
-```typescript
-interface FractionalizeEligibility {
-  canFractionalize: boolean;
-  reason?: string; // Why not (if false)
-  isOwner: boolean;
-  currentOwner: Address;
-  isAlreadyFractionalized: boolean;
-  existingErc20Address?: Address;
-  dataStatus: DataStatus;
-  isApproved: boolean; // Fractionalizer approved to transfer
-  needsApproval: boolean;
+interface RoyaltyTokenBalance {
+  vaultAddress: Address; // The vault contract address
+  balance: bigint; // Holder's Royalty Token balance
+  totalSupply: bigint; // Total supply of Royalty Tokens
+  percentage: number; // 0-100 ownership percentage
+  decimals: number; // Token decimals
 }
 ```
 
 **Example:**
 
 ```typescript
-// Check if you can fractionalize
-const eligibility = await auth.origin.canFractionalize(1n);
+// Check if a vault exists for a token
+const vault = await auth.origin.getRoyaltyVault(1n);
 
-if (eligibility.canFractionalize) {
-  // Fractionalize with automatic approval
-  await auth.origin.fractionalizeWithApproval(1n);
-} else {
-  console.log(`Cannot fractionalize: ${eligibility.reason}`);
-  // Possible reasons:
-  // - "You don't own this NFT"
-  // - "This NFT is already fractionalized"
-  // - "This NFT has been deleted"
-  // - "This NFT is disputed"
+if (!vault) {
+  // Deploy a vault for an existing NFT (migration)
+  await auth.origin.deployVaultForExistingNFT(1n);
 }
 
-// Check your ownership of fractional tokens
-const ownership = await auth.origin.getFractionOwnership(1n);
+// Check your Royalty Token balance
+const rtBalance = await auth.origin.getRoyaltyTokenBalance(1n);
+console.log(`You own ${rtBalance.percentage}% of royalty rights`);
+console.log(`Balance: ${rtBalance.balance} / ${rtBalance.totalSupply}`);
 
-if (!ownership.isFractionalized) {
-  console.log("This NFT has not been fractionalized");
-} else {
-  console.log(`You own ${ownership.ownershipPercentage}% of this NFT`);
-  console.log(`Balance: ${ownership.balance} / ${ownership.totalSupply}`);
+// Check which revenue tokens have accumulated
+const revenueTokens = await auth.origin.getVaultRevenueTokens(1n);
+console.log(`Revenue tokens: ${revenueTokens.length}`);
 
-  if (ownership.canRedeem) {
-    console.log("You can redeem the original NFT!");
-    await auth.origin.redeemIfComplete(1n);
-  }
+// Check claimable revenue for each token
+for (const token of revenueTokens) {
+  const claimable = await auth.origin.claimableRevenue(1n, token);
+  console.log(`Claimable from ${token}: ${claimable}`);
+}
+
+// Claim all revenue in one transaction
+if (revenueTokens.length > 0) {
+  await auth.origin.claimRevenueBatch(1n, revenueTokens);
 }
 ```
 
@@ -1466,10 +1447,12 @@ console.log(`Revenue Share: ${appInfo.revenueShareBps / 100}%`);
 console.log(`Active: ${appInfo.isActive}`);
 ```
 
-#### Royalty & Data Methods
+#### TBA Royalty & Data Methods
+
+These methods work with the Token Bound Account (TBA) that exists for all NFTs. For the new Royalty Vault system, see the [Royalty Vault Module Methods](#royalty-vault-module-methods) section above.
 
 - `getTokenBoundAccount(tokenId)` — Get the Token Bound Account address for a token
-- `getRoyalties(tokenId, token?)` — Get royalty balance for a token
+- `getRoyalties(tokenId, token?)` — Get TBA royalty balance for a token
 - `claimRoyalties(tokenId, recipient?, token?)` — Claim royalties from a token's TBA
 - `getData(tokenId)` — Fetch the underlying IP data (requires access)