OBIS-0003: Attribution Tag Data Model and Exchange Format#

Abstract#

This document specifies a portable data model and exchange format for attribution tags: claims that bind a blockchain address to an actor, with structured provenance and a first-class revocation mechanism. The design draws on the GraphSense TagPack approach of bundling tags with shared header metadata, but commits to several concrete improvements: addresses are identified using the CAIP-10 scheme rather than chain-shorthand strings; category and abuse values are drawn from the controlled vocabularies of OBIS-0002; provenance is structured and W3C PROV-aligned rather than a single free-form source string; and revocation is a first-class operation.

1. Introduction#

Attribution, the binding of a pseudonymous blockchain address to a real-world actor, is the core analytical activity in investigations, supervision, and research on blockchain data. Each platform working in this space today maintains its own representation of the same underlying claim. Identical concepts carry different names, and attributions produced in one ecosystem are difficult to verify or reuse in another.

The GraphSense TagPack format is the most widely-used open format for sharing attribution data in the investigations community. It represents attribution as a list of tags, each binding an address to a label with a source and (optionally) a category and abuse type. OBIS-0003 builds on the same idea (a bundle of attribution claims with shared metadata) and tightens the parts of the model that matter most for cross-organisation exchange.

This document does not prescribe how attributions are produced. It specifies how they are represented when exchanged.

2. Scope#

OBIS-0003 covers:

• the structure of an individual attribution claim (an “attribution tag”) associated with a single blockchain address;
• the structure of a bundle of tags with shared header metadata;
• provenance and revocation metadata associated with tags;
• the canonical wire serialization.

OBIS-0003 does not cover:

• the controlled vocabularies for actor and abuse types (specified in OBIS-0002);
• transmittal protocols (push, pull, query); only the data format is normative.

3. Terminology#

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

• Address. A unit of value receipt or control on a blockchain ledger, identified per §6.
• Actor. A real-world participant (e.g., service, organisation, natural person) to which an address may be attributed.
• Attribution Tag (or “tag”). A single claim binding one address to an actor, with provenance.
• Tag Bundle. A set of tags exchanged together, carrying shared header metadata.
• Attributor. The organisation or individual asserting the tag.
• Category. A value from the OBIS Actor Type Vocabulary (OBIS-0002 §6).
• Abuse. A value from the OBIS Abuse Type Vocabulary (OBIS-0002 §7).

4. Related work#

4.1 GraphSense TagPacks#

GraphSense TagPacks are the primary inspiration. A TagPack is a YAML file containing a header (title, creator, default currency, default source, etc.) and a list of tag records (address, label, source, optional category, abuse, confidence). Header fields cascade as defaults to contained tags. TagPacks are identified by a Git URI; individual tags are identified by the triple (address, label, source). OBIS-0003 reuses the bundle-with-header idea and the field-cascading convention, and diverges on identifiers, provenance structure, and revocation. It does not adopt the TagPack confidence field; assessing the credibility of a tag is the consumer’s responsibility, informed by the structured provenance carried with the tag.

4.2 INTERPOL DW-VA-Taxonomy#

The category and abuse fields in GraphSense TagPacks draw from the INTERPOL DW-VA-Taxonomy. OBIS-0003 references this work via OBIS-0002, which provides the controlled vocabularies that OBIS attribution tags use.

4.3 W3C PROV Data Model#

The W3C PROV Data Model is the established framework for representing provenance. OBIS-0003 aligns its provenance block with PROV vocabulary (Entity, Agent, Activity, derivation), without requiring full RDF serialization. A future revision may define a normative PROV-O mapping.

4.4 FATF Travel Rule and IVMS101#

The FATF Recommendation 16 (the “Travel Rule”) and the associated IVMS101 data standard specify how originator and beneficiary identity information accompanies VASP-to-VASP transfers. IVMS101 is a transmittal standard, not an attribution standard: it carries identity disclosed by counterparties at transfer time, rather than third-party-asserted bindings of addresses to actors. The two formats are complementary and operate on disjoint segments of the regulatory workflow. OBIS-0003 does not subsume IVMS101 and does not depend on it.

4.5 Closed commercial formats#

The major commercial blockchain analytics vendors (Chainalysis, TRM Labs, Elliptic) each maintain proprietary attribution-tagging formats. These are not publicly redistributable and vary in field structure. They are noted because operational interoperability with these vendors requires bidirectional mapping. They cannot serve as the basis for an open standard.

5. Design principles#

OBIS-0003 commits to the following principles, which together distinguish it from the TagPack format it builds on:

1. CAIP-10 addresses on the wire. Chain-shorthand fields (e.g., GraphSense currency: BTC) are acceptable internally, but exchanged records use the CAIP-10 fully-qualified address form. Disambiguation across chains is a first-class concern, not a convention.
2. Controlled vocabularies for categorisation. category and abuse values are drawn from the OBIS-0002 vocabularies, not free-form text. Extensions follow the x- prefix rule (OBIS-0002 §8).
3. Structured provenance. Provenance is a typed block (attributor, method, software, derived_from) aligned with W3C PROV, rather than a single source URL. The TagPack source field is preserved as a separate human-readable back-link, distinct from provenance.
4. First-class revocation. Revocation is a typed operation that produces a record. Receivers MUST honour revocations and MUST NOT silently propagate revoked tags.
5. Address-scoped tags. A tag binds exactly one address to an actor. The tag format does not encode anything about other addresses; any extension of an attribution beyond the named address is the consumer’s responsibility and is out of scope.

6. Identifiers#

6.1 Chains and addresses#

Chains use CAIP-2: <namespace>:<reference>. Addresses use CAIP-10: <chain_id>:<account>. Examples: eip155:1 (Ethereum mainnet), bip122:000000000019d6689c085ae165831e93:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa (a Bitcoin mainnet address).

Implementations MAY accept chain-shorthand on input (e.g., BTC, ETH); they MUST emit CAIP-10 on exchange.

6.2 Tags and bundles#

A tag bundle is identified by a URI, typically a Git URL of the canonical source file (e.g., https://github.com/<org>/<repo>/blob/main/bundles/<name>.json). A tag within a bundle is identified by the triple (address, actor_label, attributor).

7. Data model#

7.1 Attribution Tag#

A tag MUST contain:

A tag applies to exactly the address named in its address field. Any propagation to other addresses is the consumer’s responsibility and is out of scope.

7.2 Tag Bundle#

A tag bundle bundles tags with shared header defaults.

Header inheritance is explicit: the defaults block applies only to fields a tag does not specify. There is no implicit per-file inheritance beyond the defaults block.

8. Provenance#

Every tag carries a provenance block aligned with the W3C PROV Data Model. The block is JSON-native and does not require RDF serialization.

The derived_from field carries lineage when records are merged or refined across organisations. Implementations SHOULD populate derived_from whenever a tag’s content depends on another exchanged record.

9. Versioning and revocation#

9.1 Versioning#

Tag bundles are versioned by re-publication. A new bundle MAY supersede a prior bundle by carrying a supersedes field in its header pointing to the prior bundle’s URI. Receivers SHOULD treat the most recent bundle from a given creator as authoritative for the tags it contains.

9.2 Revocation#

A revocation is a first-class operation that produces a record. A revocation record contains:

Revocations MAY be published within a bundle (in the revocations array of the header) or as a standalone bundle whose tags array is empty.

Recipients of a revocation MUST honour it: the named tags MUST be marked as revoked and MUST NOT be silently propagated to downstream consumers without the revocation marker.

Revoked records MUST NOT be deleted from any party’s holdings. They remain available with their revocation marked, in order to preserve the lineage of any downstream tags that relied on them.

10. Serialization#

The canonical exchange serialization is JSON. YAML MAY be used internally (for parity with GraphSense TagPack files); on the wire between organisations, JSON is normative.

Example bundle:

{
  "title": "Example sanctioned-mixer bundle",
  "creator": "https://attributor.example/",
  "created": "2026-04-12T10:24:00Z",
  "defaults": {
    "category": "service.mixer",
    "abuse": "prohibited.sanctions-evasion",
    "provenance": {
      "attributor": "https://attributor.example/",
      "method": "regulatory_designation",
      "software": {"name": "example-suite", "version": "3.2.1"}
    }
  },
  "tags": [
    {
      "address": "bip122:000000000019d6689c085ae165831e93:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "actor_label": "mixer-x",
      "source": "https://home.treasury.gov/news/press-releases/example",
      "valid_from": "2024-08-01",
      "provenance": {
        "attributor": "https://attributor.example/",
        "created_at": "2026-04-12T10:24:00Z",
        "method": "regulatory_designation",
        "software": {"name": "example-suite", "version": "3.2.1"}
      }
    }
  ]
}

The defaults block specifies category, abuse, and shared provenance fields that the contained tag inherits; the tag carries only the fields specific to it.

11. Privacy and security considerations#

Attribution data is sensitive personal data in many jurisdictions. Implementations MUST apply at least the following:

1. Attribution of an address to an actor of category party.individual (OBIS-0002) is subject to applicable data protection law. Implementations MUST restrict storage, exchange, and onward disclosure of such attributions to recipients with a lawful basis.
2. Purpose limitation: attribution data collected for investigations is exchanged only with parties whose intended use is consistent with that purpose.
3. The source field MUST NOT point to a resource disclosing personal data beyond what the attribution itself reveals (e.g., a link to a leaked document containing additional personal data is not appropriate evidence).
4. Tags carrying abuse values prohibited.csam or prohibited.terror-financing (OBIS-0002 §7) carry elevated handling obligations and SHOULD be exchanged only with appropriately accredited recipients.
5. The revocation mechanism (§9.2) MUST be honoured. An attribution shown to be erroneous is not silently propagated.

12. Conformance#

An implementation is conformant with this document if, when exchanging attribution data with another party:

1. it produces records using the field names, types, and value enumerations defined here;
2. it emits CAIP-10 identifiers for addresses on exchange;
3. it draws category and abuse values from the OBIS-0002 vocabularies;
4. it carries provenance (§8) on every tag record;
5. it honours revocation (§9.2); and
6. it applies the privacy provisions of §11 to party.individual-category attributions.

Conformance does not require an implementation to produce tags. A read-only consumer is conformant if it preserves the above when re-emitting received records.

13. Open issues#

• PROV-O / JSON-LD context. A normative @context mapping to RDF terms is desirable for full PROV interoperability and is deferred to a future revision.
• Bundle signing. Cryptographic signing of bundles and revocations is desirable for non-repudiation and is deferred.

References#

• IETF RFC 2119, Key words for use in RFCs to Indicate Requirement Levels.
• ChainAgnostic Standards Alliance, CAIP-2, Blockchain ID Specification.
• ChainAgnostic Standards Alliance, CAIP-10, Account ID Specification.
• W3C, PROV Data Model.
• GraphSense, TagPacks Wiki.
• INTERPOL Innovation Centre, Darkweb and Virtual Assets Taxonomy.
• FATF, Recommendation 16 (Travel Rule).
• InterVASP, IVMS101 Data Standard.
• OBIS-0001, OBIS Document Lifecycle.
• OBIS-0002, Shared Taxonomies for Blockchain Intelligence.