Skip to content

feat(explorer-api): write a contract class artifact at most once - #36

Merged
alejoamiras merged 1 commit into
mainfrom
feat/artifact-write-once
Nov 18, 2026
Merged

alejoamiras merged 1 commit into
mainfrom
feat/artifact-write-once

Conversation

@alejoamiras

Copy link
Copy Markdown
Collaborator

Stacked on #35.

What

  • Artifact writes read the class from Postgres (readClassWithArtifact), never from the cache.
  • addArtifactData writes only while the class has no artifact (artifact_json IS NULL … RETURNING), so of concurrent uploads exactly one is written.
  • storeArtifactIfAbsent stores a verified artifact that way and returns the row as stored. Only the request that wrote names the class's public calls and refreshes the with-artifact cache entry, from that re-read row.
  • The class and standard routes answer 201 when they wrote and 200 with the stored row otherwise.
  • Deployment verification:
    • checks an uploaded artifact first;
    • verifies the address against the stored artifact when there is one, otherwise against the upload;
    • stores a first artifact only after the address check passes;
    • never replaces a stored artifact.
  • A missing class answers 404 through NotFoundError.

Tests

services/explorer-api/tests/integration/contract-class-artifact.integration.test.ts (real Postgres and Redis):

  • an artifact upload reads the class from the database, not the cache
  • concurrent artifact uploads keep the first written one: both requests are held after their first read (support/gate.ts)
  • deployment verification:
    • a deployment verification leaves a stored artifact unchanged
    • a deployment verification without an artifact uses the stored one
  • deployment verification storing a first artifact:
    • a refused deployment verification stores nothing
    • a deployment verification stores a first artifact once it is verified
    • a deployment verification refuses an artifact of another class

Verify

yarn build:packages && yarn build
yarn lint && git diff --exit-code
yarn test
yarn test:integration

🤖 Generated with Claude Code

Artifact writes read the class from Postgres (readClassWithArtifact),
never from the cache, and addArtifactData writes only while the class
has no artifact (artifact_json IS NULL ... RETURNING), so of concurrent
uploads exactly one is written. storeArtifactIfAbsent stores a verified
artifact that way and returns the row as stored; only the request that
wrote names the class's public calls and refreshes the with-artifact
cache entry, from that re-read row.

The class and standard routes answer 201 when they wrote and 200 with
the stored row otherwise. Deployment verification checks an uploaded
artifact first, verifies the address against the stored artifact when
there is one (the upload otherwise), and stores a first artifact only
after the address check passes; it never replaces a stored artifact.
A missing class answers 404 through NotFoundError.

Tests (integration, real Postgres and Redis): a stale cache entry and a
stored artifact, concurrent uploads held after their first read, a
deployment verification with and without an upload against a stored
artifact, and, in their own block, a refused deployment verification,
a first artifact stored by one, and another class's artifact refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@alejoamiras
alejoamiras force-pushed the feat/artifact-write-once branch from 6a0ca36 to f57a153 Compare November 18, 2026 15:56
@alejoamiras
alejoamiras merged commit df2e2cf into main Nov 18, 2026
19 checks passed
@alejoamiras
alejoamiras deleted the feat/artifact-write-once branch November 18, 2026 15:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant