sigil-core · nft

#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct CollectionId(pub String);

pub fn new(s: impl Into<String>) -> Self;

pub fn try_new(s: impl Into<String>) -> Result<Self, CoreError>;

pub fn as_str(&self) -> &str;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct TokenId(pub u128);

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum NftKind {
    /// Standard ERC-721-style NFT — transferable unless locked by policy.
    Standard,
    /// Identity-bound NFT — non-transferable token representing a DID
    /// credential or on-chain identity claim.
    Identity,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum IdentityNftKind {
    /// Human root identity (HMR).
    Human,
    /// Machine / model root identity (MHR).
    Mhr,
    /// Enterprise / entity root identity (ENR).
    Enr,
    /// Autonomous agent identity.
    Agent,
    /// Autonomous organization identity.
    Ao,
    /// Application identity.
    App,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum BurnAuth {
    /// Only the original issuer may burn the token.
    IssuerOnly,
    /// Only the current owner may burn the token.
    OwnerOnly,
    /// Either the issuer or the current owner may burn the token.
    Both,
    /// The token is non-burnable.
    Neither,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum LockState {
    /// Token is locked and may not be transferred.
    Locked,
    /// Token is unlocked and may be transferred (subject to collection
    /// transfer policy).
    Unlocked,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CollectionPolicy {
/// When `true`, newly minted tokens start in the `Locked` state (ERC-5192).

pub default_locked: bool,
/// Default burn authorization applied to each newly minted token.

pub default_burn_auth: BurnAuth,
/// When `true`, the controller may update per-token metadata URIs and

/// hashes after mint (ERC-4906 inspired).

pub allow_metadata_updates: bool,
/// Optional policy governing who may mint tokens in this collection.

/// `None` means only the issuer DID can mint.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub mint_policy: Option<ControlPolicy>,
/// Optional policy governing who may initiate transfers.

/// `None` means the owner controls transfers (subject to `default_locked`).

#[serde(default, skip_serializing_if = "Option::is_none")]
pub transfer_policy: Option<ControlPolicy>,
/// Maximum number of tokens that may ever be minted in this collection.

/// `None` means unlimited supply.

///

/// Serialized as a quoted decimal string on the JSON wire for cross-language

/// safety (JavaScript's Number type cannot represent u128 exactly).

#[serde(
        with = "serde_helpers::string_u128_option",
        default,
        skip_serializing_if = "Option::is_none"
    )]
pub max_supply: Option<u128>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NftCollection {
/// Unique collection identifier.

pub collection_id: CollectionId,
/// Human-readable collection name.

pub name: String,
/// Short ticker symbol (e.g. "BADGE").

pub symbol: String,
/// Whether this collection is for transferable NFTs or identity tokens.

pub kind: NftKind,
/// DID of the party that created and issued the collection.

pub issuer_did: String,
/// DID of the party that can update the collection policy.

pub controller_did: String,
/// Governance rules for this collection.

pub policy: CollectionPolicy,
/// Optional collection-level metadata URI (analogous to ERC-721

/// `contractURI`).

#[serde(default, skip_serializing_if = "Option::is_none")]
pub metadata_uri: Option<String>,
/// Block height at which this collection was created.

pub created_height: u64,
/// Cumulative count of tokens minted (never decremented on burn).

pub total_minted: u128,
/// Cumulative count of tokens burned.

pub total_burned: u128
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct IdentityBinding {
/// DID of the identity subject this token is bound to.

pub subject_did: String,
/// DID of the root anchor (HMR / MHR / ENR) that vouches for this

/// subject.

pub root_did: String,
/// Kind of the root anchor.

pub root_kind: RootKind,
/// Specific identity sub-type for this token.

pub identity_kind: IdentityNftKind,
/// Numeric verification level (0 = unverified, 255 = fully verified).

pub verification_level: u8,
/// Optional pointer to an external reputation or attestation anchor.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub reputation_anchor: Option<String>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NftToken {
/// Collection this token belongs to.

pub collection_id: CollectionId,
/// Token identifier (unique within the collection).

pub token_id: TokenId,
/// DID of the current owner.

pub owner_did: String,
/// Optional per-token metadata URI.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub metadata_uri: Option<String>,
/// Optional BLAKE3 hash of the canonical metadata document, for

/// on-chain integrity verification.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub metadata_hash: Option<SigilHash>,
/// Whether this token is currently locked (ERC-5192).

pub locked: bool,
/// Burn authorisation for this token (ERC-5484).

pub burn_auth: BurnAuth,
/// Identity binding for tokens in identity collections.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub identity: Option<IdentityBinding>,
/// Block height at which this token was minted.

pub minted_height: u64,
/// Block height of the most recent metadata update (equals

/// `minted_height` if metadata has never been updated).

pub last_metadata_update_height: u64
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct OwnerIndexEntry {
/// The collection being indexed.

pub collection_id: CollectionId,
/// The owner DID.

pub owner_did: String,
/// All token IDs currently held by this owner in this collection.

pub token_ids: Vec<TokenId>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DidIdentityIndex {
/// The subject DID being indexed.

pub subject_did: String,
/// All `(collection_id, token_id)` pairs of identity tokens bound to

/// this DID.

pub identity_tokens: Vec<(CollectionId, TokenId)>
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum NftEventKind {
    /// A new token was minted.
    Mint,
    /// Token ownership was transferred.
    Transfer,
    /// Token was burned.
    Burn,
    /// Token metadata URI or hash was updated (ERC-4906).
    MetadataUpdate,
    /// Token was locked (ERC-5192).
    Locked,
    /// Token was unlocked (ERC-5192).
    Unlocked,
    /// Identity binding verification level was raised.
    IdentityVerified,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NftEvent {
/// The kind of state change that occurred.

pub kind: NftEventKind,
/// The collection in which the event occurred.

pub collection_id: CollectionId,
/// The token involved, or `None` for collection-level events.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub token_id: Option<TokenId>,
/// Previous owner or minting authority (present on Transfer and Burn).

#[serde(default, skip_serializing_if = "Option::is_none")]
pub from_did: Option<String>,
/// New owner or recipient (present on Mint and Transfer).

#[serde(default, skip_serializing_if = "Option::is_none")]
pub to_did: Option<String>,
/// Updated metadata URI (present on MetadataUpdate and Mint when

/// metadata_uri is supplied).

#[serde(default, skip_serializing_if = "Option::is_none")]
pub metadata_uri: Option<String>,
/// Updated metadata hash (present on MetadataUpdate and Mint when

/// metadata_hash is supplied).

#[serde(default, skip_serializing_if = "Option::is_none")]
pub metadata_hash: Option<SigilHash>,
/// Block height at which this event was emitted.

pub block_height: u64,
/// Hash of the transaction that produced this event.

pub tx_hash: SigilHash
}