PrivateNFT

Class: PrivateNFT

Defined in: @sip-protocol/sdk/dist/index-BYZbDjal.d.ts:8666

Private NFT Ownership Manager

Provides methods to create private NFT ownership records, generate ownership proofs, and verify proofs without revealing owner identity.

Examples

import { PrivateNFT, generateStealthMetaAddress } from '@sip-protocol/sdk'

const nft = new PrivateNFT()

// Recipient generates stealth meta-address
const { metaAddress } = generateStealthMetaAddress('ethereum', 'NFT Wallet')
const encoded = encodeStealthMetaAddress(metaAddress)

// Create private ownership record
const ownership = nft.createPrivateOwnership({
  nftContract: '0x1234...',
  tokenId: '42',
  ownerMetaAddress: encoded,
  chain: 'ethereum',
})

// Later: prove ownership with challenge-response
const challenge = 'prove-ownership-2024-12-03'
const proof = nft.proveOwnership({
  ownership,
  challenge,
  stealthPrivateKey: derivedPrivateKey,
})

// Verifier checks proof
const result = nft.verifyOwnership(proof)
console.log(result.valid) // true

// Gate content access by NFT ownership without revealing identity
const nft = new PrivateNFT()

// User proves they own required NFT
const proof = nft.proveOwnership({
  ownership: userNFTRecord,
  challenge: `access-${contentId}-${Date.now()}`,
  stealthPrivateKey: userStealthKey,
})

// Server verifies without learning user identity
const verification = nft.verifyOwnership(proof)
if (verification.valid && verification.nftContract === REQUIRED_NFT) {
  // Grant access
}

Constructors

Constructor

new PrivateNFT(): PrivateNFT

Returns

PrivateNFT

Methods

createPrivateOwnership()

createPrivateOwnership(params): PrivateNFTOwnership

Defined in: @sip-protocol/sdk/dist/index-BYZbDjal.d.ts:8690

Create a private ownership record for an NFT

Generates a stealth address for the owner to prevent linking ownership records across different NFTs or time periods.

Parameters

params

CreatePrivateOwnershipParams

Creation parameters

Returns

PrivateNFTOwnership

Private ownership record

Throws

If parameters are invalid

Example

const nft = new PrivateNFT()

const ownership = nft.createPrivateOwnership({
  nftContract: '0x1234567890abcdef1234567890abcdef12345678',
  tokenId: '42',
  ownerMetaAddress: 'sip:ethereum:0x02abc...123:0x03def...456',
  chain: 'ethereum',
})

proveOwnership()

proveOwnership(params): OwnershipProof

Defined in: @sip-protocol/sdk/dist/index-BYZbDjal.d.ts:8719

Generate a proof of NFT ownership

Creates a zero-knowledge proof that the caller owns the NFT without revealing their stealth address or private key. Uses challenge-response to prevent replay attacks.

Parameters

params

ProveOwnershipParams

Proof generation parameters

Returns

OwnershipProof

Ownership proof

Throws

If parameters are invalid

Throws

If proof generation fails

Example

const nft = new PrivateNFT()

// Generate proof for challenge
const proof = nft.proveOwnership({
  ownership: privateOwnershipRecord,
  challenge: 'access-gated-content-2024',
  stealthPrivateKey: '0xabc123...',
})

// Send proof to verifier (doesn't reveal identity)
await submitProof(proof)

verifyOwnership()

verifyOwnership(proof): OwnershipVerification

Defined in: @sip-protocol/sdk/dist/index-BYZbDjal.d.ts:8745

Verify an ownership proof

Checks that a proof is valid without learning the owner’s identity. Verifies the signature and ensures the challenge matches.

Parameters

proof

OwnershipProof

The ownership proof to verify

Returns

OwnershipVerification

Verification result

Example

const nft = new PrivateNFT()

// Verify proof from user
const result = nft.verifyOwnership(userProof)

if (result.valid) {
  console.log('Ownership verified!')
  console.log('NFT:', result.nftContract)
  console.log('Token ID:', result.tokenId)
} else {
  console.error('Invalid proof:', result.error)
}

transferPrivately()

transferPrivately(params): TransferResult

Defined in: @sip-protocol/sdk/dist/index-BYZbDjal.d.ts:8776

Transfer NFT privately to a new owner

Creates a new stealth address for the recipient to ensure unlinkability. The old and new ownership records cannot be linked on-chain.

Parameters

params

TransferPrivatelyParams

Transfer parameters

Returns

TransferResult

Transfer result with new ownership and transfer record

Throws

If parameters are invalid

Example

const nft = new PrivateNFT()

// Recipient shares their meta-address
const recipientMetaAddr = 'sip:ethereum:0x02abc...123:0x03def...456'

// Transfer NFT privately
const result = nft.transferPrivately({
  nft: currentOwnership,
  recipientMetaAddress: recipientMetaAddr,
})

// Publish transfer record for recipient to scan
await publishTransfer(result.transfer)

// Recipient can now scan and find their NFT

scanForNFTs()

scanForNFTs(scanKey, viewingKey, transfers): OwnedNFT[]

Defined in: @sip-protocol/sdk/dist/index-BYZbDjal.d.ts:8815

Scan for NFTs owned by this recipient

Scans a list of NFT transfers to find which ones belong to the recipient by checking if the stealth addresses can be derived from the recipient’s keys.

Uses view tag optimization for efficient scanning (rejects 255/256 of non-matching transfers).

Parameters

scanKey

Uint8Array

Recipient’s spending private key (for scanning)

viewingKey

Uint8Array

Recipient’s viewing private key (for key derivation)

transfers

NFTTransfer[]

List of NFT transfers to scan

Returns

OwnedNFT[]

Array of owned NFTs discovered through scanning

Throws

If keys are invalid

Example

const nft = new PrivateNFT()

// Recipient's keys
const { spendingPrivateKey, viewingPrivateKey } = recipientKeys

// Get published transfers (from chain, indexer, or API)
const transfers = await fetchNFTTransfers()

// Scan for owned NFTs
const ownedNFTs = nft.scanForNFTs(
  hexToBytes(spendingPrivateKey.slice(2)),
  hexToBytes(viewingPrivateKey.slice(2)),
  transfers
)

console.log(`Found ${ownedNFTs.length} NFTs!`)
for (const nft of ownedNFTs) {
  console.log(`NFT: ${nft.nftContract}#${nft.tokenId}`)
}