SealedBidAuction

SIP Protocol API Reference / SealedBidAuction

Class: SealedBidAuction

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

Sealed-Bid Auction Manager

Provides cryptographic primitives for sealed-bid auctions where bidders commit to their bids without revealing them until a reveal phase.

Examples

import { SealedBidAuction } from '@sip-protocol/sdk'

const auction = new SealedBidAuction()

// BIDDING PHASE
// Alice creates a sealed bid for 100 ETH
const aliceBid = auction.createBid({
  auctionId: 'auction-123',
  amount: 100n * 10n**18n, // 100 ETH
})

// Submit commitment on-chain (only commitment is public)
await submitBidOnChain({
  auctionId: aliceBid.auctionId,
  commitment: aliceBid.commitment,
  timestamp: aliceBid.timestamp,
})

// Alice keeps the receipt secret
secureStorage.save(aliceBid) // Contains amount + salt

// REVEAL PHASE (after bidding closes)
// Alice reveals her bid
await revealBidOnChain({
  auctionId: aliceBid.auctionId,
  amount: aliceBid.amount,
  salt: aliceBid.salt,
})

// Anyone can verify the revealed bid matches the commitment
const isValid = auction.verifyBid({
  commitment: aliceBid.commitment,
  amount: aliceBid.amount,
  salt: aliceBid.salt,
})
console.log('Bid valid:', isValid) // true

// Bob and Carol also bid
const bobBid = auction.createBid({
  auctionId: 'auction-123',
  amount: 150n * 10n**18n, // 150 ETH
})

const carolBid = auction.createBid({
  auctionId: 'auction-123',
  amount: 120n * 10n**18n, // 120 ETH
})

// All commitments are public, but amounts are hidden
// Nobody knows who bid what until reveal phase

// After all bids revealed, determine winner
const bids = [
  { bidder: 'Alice', amount: 100n },
  { bidder: 'Bob', amount: 150n },   // Highest bid
  { bidder: 'Carol', amount: 120n }, // Second highest
]

const winner = 'Bob' // Highest bidder
const price = 120n   // Pays second-highest bid (Carol's)

Constructors

Constructor

new SealedBidAuction(): SealedBidAuction

Returns

SealedBidAuction

Methods

createBid()

createBid(params): BidReceipt

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

Create a sealed bid for an auction

Generates a cryptographically binding commitment to a bid amount. The commitment can be published publicly without revealing the bid.

Important: Keep the returned BidReceipt secret! It contains the bid amount and salt needed to reveal the bid later. Only publish the commitment.

Parameters

params

CreateBidParams

Bid creation parameters

Returns

BidReceipt

Complete bid receipt (keep secret!) and sealed bid (publish this)

Throws

If auctionId is empty, amount is non-positive, or salt is invalid

Example

const auction = new SealedBidAuction()

// Create a bid for 50 ETH
const receipt = auction.createBid({
  auctionId: 'auction-xyz',
  amount: 50n * 10n**18n,
})

// Public data (safe to publish)
console.log({
  auctionId: receipt.auctionId,
  commitment: receipt.commitment,
  timestamp: receipt.timestamp,
})

// Secret data (store securely, needed for reveal)
secureStorage.save({
  amount: receipt.amount,
  salt: receipt.salt,
})

verifyBid()

verifyBid(params): boolean

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

Verify that a revealed bid matches its commitment

Checks that the commitment opens to the claimed bid amount with the provided salt. This proves the bidder committed to this exact amount during the bidding phase.

Parameters

params

VerifyBidParams

Verification parameters

Returns

boolean

true if the bid is valid, false otherwise

Throws

If commitment or salt format is invalid

Examples

const auction = new SealedBidAuction()

// During reveal phase, bidder reveals their bid
const revealed = {
  commitment: '0x02abc...', // From bidding phase
  amount: 50n * 10n**18n,   // Revealed now
  salt: '0x123...',         // Revealed now
}

// Anyone can verify
const isValid = auction.verifyBid(revealed)

if (isValid) {
  console.log('✓ Bid is valid - bidder committed to this amount')
} else {
  console.log('✗ Bid is invalid - possible cheating attempt!')
}

// Bidder tries to change their bid amount
const cheatingAttempt = {
  commitment: aliceBid.commitment, // Original commitment
  amount: 200n * 10n**18n,        // Different amount!
  salt: aliceBid.salt,
}

const isValid = auction.verifyBid(cheatingAttempt)
console.log(isValid) // false - commitment doesn't match!

revealBid()

revealBid(bid, amount, salt): RevealedBid

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

Reveal a sealed bid by exposing the amount and salt

Converts a BidReceipt (with secrets) into a RevealedBid (all public). This is what bidders submit during the reveal phase to prove their bid.

Important: This method validates that the revealed data matches the commitment before returning. If validation fails, it throws an error.

Parameters

bid

SealedBid

The sealed bid to reveal (must include amount and salt from BidReceipt)

amount

bigint

The bid amount to reveal

salt

Uint8Array

The salt/blinding factor to reveal

Returns

RevealedBid

Complete revealed bid ready for public verification

Throws

If the revealed data doesn’t match the commitment (cheating attempt)

Examples

const auction = new SealedBidAuction()

// BIDDING PHASE
const receipt = auction.createBid({
  auctionId: 'auction-1',
  amount: 100n,
})

// Submit commitment on-chain (only commitment is public)
await submitToChain({
  auctionId: receipt.auctionId,
  commitment: receipt.commitment,
  timestamp: receipt.timestamp,
})

// REVEAL PHASE (after bidding closes)
const revealed = auction.revealBid(
  { auctionId: receipt.auctionId, commitment: receipt.commitment, timestamp: receipt.timestamp },
  receipt.amount,
  receipt.salt
)

// Submit revealed bid on-chain for verification
await revealOnChain(revealed)

const receipt = auction.createBid({
  auctionId: 'auction-1',
  amount: 100n,
})

// Try to reveal a different amount (cheating!)
try {
  auction.revealBid(
    { auctionId: receipt.auctionId, commitment: receipt.commitment, timestamp: receipt.timestamp },
    200n, // Different amount!
    receipt.salt
  )
} catch (error) {
  console.log('Cheating detected!') // ValidationError thrown
}

verifyReveal()

verifyReveal(bid, reveal): boolean

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

Verify that a revealed bid matches its original sealed bid

Convenience method that verifies a RevealedBid object. This is equivalent to calling verifyBid() with the reveal’s components.

Parameters

bid

SealedBid

The sealed bid from the bidding phase

reveal

RevealedBid

The revealed bid to verify

Returns

boolean

true if reveal is valid, false otherwise

Throws

If inputs are malformed

Examples

const auction = new SealedBidAuction()

// Bidding phase
const receipt = auction.createBid({
  auctionId: 'auction-1',
  amount: 100n,
})

const sealedBid = {
  auctionId: receipt.auctionId,
  commitment: receipt.commitment,
  timestamp: receipt.timestamp,
}

// Reveal phase
const reveal = auction.revealBid(sealedBid, receipt.amount, hexToBytes(receipt.salt.slice(2)))

// Anyone can verify
const isValid = auction.verifyReveal(sealedBid, reveal)
console.log(isValid) // true

// Someone tries to reveal a different bid for the same commitment
const fakeReveal = {
  ...reveal,
  amount: 200n, // Different amount!
}

const isValid = auction.verifyReveal(sealedBid, fakeReveal)
console.log(isValid) // false

hashAuctionMetadata()

hashAuctionMetadata(data): `0x${string}`

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

Hash auction metadata for deterministic auction IDs

Creates a unique auction identifier from auction parameters. Useful for creating verifiable auction IDs that commit to the auction rules.

Parameters

data

Record<string, unknown>

Auction metadata to hash

Returns

`0x${string}`

Hex-encoded hash of the auction metadata

Example

const auction = new SealedBidAuction()

// Create deterministic auction ID
const auctionId = auction.hashAuctionMetadata({
  itemId: 'nft-token-123',
  seller: '0xABCD...',
  startTime: 1704067200,
  endTime: 1704153600,
})

// Use this ID for all bids
const bid = auction.createBid({
  auctionId,
  amount: 100n,
})

determineWinner()

determineWinner(revealedBids): WinnerResult

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

Determine the winner from revealed bids

Finds the highest valid bid. In case of tie (same amount), the earliest bid (lowest timestamp) wins.

Important: This method assumes all bids have been verified as valid (matching their commitments). Always verify bids before determining winner.

Parameters

revealedBids

RevealedBid[]

Array of revealed bids to evaluate

Returns

WinnerResult

Winner result with bid details

Throws

If no bids provided or auction IDs don’t match

Examples

const auction = new SealedBidAuction()

// After reveal phase, determine winner
const revealedBids = [
  { auctionId: 'auction-1', commitment: '0x...', amount: 100n, salt: '0x...', timestamp: 1000 },
  { auctionId: 'auction-1', commitment: '0x...', amount: 150n, salt: '0x...', timestamp: 2000 },
  { auctionId: 'auction-1', commitment: '0x...', amount: 120n, salt: '0x...', timestamp: 1500 },
]

const winner = auction.determineWinner(revealedBids)
console.log(`Winner bid: ${winner.amount} (timestamp: ${winner.timestamp})`)
// Output: "Winner bid: 150 (timestamp: 2000)"

const tiedBids = [
  { auctionId: 'auction-1', commitment: '0x...', amount: 100n, salt: '0x...', timestamp: 2000 },
  { auctionId: 'auction-1', commitment: '0x...', amount: 100n, salt: '0x...', timestamp: 1000 }, // Earlier
  { auctionId: 'auction-1', commitment: '0x...', amount: 100n, salt: '0x...', timestamp: 1500 },
]

const winner = auction.determineWinner(tiedBids)
console.log(winner.timestamp) // 1000 (earliest bid wins)

verifyWinner()

verifyWinner(winner, revealedBids): boolean

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

Verify that a claimed winner is actually the highest bidder

Checks that the winner’s amount is >= all other revealed bids. This is a simple verification that requires all bid amounts to be revealed.

For privacy-preserving verification (without revealing losing bids), use verifyWinnerProof instead.

Parameters

winner

WinnerResult

The claimed winner result

revealedBids

RevealedBid[]

All revealed bids to check against

Returns

boolean

true if winner is valid, false otherwise

Examples

const auction = new SealedBidAuction()

const bids = [
  { auctionId: 'auction-1', commitment: '0x...', amount: 100n, salt: '0x...', timestamp: 1000 },
  { auctionId: 'auction-1', commitment: '0x...', amount: 150n, salt: '0x...', timestamp: 2000 },
]

const winner = auction.determineWinner(bids)
const isValid = auction.verifyWinner(winner, bids)
console.log(isValid) // true

// Someone tries to claim they won with a lower bid
const fakeWinner = {
  auctionId: 'auction-1',
  commitment: '0x...',
  amount: 50n, // Lower than highest bid!
  salt: '0x...',
  timestamp: 500,
}

const isValid = auction.verifyWinner(fakeWinner, bids)
console.log(isValid) // false

createWinnerProof()

createWinnerProof(winner, revealedBids): WinnerProof

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

Create a zero-knowledge style proof that a winner is valid

Generates a proof that the winner bid is >= all other bids WITHOUT revealing the losing bid amounts. Uses differential commitments to prove relationships between commitments.

Privacy Properties:

Reveals: Winner amount, number of bids, commitment hash
Hides: All losing bid amounts (they remain committed)

How it works: For each losing bid i, we compute: C_winner - C_i This differential commitment commits to (amount_winner - amount_i). Observers can verify C_winner - C_i without learning amount_i.

Parameters

winner

WinnerResult

The winner to create proof for

revealedBids

RevealedBid[]

All bids (needed to compute differentials)

Returns

WinnerProof

Winner proof ready for verification

Throws

If inputs are invalid

Example

const auction = new SealedBidAuction()

// After determining winner
const bids = [
  { auctionId: 'auction-1', commitment: '0xabc...', amount: 100n, salt: '0x...', timestamp: 1000 },
  { auctionId: 'auction-1', commitment: '0xdef...', amount: 150n, salt: '0x...', timestamp: 2000 },
  { auctionId: 'auction-1', commitment: '0x123...', amount: 120n, salt: '0x...', timestamp: 1500 },
]

const winner = auction.determineWinner(bids)
const proof = auction.createWinnerProof(winner, bids)

// Proof can be verified without revealing losing bids
// Only winner amount (150) is revealed
console.log(proof.winnerAmount) // 150n
console.log(proof.totalBids) // 3
console.log(proof.differentialCommitments.length) // 2 (for the 2 losing bids)

verifyWinnerProof()

verifyWinnerProof(proof, allCommitments): WinnerVerification

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

Verify a winner proof without revealing losing bid amounts

Verifies that the winner proof is valid by checking:

Commitments hash matches (prevents tampering)
Differential commitments are consistent
Winner commitment is included in the original commitments

Privacy: This verification does NOT require revealing losing bid amounts! Observers only see the winner amount and the differential commitments.

Parameters

proof

WinnerProof

The winner proof to verify

allCommitments

`0x${string}`[]

All bid commitments (public, from bidding phase)

Returns

WinnerVerification

Verification result with details

Examples

const auction = new SealedBidAuction()

// Observer only has: winner proof + original commitments (no amounts!)
const commitments = [
  '0xabc...', // Unknown amount
  '0xdef...', // Unknown amount (this is the winner)
  '0x123...', // Unknown amount
]

const proof = { ... } // Received winner proof

// Verify without knowing losing bid amounts
const verification = auction.verifyWinnerProof(proof, commitments)
console.log(verification.valid) // true
console.log(verification.details.bidsChecked) // 3

// Someone tries to modify commitments
const tamperedCommitments = [
  '0xabc...',
  '0xFAKE...', // Changed!
  '0x123...',
]

const verification = auction.verifyWinnerProof(proof, tamperedCommitments)
console.log(verification.valid) // false
console.log(verification.reason) // "commitments hash mismatch"