@campnetwork/origin 1.3.2 → 1.4.0-alpha.1

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
 
@@ -496,8 +496,7 @@ import {
   BulkCostPreview,
   VoteEligibility,
   DisputeProgress,
-  FractionOwnership,
-  FractionalizeEligibility,
+  RoyaltyTokenBalance,
 } from "@campnetwork/origin";
 ```
 
@@ -1205,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
@@ -1378,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);
 }
 ```
 
@@ -1470,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)