§ BTCO Verifiable Metadata

Specification Status: EDITORS DRAFT

Specification Version: v0.2.0 (see Changelog)

Source of Latest Draft: https://github.com/decentralized-identity/labs-ordinals-plus

Information Site: https://ordinals.plus/

Editors:
Brian Richter
Participate:
GitHub repo
File a bug
Commit history

§ Abstract

BTCO Verifiable Metadata (BTCO-VM) is a specification for creating and verifying metadata about Bitcoin Ordinal inscriptions using the W3C Verifiable Credentials Data Model 2.0. This specification defines how to issue, verify, and manage verifiable metadata on Bitcoin using ordinal theory and BTCO DIDs.

§ Overview

§ Purpose

BTCO Verifiable Metadata (BTCO-VM) enables the creation and verification of claims about Bitcoin Ordinal inscriptions. The specification leverages the W3C Verifiable Credentials Data Model 2.0 and BTCO DIDs to provide a standardized way to make verifiable assertions about ordinal inscriptions.

§ Key Features

  1. Trustless Verification

    • Leverages Bitcoin’s security model
    • Uses cryptographic proofs
    • Supports decentralized verification

  2. Ordinal-Native

    • Built on BTCO DIDs
    • Inscription-based storage
    • Bitcoin-secured credentials

  3. Credential Types

    • Curated Collection credentials
    • Verifiable Collectible credentials
    • Extensible for future types

  4. Standards Compliance

    • W3C Verifiable Credentials 2.0
    • DID Core specification
    • JSON-LD compatibility

§ Use Cases

  1. Collection Curation

    • Authenticate collections
    • Establish provenance
    • Track ownership history

  2. Artifact Verification

    • Verify authenticity
    • Establish creator identity
    • Document properties

  3. Rights Management

    • License verification
    • Usage permissions
    • Transfer restrictions

§ Architecture

The BTCO-VM system consists of:

  1. Credential Schema

    • Base credential structure
    • Type-specific extensions
    • Validation rules

  2. Issuance Process

    • Credential creation
    • Digital signing
    • Inscription storage

  3. Verification System

    • Proof validation
    • Status checking
    • Rules enforcement

  4. Revocation Mechanism

    • Status tracking
    • Revocation credentials
    • Status resolution

§ Specification

§ 1. Introduction

BTCO Verifiable Metadata (BTCO-VM) is a specification for creating, verifying, and managing metadata about Bitcoin Ordinal inscriptions using W3C Verifiable Credentials standards. This specification leverages BTCO DIDs and BTCO DID Linked Resources to provide a standardized approach for making verifiable assertions about ordinal inscriptions.

§ 2. Schema Requirements

All BTCO Verifiable Metadata MUST adhere to these core requirements:

  1. Conform to W3C Verifiable Credentials Data Model 2.0
  2. Use BTCO DIDs for issuer and subject identifiers
  3. Implement DataIntegrityProof with supported cryptosuites
  4. Include required metadata properties based on credential type

§ 2.1 BTCO Context

The https://ordinals.plus/v1 context defines BTCO-specific terms used in this specification:

{
  "@context": {
    "@version": 1.1,
    "btco": "https://ordinals.plus/v1#",
    "BTCOResourceMetadata": "btco:ResourceMetadata",
    "ResourceMetadataCredential": "btco:ResourceMetadataCredential",
    "CollectionCredential": "btco:CollectionCredential",
    "VerifiableCollectible": "btco:VerifiableCollectible",
    "CuratedCollectionCredential": "btco:CuratedCollectionCredential",
    "BTCOResource": "btco:Resource",
    "BTCOCollection": "btco:Collection",
    "Collectible": "btco:Collectible",
    "CuratedCollection": "btco:CuratedCollection",
    "metadata": "btco:metadata",
    "properties": "btco:properties",
    "collectionType": "btco:collectionType",
    "resources": "btco:resources",
    "status": "btco:status",
    "statusListCredential": "btco:statusListCredential",
    "statusListIndex": "btco:statusListIndex"
  }
}

