Merge pull request #512 from bsv-blockchain/fix/uora-anchor-exact-reader

fix(overlay-topics): read the uora anchor output exactly

Author: ty-everett

docs/packages/overlays/overlay-topics.md

@@ -4,7 +4,7 @@ title: '@bsv/overlay-topics'
 kind: package
 domain: overlays
 npm: '@bsv/overlay-topics'
-version: '1.7.1'
+version: '1.7.2'
 last_updated: '2026-08-27'
 last_verified: '2026-08-27'
 review_cadence_days: 30
@@ -207,3 +207,18 @@ const admittance = await manager.identifyAdmissibleOutputs(beef, [])
 - [API reference (TypeDoc)](https://bsv-blockchain.github.io/ts-stack/api/overlay-topics/)
 - [Source on GitHub](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/topics)
 - [npm](https://www.npmjs.com/package/@bsv/overlay-topics)
+
+## UORA v3 reader compatibility
+
+Version 1.7.2 aligns `readUoraAnchor` and `tm_uora_dpp` with the UORA v3 format:
+a 33-byte compressed locking key, eight fields, exactly four `OP_2DROP`
+instructions, and printable UTF-8 text without C0/C1 controls or DEL. Valid
+anchors keep the same bytes, signing preimage, topic identifier and admission
+result. Unicode text remains supported; no new normalization is applied.
+
+Coordinate reader upgrades across nodes serving `tm_uora_dpp`. Audit any
+previously indexed nonconforming outputs before rebuilding that topic, because
+older readers may have admitted inputs that the format does not permit.
+Repository fixtures establish format compatibility; they do not establish an
+inventory of every deployed or historical anchor. Other topics, lookup query
+shapes and persisted schemas are unchanged.

docs/reference/package-api-migrations.md

@@ -61,7 +61,7 @@ authorized release action.
 | overlays | `@bsv/overlay` | `2.3.1` | node-library | node-cjs, node-esm | node | `>=22` | [packages/overlays/overlay](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay) |
 | overlays | `@bsv/overlay-discovery-services` | `2.2.1` | node-library | node-cjs, node-esm | node | `>=22` | [packages/overlays/overlay-discovery-services](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay-discovery-services) |
 | overlays | `@bsv/overlay-express` | `2.6.1` | node-library | node-cjs, node-esm | node | `>=22` | [packages/overlays/overlay-express](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay-express) |
-| overlays | `@bsv/overlay-topics` | `1.7.1` | node-library | node-esm | node | `>=22` | [packages/overlays/topics](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/topics) |
+| overlays | `@bsv/overlay-topics` | `1.7.2` | node-library | node-esm | node | `>=22` | [packages/overlays/topics](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/topics) |
 | sdk | `@bsv/sdk` | `2.6.0` | browser-library | browser-bundler, browser-esm, node-cjs, node-esm, umd-global | browser, node, umd | `>=22` | [packages/sdk](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/sdk) |
 | sdk | `@bsv/verifast` | `0.3.5` | wasm-library | browser-bundler, browser-esm, node-cjs, node-esm, umd-global, wasm-worker | browser, node, umd, wasm, worker | `>=22` | [packages/verifast](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/verifast) |
 | wallet | `@bsv/btms` | `1.2.2` | node-library | node-cjs, node-esm | node | `>=22` | [packages/wallet/btms](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/btms) |

docs/reference/stack-facts.md

@@ -147,8 +147,8 @@
       "name": "@bsv/overlay-topics",
       "publishedVersion": "1.6.10",
       "releaseType": "minor",
-      "summary": "Adds persistent first-writer reservations for UMP presentation and recovery hashes, aborts provisional claims after strict broadcast failure, keeps confirmed owners protected until successor indexing, retries transient initialization, marks one-time legacy bootstrap, and returns the newest bounded legacy candidates for verified lineage or an operator pin. It also retains the collection-index resilience and opt-in repair controls from the prior candidate. Standardizes first-party author metadata on the current BSV Association name.",
-      "migration": "Existing topic and lookup identifiers remain unchanged. Production UMP overlays must give UMPTopicManager and the UMP lookup service Mongo-backed stores that use the same database, then roll out before updated wallet clients; the no-argument manager is bounded but intended only for isolated single-process use. The reservation and bootstrap-marker collections are additive and initialize from currently indexed UMP UTXOs; take a MongoDB backup before rollout. Legacy ambiguous rows remain visible and can be resolved with WAB pinning rather than deleted."
+      "summary": "Adds persistent first-writer reservations for UMP presentation and recovery hashes, aborts provisional claims after strict broadcast failure, keeps confirmed owners protected until successor indexing, retries transient initialization, marks one-time legacy bootstrap, and returns the newest bounded legacy candidates for verified lineage or an operator pin. It also retains the collection-index resilience and opt-in repair controls from the prior candidate. Standardizes first-party author metadata on the current BSV Association name. Aligns the UORA v3 reader with the versioned format, including compressed locking keys, exact drop tails, and printable UTF-8 fields.",
+      "migration": "Existing topic and lookup identifiers remain unchanged. Production UMP overlays must give UMPTopicManager and the UMP lookup service Mongo-backed stores that use the same database, then roll out before updated wallet clients; the no-argument manager is bounded but intended only for isolated single-process use. The reservation and bootstrap-marker collections are additive and initialize from currently indexed UMP UTXOs; take a MongoDB backup before rollout. Legacy ambiguous rows remain visible and can be resolved with WAB pinning rather than deleted. Valid uora-anchor-v3 outputs retain their bytes, signatures, and admission result. Readers now reject nonconforming key, tail, and text shapes. Coordinate reader upgrades across nodes serving tm_uora_dpp and audit any previously indexed nonconforming outputs before rebuilding that topic. No wire prefix, export, or persisted schema changes are required."
     },
     {
       "name": "@bsv/paymail",

governance/package-release-notes.json

@@ -321,7 +321,7 @@
     "@bsv/overlay": "2.3.1",
     "@bsv/overlay-discovery-services": "2.2.1",
     "@bsv/overlay-express": "2.6.1",
-    "@bsv/overlay-topics": "1.7.1",
+    "@bsv/overlay-topics": "1.7.2",
     "@bsv/sdk": "2.6.0",
     "@bsv/verifast": "0.3.5",
     "@bsv/btms": "1.2.2",

governance/repository-health/baselines.json

@@ -38,7 +38,7 @@ All notable changes to this project will be documented in this file. The format
 
 ### Fixed
 
-- (Document bugs that were fixed since the last release.)
+- Version 1.7.2 aligns `tm_uora_dpp` with the versioned UORA v3 format: compressed locking keys, exact drop tails, and printable UTF-8 fields. Valid anchors retain their bytes and admission result. The shared reference fixture covers key and tail validation. Coordinate reader upgrades and audit previously indexed nonconforming outputs before rebuilding the topic; this change does not claim a complete inventory of historical anchors.
 
 ### Security
 

packages/overlays/topics/CHANGELOG.md

@@ -197,3 +197,18 @@ ESM consumer.
 ## License
 
 Open BSV License — see [LICENSE.txt](./LICENSE.txt).
+
+## UORA v3 reader compatibility
+
+Version 1.7.2 aligns `readUoraAnchor` and `tm_uora_dpp` with the UORA v3 format:
+a 33-byte compressed locking key, eight fields, exactly four `OP_2DROP`
+instructions, and printable UTF-8 text without C0/C1 controls or DEL. Valid
+anchors keep the same bytes, signing preimage, topic identifier and admission
+result. Unicode text remains supported; no new normalization is applied.
+
+Coordinate reader upgrades across nodes serving `tm_uora_dpp`. Audit any
+previously indexed nonconforming outputs before rebuilding that topic, because
+older readers may have admitted inputs that the format does not permit.
+Repository fixtures establish format compatibility; they do not establish an
+inventory of every deployed or historical anchor. Other topics, lookup query
+shapes and persisted schemas are unchanged.

packages/overlays/topics/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/overlay-topics",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "sideEffects": false,
   "engines": {
     "node": ">=22"

packages/overlays/topics/package.json

@@ -529,6 +529,48 @@ describe('the boundary between the subject and the type', () => {
   })
 })
 
+describe('UORA v3 key and drop-tail validation', () => {
+  const F = ANCHOR_V3_FIXTURE
+  const manager = new UoraDppTopicManager()
+
+  it('refuses the 65-byte uncompressed locking push', async () => {
+    const script = LockingScript.fromHex(F.uncompressedKey)
+    expect(() => readUoraAnchor(script)).toThrow(/locking key push is not 33 bytes/)
+    const admitted = await manager.identifyAdmissibleOutputs(txWith(script).toBEEF(), [])
+    expect(admitted.outputsToAdmit).toEqual([])
+  })
+
+  it('refuses a short, mixed or trailing drop tail', async () => {
+    expect(F.malformedTail).toHaveLength(3)
+    for (const hex of F.malformedTail) {
+      const script = LockingScript.fromHex(hex)
+      expect(() => readUoraAnchor(script)).toThrow(/drop tail/)
+      const admitted = await manager.identifyAdmissibleOutputs(txWith(script).toBEEF(), [])
+      expect(admitted.outputsToAdmit).toEqual([])
+    }
+  })
+
+  it('names what is wrong with a script that is not this shape at all', () => {
+    const key = { op: 33, data: Utils.toArray(SERVICE_KEY, 'hex') }
+    const checksig = { op: 0xac }
+    expect(() => readUoraAnchor(new LockingScript([]))).toThrow(/locking key push is not 33 bytes/)
+    expect(() => readUoraAnchor(new LockingScript([key, { op: 0x6a }]))).toThrow(/no OP_CHECKSIG/)
+    expect(() => readUoraAnchor(new LockingScript([key, checksig, { op: 0x6a }]))).toThrow(
+      /opcode 0x6a where a field should be/
+    )
+    // 33 bytes in the compressed shape that are not a point on the curve.
+    const notAPoint = { op: 33, data: Utils.toArray(`02${'00'.repeat(32)}`, 'hex') }
+    expect(() => readUoraAnchor(new LockingScript([notAPoint, checksig]))).toThrow(
+      /not a valid public key/
+    )
+    // OP_0 and a small-integer opcode read as the bytes they push, and the tail
+    // is exact for two fields, so this fails on the count and nothing earlier.
+    expect(() =>
+      readUoraAnchor(new LockingScript([key, checksig, { op: 0 }, { op: 0x51 }, { op: 0x6d }]))
+    ).toThrow(/expected 7 fields and a signature, found 2/)
+  })
+})
+
 describe('what readUoraAnchor refuses', () => {
   const manager = new UoraDppTopicManager()
 
@@ -551,6 +593,25 @@ describe('what readUoraAnchor refuses', () => {
     )
   }
 
+  it('preserves printable Unicode and exact field length boundaries', async () => {
+    const unicode = claim({ subject: '产品/café/🌱', uoraType: 'Origine é' })
+    const bounded = claim({
+      attestationId: 'i'.repeat(256),
+      subject: 's'.repeat(512),
+      uoraType: 't'.repeat(64)
+    })
+    for (const expected of [unicode, bounded]) {
+      const script = await anchorScript(expected)
+      const { anchor, fields } = readUoraAnchor(script)
+      expect(anchor).toMatchObject(expected)
+      await expect(
+        assertAnchorSignature(fields, anchor.anchoredBy, anchor.attestationId)
+      ).resolves.toBeUndefined()
+      const result = await manager.identifyAdmissibleOutputs(txWith(script).toBEEF(), [])
+      expect(result.outputsToAdmit).toEqual([0])
+    }
+  })
+
   it('refuses an output that is not this many fields', async () => {
     // Two fields and no signature. The count is checked before anything is
     // read, because a short output has no field 6 to attribute it by and
@@ -604,6 +665,25 @@ describe('what readUoraAnchor refuses', () => {
     }
   })
 
+  it('refuses a field carrying a control character', async () => {
+    // Well-formed UTF-8 that round-trips, and still not text the format admits:
+    // a C0 control, 0x7F and a C1 control are refused, as the reference reader
+    // refuses them, so an index never carries a subject or a type it cannot show.
+    for (const code of [0x07, 0x7f, 0x85]) {
+      const one = claim()
+      const script = await scriptWithFields([
+        UORA_ANCHOR_PREFIX,
+        one.digest,
+        one.attestationId,
+        one.issuer,
+        one.subject,
+        `${one.uoraType}${String.fromCharCode(code)}`,
+        one.anchoredBy
+      ])
+      expect(() => readUoraAnchor(script)).toThrow(/control character/)
+    }
+  })
+
   it('refuses a field that is not valid UTF-8 text', async () => {
     // Invalid continuation byte: toUTF8 either throws or produces a string that
     // does not re-encode to the same bytes. Either path is "not UTF-8".
@@ -702,9 +782,9 @@ describe('UoraDppLookupService, at its edges', () => {
       /valid query is required/
     )
     // `query` omitted is treated as `{}`, not as a missing question object.
-    await expect(
-      service.lookup({ service: 'ls_uora_dpp' } as LookupQuestion)
-    ).rejects.toThrow(/issuer, issuerKey, subject, attestationId or digest/)
+    await expect(service.lookup({ service: 'ls_uora_dpp' } as LookupQuestion)).rejects.toThrow(
+      /issuer, issuerKey, subject, attestationId or digest/
+    )
     await expect(
       service.lookup({ service: 'ls_uora_dpp', query: { issuer: '' } } as LookupQuestion)
     ).rejects.toThrow(/issuer, issuerKey, subject, attestationId or digest/)