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
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.
| Guarantee | Enforced by | Detail |
|---|---|---|
| The bytes received are hashed (SHA-256) at receipt and stored write-once | Azure immutability policy (Locked) | section 4 |
| A file is only returned if it still matches the hash taken at receipt | Application, on every read | section 4 |
| No MDN is returned, and nothing is sent, unless its evidence row is stored | Application, single database transaction | section 5 |
| Evidence rows cannot be updated, deleted or truncated | Database triggers | section 6 |
| Every change to a tracked record keeps its prior and new value, who and why | Database triggers, same transaction | section 7 |
| Repeated messages are kept and linked to the first copy, not reprocessed | Application | section 8 |
| Deleting a customer keeps the ledger and the write-once files | Application and Azure policy | section 9 |
| Outside readers see one workspace, with every read and access change logged | Application and database triggers | section 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
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.
| Kind | Written when |
|---|---|
| Arrival | An AS2 message is received, or is about to be sent. One per exchange. Never updated. |
| Identifiers | The file has been validated. Holds the ISA, GS and ST identifiers copied from the interchange as validated. |
| Mdn | An MDN (signed receipt) is stored after the Arrival. |
| Duplicate | A message arrives with an AS2 Message-ID already received, or a repeated ISA13 is seen. Points at the first Arrival. |
| Correction | A file is reprocessed. Points at the Arrival, which stays as written. |
| Change | A tracked value on an exchange, transaction or control-number record changed. Holds prior and new values. |
| Deletion | A 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.
| Group | Fields |
|---|---|
| Position | id sequence kind refersToId fileExchangeId direction |
| Time | receivedAtUtc receivedClock storedAtUtc |
| AS2 envelope | messageId as2From as2To mic disposition fileName |
| X12 identifiers | isa05 isa06 isa07 isa08 isa13 gs02 gs03 gs06 st02 |
| Files | rawSha256 decryptedSha256 mdnSha256 fileStore rawVersionId decryptedVersionId mdnVersionId filesImmutableUntilUtc, and the storage key of each file |
| Change | sourceTable sourceId priorValues newValues |
| Who and why | actor note |
Section 3
Identifiers and timestamps#
| Field | Meaning |
|---|---|
id | Unique 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. |
sequence | Position 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. |
refersToId | The earlier row this row is about. |
direction | 0 inbound, 1 outbound. Stored when the row is written; a later change to the exchange does not alter it. |
messageId as2From as2To | The AS2 Message-ID, AS2-From and AS2-To headers. Recorded on the Arrival at receipt and never updated. |
receivedAtUtc | When 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. |
receivedClock | The clock that set receivedAtUtc, named on the row: as2-gateway system clock (UTC), host <host name> |
storedAtUtc | When the row was written, by the control-plane server clock. |
isa05–isa08 isa13 gs02 gs03 gs06 st02 | Sender 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. |
filesImmutableUntilUtc | The 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.
| File | Hash field |
|---|---|
| The bytes exactly as received on the HTTP request, hashed at receipt | rawSha256 |
| The payload as it came out of decryption and signature checking, not re-serialized | decryptedSha256 |
| The MDN sent or received, including an error MDN when a message is refused | mdnSha256, 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
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.
| Record | Tracked fields |
|---|---|
| File exchanges | Status, MDN status, file name, size, content hash, Message-ID, MIC, disposition, MDN time, file keys, error, timestamps, links |
| Transactions | ISA/GS/ST control numbers, key data, set code, direction, usage indicator, partnership, processing status |
| Control-number log | Every 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
receivedAtUtcandreceivedClock, 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.
| Request | Returns |
|---|---|
GET /api/evidence/read/changes?after=N&limit=M | Rows 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/export | A 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.
- 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.
- 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.
- 11.3
The receive time comes from our clock.
receivedAtUtcis 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. - 11.4
A hash proves sameness, not origin.
rawSha256proves the bytes you read are the bytes that reached our gateway. Who sent them rests on the AS2 signature check, recorded in the MDN. - 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.
- 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
receivedAtUtcandreceivedClock. - 11.7
Only listed fields are tracked. Change rows are written only for the records and fields listed in section 7.
- 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?
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.
| Version | Date | Change |
|---|---|---|
| 1.2 | 16 Nov 2026 | States 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.1 | 15 Nov 2026 | Added a three-minute explainer film. No change to the guarantees. |
| 1.0 | 15 Nov 2026 | First publication. |