This context provides the vocabulary for all BTCO-specific terms used in credentials and ensures interoperability between different implementations.

§ 3. Base Structure

This minimal structure serves as the foundation for all BTCO Verifiable Metadata:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://ordinals.plus/v1"
  ],
  "type": ["VerifiableCredential", "BTCOResourceMetadata"],
  "issuer": {
    "id": "did:btco:<sat-number>"
  },
  "validFrom": "<iso-8601-date>",
  "credentialSubject": {
    "id": "did:btco:<sat-number>",
    "type": "BTCOResource",
    "metadata": {
      "name": "<string>",
      "description": "<string>"
    }
  }
}
NOTE

A formal JSON Schema for validation will be added in a future version of this specification. The structure shown above represents the minimal required fields.

§ 4. Integration with BTCO DID Linked Resources

BTCO Verifiable Metadata leverages BTCO DID Linked Resources to provide a comprehensive solution for metadata about ordinal inscriptions.

§ 4.1 Resource Association

Verifiable Metadata can be associated with BTCO DID Linked Resources in two ways:

  1. Self-describing Metadata:

    • Credential describes the resource it is inscribed on
    • credentialSubject.id equals the DID of the containing satoshi
    • Accessible via the /meta endpoint of the resource
    did:btco:1954913028215432/0/meta

  2. Referential Metadata:

    • Credential describes one or more other resources
    • credentialSubject.id differs from the credential’s resource DID
    • Creates a verifiable link between resources

§ 4.2 Collection Metadata

Collections defined in BTCO DID Linked Resources can be enhanced with verifiable metadata:

  1. Curated Collections:

    • Uses a Verifiable Credential to define collection membership
    • Provides authenticated curation with issuer attestation
    • Allows verification of collection integrity and provenance

  2. Heritage Collections:

    • Can reference parent/child relationships with verified metadata
    • Enables verified provenance chains through heritage relationships

§ 5. Metadata Verification

§ 5.1 Standard Verification Process

Verification of BTCO Verifiable Metadata MUST follow these standardized steps:

  1. Resolution:

    • Resolve the metadata’s BTCO DID Linked Resource using the inscription index
    • Retrieve the complete credential document

  2. Structure Validation:

    • Validate that the credential has all required fields according to W3C VC Data Model
    • Validate that the BTCO-specific fields conform to this specification
    • Validate that timestamps are properly formatted and logical

  3. Proof Verification:

    • For each proof in the proof or proofs array:
      • Identify the cryptosuite used
      • Resolve the verification method from the DID referenced in the proof
      • Verify the proof according to the cryptosuite’s specific verification algorithm
      • All proofs MUST verify successfully, as required by W3C Data Integrity specifications

  4. Issuer Verification:

    • Resolve the issuer’s DID Document using the BTCO DID Method
    • Verify the issuer controls the satoshi by:
      • Checking that the verification method referenced in the proof belongs to the issuer’s DID Document
      • Validating that the DID Document contains the verification method identifier
      • Confirming the controller property of the verification method matches the issuer’s DID
    • When using the verification method, confirm that:
      • The satoshi number in the verification method MUST match the issuer’s satoshi number (they are the same satoshi)
      • The inscription indexed in the verification method contains the actual verification key material
      • This ensures that the same entity that owns the satoshi also controls the verification keys

  5. Reference Validation:

    • Validate that all DIDs referenced in the credential exist and resolve successfully
    • For indexed references to specific inscriptions, verify those inscriptions exist

  6. Type-Specific Validation:

    • Apply credential-type-specific validation rules as defined in this specification
    • For ResourceMetadataCredential, verify the referenced resource properties
    • For CollectionCredential, verify all resources in the collection exist

  7. Status Checking:

    • If the credential has a status property, check its current status using the status property format
    • Retrieve the status list credential referenced in the status property
    • Verify the status list credential is valid and issued by an authorized entity
    • Check the referenced index within the status list
    • Reject credentials that have been revoked

§ 5.2 DataIntegrityProof Verification

Verification of DataIntegrityProof proofs MUST follow the procedures defined in the relevant cryptosuite specifications:

NOTE

