Reference · Evidence ledger · v1.2

What DotLinQ keeps as evidence, and exactly what it guarantees

When a load tender, status message or invoice is disputed, you need to show what your partner sent, when it arrived, and that nobody has changed it since. This reference states what the DotLinQ evidence ledger records, what its identifiers and timestamps mean, how duplicates, corrections and deletions are stored, and what it does not guarantee. It describes shipped behaviour only.

Version
1.2 ·
Applies to
Platform release fe6db6c
Owner
DotLinQ engineering

Cite as: DotLinQ, “Evidence ledger”, v1.2, 16 Nov 2026, https://www.dotlinq.com/evidence

Watch first · 3 minutes

One load, two claims, and the evidence that settles both

A carrier is fined for a late delivery on its 214 status message and charged back on its 210 invoice, both “never received”. Follow how DotLinQ records, fingerprints and locks every AS2 exchange, and how that record settles the dispute. The reference below states each guarantee precisely.

Story and companies are fictional. Behaviour shown is the shipped product.

On this page
  1. 1Summary
  2. 2What an evidence row contains
  3. 3Identifiers and timestamps
  4. 4Files and hashes
  5. 5Nothing acknowledged without its row
  6. 6Rows are never changed or removed
  7. 7Corrections and changes
  8. 8Duplicates
  9. 9Deletions
  10. 10Reading the ledger from outside
  11. 11What is not guaranteed
  12. 12Revision history

Section 1

Summary#

Shippers, carriers, 3PLs and retailers settle chargebacks, detention claims and missed-appointment disputes on the documents they exchanged. For every AS2 exchange, DotLinQ keeps a record that you, your trading partner or an independent evidence provider can verify without relying on our word.

Guarantees at a glance
GuaranteeEnforced byDetail
The bytes received are hashed (SHA-256) at receipt and stored write-onceAzure immutability policy (Locked)section 4
A file is only returned if it still matches the hash taken at receiptApplication, on every readsection 4
No MDN is returned, and nothing is sent, unless its evidence row is storedApplication, single database transactionsection 5
Evidence rows cannot be updated, deleted or truncatedDatabase triggerssection 6
Every change to a tracked record keeps its prior and new value, who and whyDatabase triggers, same transactionsection 7
Repeated messages are kept and linked to the first copy, not reprocessedApplicationsection 8
Deleting a customer keeps the ledger and the write-once filesApplication and Azure policysection 9
Outside readers see one workspace, with every read and access change loggedApplication and database triggerssection 10

“Enforced by the database” or “by Azure” means the rule holds below the application, for every writer. The boundaries of each guarantee are stated in section 11.

What a DotLinQ record proves, and what it does not

DotLinQ is a source of evidence. A DotLinQ record proves what crossed DotLinQ, byte for byte: what was sent or received, between whom, when, and that it has not changed since. It does not decide what happened in the world behind the message, such as whether a load was really delivered at the time a 214 states. That judgement belongs to whoever weighs records from several independent systems together, such as an auditor or an evidence platform. The cleaner each source, the stronger that judgement.

Section 2

What an evidence row contains#

The ledger is an ordered series of rows, one series per customer workspace. Each row records one fact and has a kind. A later fact never edits an earlier row: it is a new row that points at the earlier one through refersToId.

Kinds of evidence row
KindWritten when
ArrivalAn AS2 message is received, or is about to be sent. One per exchange. Never updated.
IdentifiersThe file has been validated. Holds the ISA, GS and ST identifiers copied from the interchange as validated.
MdnAn MDN (signed receipt) is stored after the Arrival.
DuplicateA message arrives with an AS2 Message-ID already received, or a repeated ISA13 is seen. Points at the first Arrival.
CorrectionA file is reprocessed. Points at the Arrival, which stays as written.
ChangeA tracked value on an exchange, transaction or control-number record changed. Holds prior and new values.
DeletionA tracked record was deleted, a deletion of an evidence file was refused, or a workspace was purged.

Fields a row can carry. A field that does not apply to the row’s kind is empty.

Fields of an evidence row
GroupFields
Positionid sequence kind refersToId fileExchangeId direction
TimereceivedAtUtc receivedClock storedAtUtc
AS2 envelopemessageId as2From as2To mic disposition fileName
X12 identifiersisa05 isa06 isa07 isa08 isa13 gs02 gs03 gs06 st02
FilesrawSha256 decryptedSha256 mdnSha256 fileStore rawVersionId decryptedVersionId mdnVersionId filesImmutableUntilUtc, and the storage key of each file
ChangesourceTable sourceId priorValues newValues
Who and whyactor note

Section 3

Identifiers and timestamps#

Meaning of identifiers and timestamps
FieldMeaning
idUnique id of the row. For rows sent by the AS2 gateway the gateway chooses it, so a retried call cannot store the same fact twice.
sequencePosition in the workspace’s ledger, assigned by the database under a per-workspace lock held until commit. Sequence order is commit order: a lower number never appears after a reader has passed it.
refersToIdThe earlier row this row is about.
direction0 inbound, 1 outbound. Stored when the row is written; a later change to the exchange does not alter it.
messageId as2From as2ToThe AS2 Message-ID, AS2-From and AS2-To headers. Recorded on the Arrival at receipt and never updated.
receivedAtUtcWhen the HTTP request reached the DotLinQ AS2 gateway, taken before the body was read. Present on Arrival and Duplicate rows. This is not the date inside the ISA segment.
receivedClockThe clock that set receivedAtUtc, named on the row: as2-gateway system clock (UTC), host <host name>
storedAtUtcWhen the row was written, by the control-plane server clock.
isa05–isa08 isa13 gs02 gs03 gs06 st02Sender and receiver qualifiers and IDs, and the interchange, group and transaction-set control numbers. Copied onto the Identifiers row from the interchange as validated; a later edit of the control-number log does not change them.
filesImmutableUntilUtcThe earliest date until which this row’s files cannot be deleted or overwritten.

All times are UTC.

Section 4

Enforced by Azure immutability policy and application

Files and hashes#

For each AS2 message DotLinQ keeps the following files, and records the SHA-256 (hex) of each on the row.

Files kept per AS2 message
FileHash field
The bytes exactly as received on the HTTP request, hashed at receiptrawSha256
The payload as it came out of decryption and signature checking, not re-serializeddecryptedSha256
The MDN sent or received, including an error MDN when a message is refusedmdnSha256, with mic and disposition
The body of a repeated message (section 8)On the Duplicate row

Write-once storage. Each of these files is written to a dedicated evidence container in Azure Blob Storage with version-level immutability (WORM). The stored version is placed under a Locked time-based retention policy. The file counts as stored only after DotLinQ reads the version back and Azure reports it Locked until the expected date; until then nothing is acknowledged (section 5). While the policy is in effect, Azure refuses to delete the version, no one can remove or shorten the policy (DotLinQ included), and writing the same name again creates a new version rather than changing the stored one.

Retention. The retention period is fixed in each file’s policy when the file is stored, and its end date is on the row as filesImmutableUntilUtc. On the environment customers use today it is 30 days. The production environment is configured for 365 days.

Hash-checked reads. A read fetches exactly the version recorded on the row and compares its SHA-256 with the hash on the row. If they differ, the read is refused (HTTP 409) and no bytes are returned.

Evidence files are separate from the working copy that routing moves through the File Bank. Evidence never points at the working copy.

Section 5

Enforced by Application, single database transaction

Nothing is acknowledged without its evidence row#

  • The exchange and its Arrival row are written in one database transaction, before an MDN is returned or sent.
  • If that write fails after retries, the partner receives HTTP 503 and no MDN, and sends the message again.
  • A repeated Message-ID is acknowledged only after its Duplicate row and the repeated body are stored. Otherwise the partner receives HTTP 503.
  • An error MDN is sent only after the refused message’s raw bytes, the error MDN and the Arrival row are stored.
  • Outbound follows the same rule: the exchange and its Arrival row (raw and plain hash, Message-ID, AS2-From, AS2-To) are stored in one transaction before the file is posted to the partner. If that write fails, nothing is sent.

Section 6

Enforced by Database triggers

Rows are never changed or removed#

The database refuses UPDATE, DELETE and TRUNCATE on the evidence table, the read log and the access log (SQLSTATE P0E01), for every writer, including SQL entered by hand.

Disclosed exception

When the direction column was added on 15 November 2026, rows written before it existed were filled once, by a migration, with the value the API was already returning for them. That is the only time ledger rows have been updated.

Section 7

Enforced by Database triggers, same transaction

Corrections and changes#

Exchange, transaction and control-number records can change after receipt: status, MDN outcome, reprocess, repeated control numbers. When a tracked value changes, a database trigger writes a Change row in the same transaction as the change, so the change cannot be committed without it.

Records and fields tracked by Change rows
RecordTracked fields
File exchangesStatus, MDN status, file name, size, content hash, Message-ID, MIC, disposition, MDN time, file keys, error, timestamps, links
TransactionsISA/GS/ST control numbers, key data, set code, direction, usage indicator, partnership, processing status
Control-number logEvery stored field, including received time, hash, seen count and last seen

A Change row holds priorValues and newValues (only the fields that changed), the time, who (actor) and why (note). The actor is the signed-in user, or worker or system; reprocess, ignore, repeated control numbers, the AS2 gateway and workspace purge each record their own reason. A change made outside the application is still recorded, with actor unrecorded and the note “No reason was given by the writer.”

A reprocess writes a Correction row that points at the Arrival and names who requested it. The Arrival stays as written. Each status the transaction passes through (for example Failed, In progress, Completed) is its own Change row.

Section 8

Enforced by Application

