Core Logic: Tokentagged.sol

Tokentagged.sol is the heart of the system. It implements the logic for verifying the high-security NXP P71D321 (EAL 6+) chips and defines the token structure.

Abstract Contract

This contract is not deployed directly; it is inherited by TokentaggedAssets and TokentaggedCollection. It provides the security functions for all collections.

Token ID Bit-Splitting

To save storage (gas) and provide maximum flexibility, we use a bit-splitting method. A single uint256 token ID contains multiple pieces of information at once.

Bit Range	Length	Name	Description
256 - 177	80 bits	Semi Fungible ID	ID for editions or serial numbers.
176 - 161	16 bits	Flags	Defines the token type (NFT, FT, SFT).
160 - 1	160 bits	Tokentag ID	The unique address (derived from the public key) of the chip.

Type Definitions (Flags)

Bitmask	Type	Description
0	NFT	Unique (1:1 with a physical object). Amount is always 1.
1 << 161	SFT	Semi-fungible token (e.g., limited editions).
1 << 162	VFT	Versatile fungible token.
1 << 163	FT	Fungible token (e.g., loyalty points per tag).

Security Concept: The Verification Chain

Tokentagged security is based on a multi-stage hardware security model ("trust chain"). A key property is that the card private key is not known to the manufacturer because it is derived only after user activation.

To still guarantee hardware authenticity, the smart contract (TokentaggedSignerRegistry) verifies a chain of certificates.

Key Hierarchy

The following diagram shows the dependencies. Note: the master key is created inside the chip (on-chip generated) and is not created by the manufacturer, only signed.

The Verification Process (On-Chain)

For every transaction (mintTokentag or verifyTokentag), three cryptographic proofs are validated. Only if all three checks succeed is the chip considered authentic and secure.

1. Challenge Signature (User Action)

Proves that the physically present chip possesses the Card-Private-Key and authorized the transaction.

• Check: ecrecover(TxHash, Signature) == Card-Address
• Location: Tokentagged.sol

2. Card Attestation (Integrity Check)

Proves that the Card-Key used was legitimately derived from the chip's Master-Key. This prevents someone from generating an arbitrary key and claiming it belongs to a chip.

• Check: ecrecover(Card-Address, Card-Attestation) == Master-Address
• Location: TokentaggedSignerRegistry.sol
• Additional check: Is the Master-Address on the blacklist? (In case a chip was physically compromised).

3. Root Attestation (Authenticity Check)

Proves that the Master-Key from Tokentagged was programmed into an original NXP chip.

• Check: ecrecover(Master-Address, Root-Attestation) == Trusted-Issuer-Address
• Location: TokentaggedSignerRegistry.sol

Code Logic (Simplified)

The following pseudocode shows the logic inside the verifyTokentagAuthenticity function in the registry:

function verifyTokentagAuthenticity(address cardId, bytes cardAtstSig, bytes rootAtstSig) external view returns (bool) {
    
    // Step 1: Recover master address from the card attestation
    // Proves: This card key belongs to this master key
    address masterAddr = ecrecover(cardId, cardAtstSig);
    
    // Step 2: Security check
    // Was this master key reported as compromised?
    require(!blacklistedMasters[masterAddr], "Master is blacklisted");

    // Step 3: Recover issuer address from the root attestation
    // Proves: This master key is a genuine Tokentagged chip
    address issuerAddr = ecrecover(masterAddr, rootAtstSig);
    
    // Step 4: Whitelist check
    // Is the signer an authorized Tokentagged issuer?
    return trustedSigners[issuerAddr];
}