The verification process varies by cryptosuite and includes considerations for proof options, canonicalization method, and signature verification algorithms. Implementers should refer to the specific cryptosuite specification.

§ 5.3 Technical Requirements

Implementation of verification MUST:

  1. Support multiple proofs (either as an array or as a single object)
  2. Handle DID resolution errors gracefully
  3. Report specific verification failures with clear error messages
  4. Validate temporal claims (validFrom, validUntil) against current time
  5. Cache DID resolution results appropriately for performance

The verification process must locate the specific inscription that contains the verification keys using the inscribed index in the verification method, while the identity of the issuer and subject are determined by the satoshi itself (without index).

§ 6. Resource Identification and Referencing

BTCO-VM uses two different approaches for identifying resources, depending on the context:

  1. Identity References:

    • The issuer.id always uses the non-indexed form (did:btco:<sat-number>) to identify the satoshi
    • This represents the persistent identity of the entity that issued the credential

  2. Resource References:

    • For credentialSubject.id, the appropriate form depends on what’s being described:
      • When describing a satoshi as a whole: use the non-indexed form (did:btco:<sat-number>)
      • When describing a specific inscription (like an image): use the indexed form (did:btco:<sat-number>/<index>)
      • When describing a collection: use the non-indexed form for the collection satoshi

  3. Verification References:

    • The verificationMethod always uses the indexed form (did:btco:<sat-number>/<index>#key-1)
    • This precisely identifies which inscription contains the verification keys

This approach allows maximum flexibility and precision:

EXAMPLE

A Verifiable Collectible credential about a specific artwork would use:

  • issuer.id: did:btco:123456 (the creator’s identity)
  • credentialSubject.id: did:btco:789012/0 (the specific inscription containing the artwork)
  • verificationMethod: did:btco:123456/2#key-1 (the specific inscription containing the verification key)

Implementations MUST validate these relationships and ensure claims are appropriate to the credential type.

NOTE

Using the non-indexed form for identity references while using the indexed form for specific content and verification provides the best balance between stable identity and precise content addressing. This allows credentials about identities to remain valid even as resources are updated, while ensuring that references to specific content remain exact.

§ 7. Credential Types

§ 7.1 Resource Metadata Credential

Basic credential for describing properties of a specific inscription resource.

§ Required Properties
§ Optional Properties
§ Validation Rules
  1. The credentialSubject.id MUST be a valid BTCO DID URL
  2. If an indexed form is used, the inscription MUST exist
  3. The name and description MUST NOT be empty
  4. The contentType MUST be a valid MIME type
  5. The created date MUST be a valid ISO 8601 date
  6. The created date MUST NOT be in the future
§ Example
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://ordinals.plus/v1"
  ],
  "type": ["VerifiableCredential", "ResourceMetadataCredential"],
  "issuer": {
    "id": "did:btco:539864085599956"
  },
  "validFrom": "2024-03-21T12:00:00Z",
  "credentialSubject": {
    "id": "did:btco:1954913028215432/0",
    "type": "BTCOResource",
    "name": "Example Resource",
    "description": "An example resource with verified metadata",
    "properties": {
      "contentType": "image/png",
      "created": "2024-03-20T10:30:00Z",
      "creator": "Example Artist"
    }
  }
}

§ 7.2 Collection Credential

Credential for defining and authenticating a collection of resources.

§ Required Properties
§ Optional Properties
§ Validation Rules
  1. The credentialSubject.id MUST be a valid BTCO DID
  2. The name and description MUST NOT be empty
  3. The collectionType MUST be one of the defined collection types
  4. The resources array MUST NOT be empty
  5. Each item in resources MUST be a valid BTCO DID URL
  6. All resources referenced in the collection MUST exist
  7. If created is present, it MUST be a valid ISO 8601 date
  8. If updated is present, it MUST be a valid ISO 8601 date not earlier than created