Duplicates#

  • Repeated AS2 Message-ID. The repeated HTTP body is stored as a file, then a Duplicate row is written with the Message-ID, its own receivedAtUtc and receivedClock, the SHA-256 of that body, the file’s location, and a pointer to the first Arrival. Only then is it acknowledged. The file is not processed again and no second MDN is sent.
  • Repeated ISA13 (same partnership, within 365 days). A Duplicate row is written. The control-number record’s seen count increases, and that change is a Change row.

Section 9

Enforced by Application and Azure policy

Deletions#

  • Deleting an AS2 exchange file from the portal is refused, and the attempt is recorded as a Deletion row (who, when).
  • Deleting a control-number record (released on reprocess or ignore) produces a Deletion row holding its prior values.
  • Workspace purge (customer offboarding) deletes the working files and records. Each deleted record produces a Deletion row, and one further Deletion row records the purge itself, who performed it and when. The ledger is kept, as are the workspace’s evidence sharing settings and keys.
  • A purge does not touch the write-once evidence files. They remain readable through the evidence API, by version and hash-checked, until their Locked policy ends. The purge’s Deletion row states this and gives the latest end date.
  • Working storage also keeps the earlier version of an overwritten or deleted file, for the same retention period as the evidence files.

Section 10

Enforced by Application and database triggers

Reading the ledger from outside#

  • Grant. A workspace administrator turns evidence sharing on and creates an API key (ev.<prefix>.<secret>). The key is shown once and stored only as a SHA-256 hash. It reads one workspace only. Expiring the key, or turning sharing off, stops it immediately.
  • Every read is logged: which key, when, and what was read (cursor range, manifest or file). The read log cannot be changed or removed.
  • Every access change is logged: sharing on or off, key created, key expired, and key refused (unknown, wrong secret, expired, sharing off), with the caller’s address.
  • The workspace sees the same history in the DotLinQ portal, under Evidence.

Endpoints. Send the key as X-Api-Key or Authorization: Bearer.

Evidence read endpoints
RequestReturns
GET /api/evidence/read/changes?after=N&limit=MRows with sequence greater than N, in order. Pass nextCursor as the next after. Rows are never changed or removed, so the same after returns the same rows later, plus any newer ones: each row is read exactly once, in commit order.
GET /api/evidence/read/{id}/file/{raw|decrypted|mdn}The stored version’s bytes, with X-Evidence-Sha256 (checked before sending) and X-Evidence-Version-Id.
GET /api/evidence/read/exportA manifest of every row and every file with its hash, storedAtUtc, receivedAtUtc, receivedClock, versionId and immutableUntilUtc.

In the manifest, a file’s receive time is its own row’s (Arrival or Duplicate). For a row without one, such as an MDN stored later, it is the receive time of the Arrival it refers to, and receivedAtFromEvidenceId identifies that row.

Section 11

What is not guaranteed#

Stated plainly, so that nothing above is read as a broader claim than it is.

  1. 11.1

    AS2 only. Arrival rows, receipt hashes and write-once files are produced for AS2 exchanges. Files exchanged over SFTP or a REST API do not receive Arrival rows yet. Changes to their transaction records are still recorded as Change rows.

  2. 11.2

    The database owner can remove the triggers. The append-only rules in section 6 rest on triggers that the database owner could drop. That is a deliberate change to the database schema, which the application cannot make.

  3. 11.3

    The receive time comes from our clock. receivedAtUtc is taken from the AS2 gateway host’s system clock (UTC), named on every row. It is not signed or anchored by an outside timestamp authority.

  4. 11.4

    A hash proves sameness, not origin. rawSha256 proves the bytes you read are the bytes that reached our gateway. Who sent them rests on the AS2 signature check, recorded in the MDN.

  5. 11.5

    Retention ends. After a file’s Locked policy ends, Azure allows it to be deleted. Nothing deletes it automatically today, but it is no longer protected by Azure after that date. Ledger rows are not removed.

  6. 11.6

    Older rows carry less. Files kept before 15 November 2026 have no version on their row; they are read from working storage rather than the write-once container, and are hash-checked the same way. Rows written before the receive-time columns existed have an empty receivedAtUtc and receivedClock.

  7. 11.7

    Only listed fields are tracked. Change rows are written only for the records and fields listed in section 7.

  8. 11.8

    Proof of the exchange, not of the event. A record proves what crossed DotLinQ and when, and that it is unchanged. It does not prove that what a message says is true, for example that a load was delivered at the time a 214 states. Establishing the event behind the messages means comparing records from several independent systems.

Need a guarantee not listed here?

Write to support@dotlinq.com. We will tell you whether it is built. It is added to this page only once it has shipped.

Section 12

Revision history#

This page changes only when the product changes. Earlier versions remain listed so a citation of an earlier version can be read against what changed.

Revision history
VersionDateChange
1.216 Nov 2026States the boundary plainly: a record proves what crossed DotLinQ, not the event behind it (section 1 and 11.8). No change to the guarantees.
1.115 Nov 2026Added a three-minute explainer film. No change to the guarantees.
1.015 Nov 2026First publication.