§ Example
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://ordinals.plus/v1"
  ],
  "type": ["VerifiableCredential", "CollectionCredential"],
  "issuer": {
    "id": "did:btco:539864085599956"
  },
  "validFrom": "2024-03-21T12:00:00Z",
  "credentialSubject": {
    "id": "did:btco:539864085599956",
    "type": "BTCOCollection",
    "name": "Example Collection",
    "description": "A verified collection of resources",
    "collectionType": "curated",
    "resources": [
      "did:btco:1954913028215432/0",
      "did:btco:1923519999999991/2"
    ]
  }
}

§ 7.3 VerifiableCollectible Credential

A credential type for verifying authenticity and properties of individual collectible inscriptions.

§ Required Properties
§ Optional Properties
§ Validation Rules
  1. The credentialSubject.id MUST be a valid BTCO DID URL using the indexed form
  2. The creator DID MUST be valid and resolvable
  3. The issuer MUST be the creator or authorized by the creator
  4. The creation date MUST NOT be in the future
  5. The referenced inscription MUST exist and match the properties
§ Example
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://ordinals.plus/v1"
  ],
  "type": ["VerifiableCredential", "VerifiableCollectible"],
  "issuer": {
    "id": "did:btco:539864085599956"
  },
  "validFrom": "2024-03-21T12:00:00Z",
  "credentialSubject": {
    "id": "did:btco:1954913028215432/0",
    "type": "Collectible",
    "title": "Artifact Title",
    "creator": "did:btco:539864085599956",
    "creationDate": "2024-03-21",
    "properties": {
      "medium": "Digital",
      "format": "image/png",
      "dimensions": "3000x3000"
    },
    "rights": {
      "license": "CC BY-SA 4.0",
      "terms": "https://creativecommons.org/licenses/by-sa/4.0/"
    }
  }
}

§ 7.4 CuratedCollection Credential

A credential type for establishing curated collections of ordinal inscriptions.

§ Required Properties
§ Optional Properties
§ Validation Rules
  1. All items in the collection MUST be valid BTCO DIDs
  2. The issuer MUST control the DID at time of issuance
  3. The collection MUST contain at least one item
  4. The name and description MUST NOT be empty
§ Example
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://ordinals.plus/v1"
  ],
  "type": ["VerifiableCredential", "CuratedCollectionCredential"],
  "issuer": {
    "id": "did:btco:539864085599956"
  },
  "validFrom": "2024-03-21T12:00:00Z",
  "credentialSubject": {
    "id": "did:btco:539864085599956/0",
    "type": "CuratedCollection",
    "name": "Example Collection",
    "description": "A curated collection of digital artifacts",
    "items": [
      "did:btco:1954913028215432/0",
      "did:btco:1923519999999991/0"
    ],
    "curatorDetails": {
      "name": "Curator Name",
      "statement": "Curatorial statement"
    }
  }
}

§ 8. Proof Requirements

All BTCO Verifiable Metadata MUST include at least one cryptographic proof. Proofs can be represented either as a single proof object or as an array of proof objects:

§ 8.1 Single Proof Example

"proof": {
  "type": "DataIntegrityProof",
  "cryptosuite": "eddsa-jcs-2022",
  "created": "2024-03-21T12:00:00Z",
  "verificationMethod": "did:btco:539864085599956/0#key-1",
  "proofPurpose": "assertionMethod",
  "proofValue": "z..."
}

§ 8.2 Multiple Proofs Example

"proofs": [
  {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2024-03-21T12:00:00Z",
    "verificationMethod": "did:btco:539864085599956/0#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z..."
  },
  {
    "type": "DataIntegrityProof",
    "cryptosuite": "ecdsa-jcs-2019",
    "created": "2024-03-21T12:01:00Z",
    "verificationMethod": "did:btco:539864085599956/0#key-2",
    "proofPurpose": "assertionMethod",
    "proofValue": "z..."
  }
]

Note that while the issuer.id and credentialSubject.id use the non-indexed form of the DID (did:btco:<sat-number>), the verificationMethod in the proof uses the indexed form (did:btco:<sat-number>/<index>#key-1) to precisely identify which inscription contains the verification keys.

§ 8.3 Proof Requirements

Each proof MUST include:

  1. type: The type of proof, typically “DataIntegrityProof”
  2. cryptosuite: Identifier for the specific cryptographic suite used
  3. created: Timestamp indicating when the proof was created
  4. verificationMethod: The specific verification method to use
  5. proofPurpose: The purpose of the proof, typically “assertionMethod”
  6. proofValue: The cryptographic proof value, formatted according to the cryptosuite

Implementations MUST:

  1. Support verification of credentials with either a single proof object or an array of proof objects
  2. Consider a credential valid only if all proofs successfully verify
  3. Record which proofs were successfully verified when multiple proofs are present
  4. Support the recommended eddsa-jcs-2022 cryptosuite at minimum

Supported cryptosuites with varying levels of interoperability:

NOTE

This list of supported cryptosuites is preliminary and will evolve as implementation experience grows. Implementers should prioritize support for the recommended cryptosuite (eddsa-jcs-2022) for maximum interoperability, while other cryptosuites may have varying levels of support across implementations.

§ 9. Verifiable Presentations

BTCO Verifiable Metadata can be combined and presented using W3C Verifiable Presentations.

§ 9.1 Presentation Format

A BTCO Verifiable Presentation follows this format:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://ordinals.plus/v1"
  ],
  "type": ["VerifiablePresentation", "BTCOPresentation"],
  "holder": {
    "id": "did:btco:<sat-number>"
  },
  "verifiableCredential": [
    {
      // First BTCO Verifiable Metadata credential
    },
    {
      // Second BTCO Verifiable Metadata credential
    }
  ],
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022", 
    "created": "2024-03-22T10:00:00Z",
    "verificationMethod": "did:btco:<sat-number>/<index>#key-1",
    "proofPurpose": "authentication",
    "proofValue": "z..."
  }
}

§ 9.2 Presentation Usage

BTCO Verifiable Presentations can be used in two ways:

  1. Inscribed Presentations:

    • A Verifiable Presentation inscribed directly on Bitcoin
    • Accessible via a BTCO DID URL (e.g., did:btco:1954913028215432/1)
    • Creates a permanent record of the presentation

  2. Off-chain Presentations:

    • Created and shared without being inscribed
    • Used for short-lived verification contexts
    • May contain time-bound proofs or domain-specific constraints
NOTE

When organizing credentials, consider whether to use:

  • A Verifiable Presentation (holder-centered, can include credentials from multiple issuers)
  • A Collection Credential (issuer-centered, references multiple resources)

The choice depends on the use case and whether the focus is on holder presentation or issuer attestation.

§ 9.3 Presentation Verification

Verification of a BTCO Verifiable Presentation requires:

  1. Verifying each credential within the presentation independently
  2. Verifying the presentation proof using the holder’s verification method
  3. Validating temporal constraints (validity period, timestamps)
  4. Checking domain-specific constraints if present

§ 10. Credential Issuance

The process of creating and issuing BTCO Verifiable Metadata credentials consists of several distinct steps:

§ 10.1 Issuance Process

  1. Key Generation:

    • Generate a cryptographic key pair suitable for the chosen cryptosuite
    • EdDSA (Ed25519) keys are recommended for maximum interoperability
    • ECDSA (secp256k1) keys may be used for Bitcoin-native compatibility
    • Store private keys securely, never sharing or exposing them

  2. Credential Creation:

    • Create a credential document following the structure for the specific credential type
    • Ensure all required fields are present and properly formatted
    • Add appropriate metadata about the subject based on credential type
    • Add a status property if revocation capability is desired

  3. Proof Generation:

    • Create a cryptographic proof using the private key
    • Follow the cryptosuite’s specific algorithms for canonicalization and signing
    • Include all required proof properties including created timestamp

  4. Inscription:

    • Inscribe the complete credential (including proof) to Bitcoin
    • Use an appropriate inscription protocol compatible with BTCO DIDs
    • Record the inscription transaction ID and output index
    • Optionally verify the inscription was successful via a block explorer

§ 10.2 Key Management Considerations

Issuers MUST properly secure their private keys at all times:

  1. Use hardware security modules (HSMs) or secure enclaves when possible
  2. Never share private keys or include them in inscriptions
  3. Implement appropriate organizational controls for key access
  4. Consider key rotation strategies for long-term security

§ 10.3 Status Property Format

When creating a credential that supports revocation, include a status property with this format:

"credentialStatus": {
  "type": "BTCOStatusList2023",
  "statusListCredential": "did:btco:<sat-number>/<index>",
  "statusListIndex": "<integer>",
  "statusPurpose": "revocation"
}

Where:

§ 11. Resource Resolution

Verifiable Metadata can be resolved using BTCO DID Linked Resources resolution mechanisms:

  1. Direct Resolution:

    • Use the /meta endpoint to retrieve metadata about a resource
    • Example: did:btco:1954913028215432/0/meta

  2. Collection Resolution:

    • Resolve collection metadata to discover authenticated resources
    • Follow collection references to navigate related resources

  3. Presentation Resolution:

    • Inscribed presentations can be resolved directly via their DID URL
    • Example: did:btco:1954913028215432/1

§ 12. Status List Credential Format

BTCO Status List credentials provide a mechanism for issuers to revoke previously issued credentials.

§ 12.1 Status List Structure

A Status List credential follows this format:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://ordinals.plus/v1"
  ],
  "type": ["VerifiableCredential", "BTCOStatusList2023Credential"],
  "issuer": {
    "id": "did:btco:<sat-number>"
  },
  "validFrom": "<iso-8601-date>",
  "credentialSubject": {
    "id": "did:btco:<sat-number>/<index>",
    "type": "BTCOStatusList2023",
    "statusPurpose": "revocation",
    "encodedList": "<base64 encoded bitmap>"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "<iso-8601-date>",
    "verificationMethod": "<verification-method-id>",
    "proofPurpose": "assertionMethod",
    "proofValue": "<proof-value>"
  }
}

The encodedList property contains a base64-encoded bitmap where each bit represents the status of a credential. A value of 0 means the credential is still valid, while a value of 1 means the credential has been revoked.

§ 12.2 Status List Management

Issuers should follow these practices when managing status lists:

  1. Create a new status list credential before issuing credentials that reference it
  2. Maintain the status list by updating it when credentials need to be revoked
  3. Sign updated status lists with the same key used to issue the original credentials
  4. When updating a status list, inscribe the new version and reference it from now on
  5. Previous versions of status lists should remain available for historical verification

§ 12.3 Status Checking

Verifiers should check status as follows:

  1. Extract the statusListCredential and statusListIndex from the credential
  2. Resolve the status list credential using the BTCO DID URL
  3. Verify the status list credential’s proof
  4. Decode the encodedList bitmap
  5. Check the bit at position statusListIndex
  6. If the bit is 1, the credential has been revoked and should be rejected
NOTE

The revocation mechanism is an active area of research and development. The approach described here is preliminary and will evolve significantly as implementation experience grows and best practices emerge.

§ 13. Error Handling

Implementations MUST provide clear error messages for verification failures:

§ 13.1 Standard Error Codes

The following standard error codes SHOULD be used when reporting verification failures:

Error Code Description
MALFORMED_CREDENTIAL The credential document is not well-formed JSON or violates the schema
MISSING_REQUIRED_FIELD A required field is missing from the credential
INVALID_ISSUER The issuer DID cannot be resolved or is invalid
INVALID_SUBJECT The subject DID cannot be resolved or is invalid
EXPIRED_CREDENTIAL The credential has expired based on its validUntil property
NOT_YET_VALID The credential is not yet valid based on its validFrom property
PROOF_VERIFICATION_FAILED None of the proofs verify successfully
CRYPTOSUITE_NOT_SUPPORTED The cryptosuite used in the proof is not supported
REVOKED_CREDENTIAL The credential has been revoked according to its status
STATUS_LIST_UNREACHABLE The status list credential could not be retrieved
STATUS_CHECK_ERROR The status check failed for a different reason
TYPE_VALIDATION_FAILED The credential fails type-specific validation rules

§ 13.2 Error Response Format

When reporting errors, implementations SHOULD use this format:

{
  "error": {
    "code": "<ERROR_CODE>",
    "message": "Human-readable description of the error",
    "details": {
      "property": "specific property where the error occurred",
      "context": "Additional information about the error"
    }
  }
}

§ 13.3 Error Handling Guidance

Implementers SHOULD:

  1. Provide detailed error information without revealing sensitive data
  2. Log verification failures for diagnostic purposes
  3. Report multiple errors when possible rather than stopping at the first error
  4. Handle errors gracefully without crashing or hanging
  5. Implement appropriate fallback behavior when errors occur
  6. Consider security implications when reporting error details

§ 14. Test Vectors

For interoperability testing, the following test vectors are provided:

§ 14.1 Valid Credential Example

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://ordinals.plus/v1"
  ],
  "type": ["VerifiableCredential", "ResourceMetadataCredential"],
  "issuer": {
    "id": "did:btco:539864085599956"
  },
  "validFrom": "2024-03-21T12:00:00Z",
  "credentialSubject": {
    "id": "did:btco:1954913028215432/0",
    "type": "BTCOResource",
    "name": "Test Resource",
    "description": "A test resource for verification implementation",
    "properties": {
      "contentType": "image/png",
      "created": "2024-03-20T10:30:00Z",
      "creator": "Test Creator"
    }
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2024-03-21T12:00:00Z",
    "verificationMethod": "did:btco:539864085599956/0#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z5jxQLyq5DWRDCZKmNjjKLzZDwbPMVD8afRrYGECySMD9eZgAuKRrD2eiCQ87QEqPqk7f9JFDQptQSJbrXwwWobVB"
  }
}

§ 14.2 Invalid Credential Examples

The repository includes several invalid test vectors including:

  1. Credential with invalid signature
  2. Credential with expired validity period
  3. Credential with revoked status
  4. Credential with malformed fields
  5. Credential with missing required properties

Implementers should verify their implementations correctly reject these invalid credentials.

A complete set of test vectors is available in the vectors.md file.

§ 15. Implementation Considerations

  1. Privacy:

    • Consider the immutable nature of blockchain credentials
    • Minimize inclusion of sensitive or personal data
    • Support selective disclosure where appropriate

  2. Security:

    • Validate all cryptographic proofs
    • Ensure proper key management for issuers
    • Follow secure implementation practices

  3. Interoperability:

    • Maintain compatibility with W3C standards
    • Support standard Verifiable Credential libraries
    • Enable cross-platform verification

§ Operations

§ Issuance

To issue a BTCO Verifiable Credential:

  1. Create the credential JSON document following the schema
  2. Sign using the issuer’s BTCO DID verification method
  3. Inscribe the signed credential
  4. Reference the credential using the inscription’s BTCO DID

§ Verification

To verify a BTCO-VM credential:

  1. Resolve the credential’s BTCO DID
  2. Verify the DataIntegrityProof signature
  3. Validate the issuer’s BTCO DID control
  4. Check credential status (if applicable)
  5. Verify referenced inscriptions exist
  6. Validate against credential type-specific rules

§ Revocation

Credentials can be revoked by:

  1. Issuing a revocation credential
  2. Including the revoked credential’s ID
  3. Signing with the original issuer’s key
  4. Inscribing the revocation

§ Status Checking

Status can be checked by:

  1. Resolving the credential’s DID
  2. Checking for revocation credentials
  3. Validating the revocation signature
  4. Confirming revocation timestamp

§ Credential Types

BTCO-VM defines two primary credential types:

  1. Curated Collection Credential
  2. Verifiable Collectible

§ Curated Collection Credential

A credential type for establishing curated collections of ordinal inscriptions.

§ Example
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://ordinals.plus/v1"
  ],
  "type": ["VerifiableCredential", "CuratedCollectionCredential"],
  "issuer": {
    "id": "did:btco:539864085599956"
  },
  "validFrom": "2024-03-21T12:00:00Z",
  "credentialSubject": {
    "id": "did:btco:539864085599956/0",
    "type": "CuratedCollection",
    "name": "Example Collection",
    "description": "A curated collection of digital artifacts",
    "items": [
      "did:btco:1954913028215432/0",
      "did:btco:1923519999999991/0"
    ],
    "curatorDetails": {
      "name": "Curator Name",
      "statement": "Curatorial statement"
    }
  }
}
§ Required Properties
§ Optional Properties
§ Verification Rules
  1. All items in the collection must be valid BTCO DIDs
  2. The issuer must control the DID at time of issuance
  3. The collection must contain at least one item
  4. The name and description must not be empty

§ Verifiable Collectible Credential

A credential type for verifying authenticity and properties of individual inscriptions.

§ Example
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://ordinals.plus/v1"
  ],
  "type": ["VerifiableCredential", "VerifiableCollectible"],
  "issuer": {
    "id": "did:btco:539864085599956"
  },
  "validFrom": "2024-03-21T12:00:00Z",
  "credentialSubject": {
    "id": "did:btco:1954913028215432/0",
    "type": "Collectible",
    "title": "Artifact Title",
    "creator": "did:btco:539864085599956",
    "creationDate": "2024-03-21",
    "properties": {
      "medium": "Digital",
      "format": "image/png",
      "dimensions": "3000x3000"
    },
    "rights": {
      "license": "CC BY-SA 4.0",
      "terms": "https://creativecommons.org/licenses/by-sa/4.0/"
    }
  }
}
§ Required Properties
§ Optional Properties
§ Verification Rules
  1. The creator DID must be valid and resolvable
  2. The issuer must be the creator or authorized by the creator
  3. The creation date must not be in the future
  4. The referenced inscription must exist and match the properties

§ Security Considerations

§ Key Management

  1. Issuer Key Security

    • Protect private keys used for signing
    • Implement secure key storage
    • Use hardware security when possible
    • Regular key rotation recommended

  2. Verification Methods

    • Validate all cryptographic proofs
    • Check issuer DID control
    • Verify proof timestamps
    • Support multiple cryptosuites

§ Privacy Considerations

  1. Data Minimization

    • Include only necessary claims
    • Avoid sensitive personal data
    • Support selective disclosure
    • Consider data permanence

  2. Identifier Correlation

    • Use separate DIDs when appropriate
    • Minimize linkable identifiers
    • Consider privacy implications
    • Implement appropriate access controls

§ Network Security

  1. Bitcoin Network

    • Monitor for chain reorganizations
    • Wait for sufficient confirmations
    • Validate inscription ordering
    • Follow Bitcoin security best practices

  2. Inscription Security

    • Verify inscription ownership
    • Check inscription content integrity
    • Validate metadata signatures
    • Monitor for duplicate inscriptions

§ Terminology

BTCO Verifiable Credential:
A verifiable credential issued and managed using Bitcoin Ordinals and BTCO DIDs.
Curated Collection:
A collection of ordinal inscriptions authenticated by a curator through a verifiable credential.
Verifiable Collectible:
An ordinal inscription with verified authenticity and provenance through a verifiable credential.
DataIntegrityProof:
A cryptographic proof that ensures the integrity and authenticity of a credential.
Credential Status:
The current state of a credential, including whether it has been revoked.

§ Conformance

A conformant implementation MUST:

  1. Follow the W3C Verifiable Credentials Data Model 2.0
  2. Support the required cryptographic suites
  3. Implement proper DID resolution
  4. Validate credentials according to type-specific rules
  5. Handle revocation appropriately
  6. Process inscription metadata correctly
  7. Verify all cryptographic proofs
  8. Check issuer control of DIDs
  9. Support selective disclosure when possible
  10. Implement proper error handling

§ Test Suite

Implementations SHOULD provide test vectors for:

  1. Credential issuance
  2. Signature verification
  3. Revocation handling
  4. DID resolution
  5. Type-specific validation

§ References

  1. W3C Verifiable Credentials Data Model 2.0
  2. BTCO DID Method Specification
  3. BTCO DID Linked Resources
  4. Bitcoin Ordinals Protocol

§ Version Changelog

§ v0.2.0 (Current)

§ v0.1.0 (2025-02-18)

✕
Table of Contents ✕