@dopamint-fun/open-sdk 0.1.0-dev.0

package/dist/sessionCodec.d.ts

@@ -0,0 +1,139 @@
+import { type SessionContext } from "./sessionWire.js";
+export declare const SESSION_JOINED_TAG = 2;
+export declare const PARTICIPANT_VIEW_TAG = 3;
+export declare const ACTION_ACKNOWLEDGED_TAG = 5;
+export declare const ACTION_PENDING_TAG = 6;
+export declare const ACTION_REJECTED_TAG = 7;
+export declare const ACTION_COMMITTED_TAG = 8;
+export declare const SESSION_RESUMED_TAG = 11;
+export declare const SESSION_TERMINAL_TAG = 12;
+export declare const SESSION_ERROR_TAG = 13;
+export declare const SEAT_AUTHORIZATION_CHALLENGE_TAG = 15;
+export declare const SEAT_AUTHORIZATION_RESPONSE_TAG = 16;
+export declare const MAX_TRANSPORT_FRAME_BYTES: number;
+export interface WireEnvelope {
+    message: string;
+}
+export declare function encodeAckFrame(context: SessionContext, cursor: number | bigint | ResumeCursor): Uint8Array;
+export declare function encodeEnvelope(wire: Uint8Array): WireEnvelope;
+export declare function decodeEnvelope(envelope: WireEnvelope): Uint8Array;
+export interface StateRef {
+    nonce: bigint;
+    commitment: Uint8Array;
+}
+export interface ReceiptRef {
+    digest: Uint8Array;
+    resultingState: StateRef;
+}
+export interface ResumeCursor {
+    sequence: bigint;
+    witnessedReceipt: ReceiptRef | null;
+}
+export interface ViewSnapshot {
+    state: StateRef;
+    participantView: Uint8Array;
+    participantViewSchema: number;
+    legalActions: Uint8Array;
+    legalActionsSchema: number;
+    participantDeadlineMs: bigint;
+    latestReceipt: ReceiptRef | null;
+}
+export interface SessionPolicy {
+    maxParticipantViewBytes: bigint;
+    maxActionPayloadBytes: bigint;
+    maxLegalActionSchemaBytes: bigint;
+    maxArtifactReferences: number;
+    maxUnacknowledgedEvents: bigint;
+    replayWindowEvents: bigint;
+    rateWindowMs: bigint;
+    maxActionsPerRateWindow: number;
+    actionBurst: number;
+}
+export interface SeatAuthChallenge {
+    context: SessionContext;
+    actionId: Uint8Array;
+    authorizationPayload: Uint8Array;
+    coordinatorProof: Uint8Array;
+    coordinatorPublicKey: Uint8Array;
+}
+export type AuthorityMessage = {
+    type: "sessionJoined";
+    context: SessionContext;
+    sequence: bigint;
+    policy: SessionPolicy;
+    view: ViewSnapshot;
+    cursor: ResumeCursor;
+} | {
+    type: "participantView";
+    context: SessionContext;
+    sequence: bigint;
+    view: ViewSnapshot;
+    cursor: ResumeCursor;
+} | {
+    type: "actionAcknowledged";
+    context: SessionContext;
+    sequence: bigint;
+    actionId: Uint8Array;
+} | {
+    type: "actionPending";
+    context: SessionContext;
+    sequence: bigint;
+} | {
+    type: "actionRejected";
+    context: SessionContext;
+    sequence: bigint;
+    actionId: Uint8Array;
+    view: ViewSnapshot;
+    cursor: ResumeCursor;
+} | {
+    type: "actionCommitted";
+    context: SessionContext;
+    sequence: bigint;
+    actionId: Uint8Array;
+    view: ViewSnapshot;
+    cursor: ResumeCursor;
+    receipt: ReceiptRef;
+} | {
+    type: "sessionResumed";
+    context: SessionContext;
+    sequence: bigint;
+    view: ViewSnapshot;
+    cursor: ResumeCursor;
+} | {
+    type: "sessionTerminal";
+    context: SessionContext;
+    sequence: bigint;
+    disposition: number;
+    finalState: StateRef;
+    cursor: ResumeCursor;
+    finalReceipt: ReceiptRef | null;
+} | {
+    type: "error";
+    retryable: boolean;
+    tag: number;
+    name: string;
+} | {
+    type: "seatAuthorization";
+    challenge: SeatAuthChallenge;
+};
+export declare const SESSION_ERROR_NAMES: readonly string[];
+/** The name behind a wire tag, or the tag itself where this build predates it. */
+export declare function sessionErrorName(tag: number): string;
+/** What a seat can do about a session error, where there is something.
+ *
+ *  Two of these are how a second client on the same key shows up: the newer
+ *  join supersedes the older binding, and the older client's next message
+ *  finds its session gone. Both used to read as transport flakiness. */
+export declare function sessionErrorHint(tag: number): string | null;
+export declare function decodeAuthorityMessage(bytes: Uint8Array): AuthorityMessage;
+export declare function encodeSeatAuthSuccessFrame(context: SessionContext, actionId: Uint8Array, signature: Uint8Array): Uint8Array;
+export declare function extractProtocolInput(payload: Uint8Array): Uint8Array;
+export declare function takePrincipalProof(bytes: Uint8Array): {
+    principalTag: number;
+    seat?: number;
+    role?: Uint8Array;
+    generation: Uint8Array;
+    scheme: number;
+    signature: Uint8Array;
+    rest: Uint8Array;
+};

package/dist/sessionCodec.js

@@ -0,0 +1,373 @@
+/* HTTP envelope and authority-message decode for the Participant Session.
+ *
+ * Participant send path reuses the signing bodies in sessionWire.ts and
+ * appends the signature. Authority messages are decoded just far enough for
+ * the seat loop: views, commits, terminal, errors, and seat-auth challenges.
+ */
+import { ByteReader, ByteWriter } from "./bytes.js";
+import { encodeContext } from "./sessionWire.js";
+const AUTHORITY_EVENT_ACKNOWLEDGEMENT_TAG = 0x09;
+export const SESSION_JOINED_TAG = 0x02;
+export const PARTICIPANT_VIEW_TAG = 0x03;
+export const ACTION_ACKNOWLEDGED_TAG = 0x05;
+export const ACTION_PENDING_TAG = 0x06;
+export const ACTION_REJECTED_TAG = 0x07;
+export const ACTION_COMMITTED_TAG = 0x08;
+export const SESSION_RESUMED_TAG = 0x0b;
+export const SESSION_TERMINAL_TAG = 0x0c;
+export const SESSION_ERROR_TAG = 0x0d;
+export const SEAT_AUTHORIZATION_CHALLENGE_TAG = 0x0f;
+export const SEAT_AUTHORIZATION_RESPONSE_TAG = 0x10;
+export const MAX_TRANSPORT_FRAME_BYTES = 1 << 20;
+export function encodeAckFrame(context, cursor) {
+    const sequence = typeof cursor === "object" ? cursor.sequence : cursor;
+    const receipt = typeof cursor === "object" ? cursor.witnessedReceipt : null;
+    const writer = new ByteWriter()
+        .pushU16(context.wireVersion)
+        .pushByte(AUTHORITY_EVENT_ACKNOWLEDGEMENT_TAG);
+    encodeContext(writer, context);
+    writer.pushU64(sequence);
+    if (receipt) {
+        writer
+            .pushByte(1)
+            .pushFixed(receipt.digest, 32, "receipt digest")
+            .pushU64(receipt.resultingState.nonce)
+            .pushFixed(receipt.resultingState.commitment, 32, "receipt resulting state");
+    }
+    else {
+        writer.pushByte(0);
+    }
+    return writer.bytes();
+}
+export function encodeEnvelope(wire) {
+    if (wire.length > MAX_TRANSPORT_FRAME_BYTES)
+        throw new Error("session frame exceeds transport ceiling");
+    return { message: Buffer.from(wire).toString("base64") };
+}
+export function decodeEnvelope(envelope) {
+    const wire = Buffer.from(envelope.message, "base64");
+    if (wire.length > MAX_TRANSPORT_FRAME_BYTES)
+        throw new Error("session frame exceeds transport ceiling");
+    return new Uint8Array(wire);
+}
+/* The authority's session-protocol error tags, by name.
+ *
+ * `arena-session/src/wire.rs` numbers `SessionProtocolError` on the wire and
+ * this side surfaced the number: "session error tag 6". Two agents met that
+ * message in one afternoon and both read it as a broken resume path. It was
+ * `UnknownSession` — and in their case the cause was the two of them joining
+ * the same seat with the same key, each join retiring the other's session.
+ * A name is what lets a reader look that up; the number sent them into the
+ * Rust source instead. */
+export const SESSION_ERROR_NAMES = [
+    "UnsupportedWireVersion",
+    "UnsupportedSessionVersion",
+    "InvalidMessageTag",
+    "MalformedEncoding",
+    "ManifestMismatch",
+    "AuthenticationFailed",
+    "UnknownSession",
+    "InvalidResumeCursor",
+    "PayloadLimitExceeded",
+    "ServiceUnavailable",
+    "SessionSuperseded",
+    "ChallengeRequired",
+];
+/** The name behind a wire tag, or the tag itself where this build predates it. */
+export function sessionErrorName(tag) {
+    return SESSION_ERROR_NAMES[tag] ?? `unknown tag ${tag}`;
+}
+/** What a seat can do about a session error, where there is something.
+ *
+ *  Two of these are how a second client on the same key shows up: the newer
+ *  join supersedes the older binding, and the older client's next message
+ *  finds its session gone. Both used to read as transport flakiness. */
+export function sessionErrorHint(tag) {
+    switch (tag) {
+        case 6:
+            return "the authority no longer holds this session; join afresh — and if this repeats, another client may be joining this seat with the same key";
+        case 10:
+            return "a newer join replaced this seat's binding; another client is running with this key";
+        case 7:
+            return "the resume cursor is outside the replay window; join afresh rather than resuming";
+        case 11:
+            return "the join needs a fresh seat-auth challenge; fetch one and retry";
+        default:
+            return null;
+    }
+}
+function readContext(reader, wireVersion) {
+    return {
+        wireVersion,
+        sessionVersion: reader.readU16("session version"),
+        sessionId: reader.readFixed(32, "session id"),
+        executionId: reader.readFixed(32, "execution id"),
+        executionManifestDigest: reader.readFixed(32, "execution manifest digest"),
+        protocolId: reader.readFixed(32, "protocol id"),
+        protocolVersion: reader.readU16("protocol version"),
+        participantId: reader.readFixed(32, "participant id"),
+        seat: reader.readU16("seat"),
+    };
+}
+function readState(reader, nonceField, commitmentField) {
+    return {
+        nonce: reader.readU64(nonceField),
+        commitment: reader.readFixed(32, commitmentField),
+    };
+}
+function readReceipt(reader) {
+    return {
+        digest: reader.readFixed(32, "receipt digest"),
+        resultingState: readState(reader, "receipt resulting state nonce", "receipt resulting state commitment"),
+    };
+}
+function readOption(reader, field, read) {
+    const tag = reader.readByte(field);
+    if (tag === 0)
+        return null;
+    if (tag === 1)
+        return read();
+    throw new Error(`invalid option tag ${tag} for ${field}`);
+}
+function readPayload(reader, lengthField, bytesField) {
+    const schema = reader.readU16("payload schema version");
+    const bytes = reader.readLengthPrefixed(lengthField, bytesField);
+    return { schema, bytes };
+}
+function readCursor(reader) {
+    const sequence = reader.readU64("cursor event sequence");
+    const witnessedReceipt = readOption(reader, "cursor witnessed receipt option", () => readReceipt(reader));
+    return { sequence, witnessedReceipt };
+}
+function readView(reader) {
+    const state = readState(reader, "view state nonce", "view state commitment");
+    const participantView = readPayload(reader, "participant view byte length", "participant view bytes");
+    const legal = readPayload(reader, "legal action schema byte length", "legal action schema bytes");
+    const participantDeadlineMs = reader.readU64("participant deadline milliseconds");
+    const latestReceipt = readOption(reader, "latest receipt option", () => readReceipt(reader));
+    return {
+        state,
+        participantView: participantView.bytes,
+        participantViewSchema: participantView.schema,
+        legalActions: legal.bytes,
+        legalActionsSchema: legal.schema,
+        participantDeadlineMs,
+        latestReceipt,
+    };
+}
+function readPolicy(reader) {
+    return {
+        maxParticipantViewBytes: reader.readU64("maximum participant view bytes"),
+        maxActionPayloadBytes: reader.readU64("maximum action payload bytes"),
+        maxLegalActionSchemaBytes: reader.readU64("maximum legal action schema bytes"),
+        maxArtifactReferences: reader.readU16("maximum artifact references"),
+        maxUnacknowledgedEvents: reader.readU64("maximum unacknowledged events"),
+        replayWindowEvents: reader.readU64("replay window events"),
+        rateWindowMs: reader.readU64("rate window milliseconds"),
+        maxActionsPerRateWindow: reader.readU32("maximum actions per rate window"),
+        actionBurst: reader.readU32("action burst"),
+    };
+}
+function skipAuthorization(reader) {
+    const tag = reader.readByte("authorization requirement tag");
+    if (tag !== 0)
+        throw new Error(`invalid authorization requirement tag ${tag}`);
+    const count = reader.readU16("authorization principal count");
+    for (let i = 0; i < count; i++) {
+        const principalTag = reader.readByte("authorization principal tag");
+        if (principalTag === 0)
+            reader.readU16("authorization seat");
+        else if (principalTag === 1)
+            reader.readFixed(32, "authorization role");
+        else
+            throw new Error(`invalid authorization principal tag ${principalTag}`);
+    }
+}
+function readActionRejection(reader) {
+    const tag = reader.readByte("action rejection tag");
+    if (tag === 0 || tag === 6)
+        reader.readU16("action rejection extra");
+    if (tag > 13)
+        throw new Error(`invalid action rejection tag ${tag}`);
+}
+function readSeatAuthChallenge(reader, wireVersion) {
+    const context = readContext(reader, wireVersion);
+    const actionId = reader.readFixed(32, "seat authorization action id");
+    const payloadLen = reader.readU32("seat authorization payload length");
+    const authorizationPayload = reader.readFixed(payloadLen, "seat authorization payload");
+    const proofLen = reader.readU32("seat authorization proof length");
+    const coordinatorProof = reader.readFixed(proofLen, "seat authorization proof");
+    const coordinatorPublicKey = reader.readFixed(32, "coordinator public key");
+    return {
+        context,
+        actionId,
+        authorizationPayload,
+        coordinatorProof,
+        coordinatorPublicKey,
+    };
+}
+export function decodeAuthorityMessage(bytes) {
+    const reader = new ByteReader(bytes);
+    const wireVersion = reader.readU16("wire version");
+    const tag = reader.readByte("message tag");
+    if (tag === SESSION_ERROR_TAG) {
+        readOption(reader, "session version option", () => reader.readU16("session version"));
+        const errorTag = reader.readByte("session protocol error tag");
+        if (errorTag === 0 || errorTag === 1)
+            reader.readU16("unsupported version");
+        if (errorTag === 2)
+            reader.readByte("invalid message tag");
+        const retry = reader.readByte("retry disposition");
+        reader.finish();
+        return {
+            type: "error",
+            retryable: retry !== 0,
+            tag: errorTag,
+            name: sessionErrorName(errorTag),
+        };
+    }
+    if (tag === SEAT_AUTHORIZATION_CHALLENGE_TAG) {
+        const challenge = readSeatAuthChallenge(reader, wireVersion);
+        reader.finish();
+        return { type: "seatAuthorization", challenge };
+    }
+    const context = readContext(reader, wireVersion);
+    const sequence = reader.readU64("authority event sequence");
+    let message;
+    switch (tag) {
+        case SESSION_JOINED_TAG: {
+            const policy = readPolicy(reader);
+            const view = readView(reader);
+            const cursor = readCursor(reader);
+            message = {
+                type: "sessionJoined",
+                context,
+                sequence,
+                policy,
+                view,
+                cursor,
+            };
+            break;
+        }
+        case PARTICIPANT_VIEW_TAG: {
+            const view = readView(reader);
+            const cursor = readCursor(reader);
+            message = { type: "participantView", context, sequence, view, cursor };
+            break;
+        }
+        case ACTION_ACKNOWLEDGED_TAG:
+            message = {
+                type: "actionAcknowledged",
+                context,
+                sequence,
+                actionId: reader.readFixed(32, "action id"),
+            };
+            break;
+        case ACTION_PENDING_TAG:
+            reader.readFixed(32, "action id");
+            skipAuthorization(reader);
+            message = { type: "actionPending", context, sequence };
+            break;
+        case ACTION_REJECTED_TAG: {
+            const actionId = reader.readFixed(32, "action id");
+            readActionRejection(reader);
+            reader.readByte("retry disposition");
+            const view = readView(reader);
+            const cursor = readCursor(reader);
+            message = {
+                type: "actionRejected",
+                context,
+                sequence,
+                actionId,
+                view,
+                cursor,
+            };
+            break;
+        }
+        case ACTION_COMMITTED_TAG: {
+            const actionId = reader.readFixed(32, "action id");
+            const receipt = readReceipt(reader);
+            const view = readView(reader);
+            const cursor = readCursor(reader);
+            message = {
+                type: "actionCommitted",
+                context,
+                sequence,
+                actionId,
+                view,
+                cursor,
+                receipt,
+            };
+            break;
+        }
+        case SESSION_RESUMED_TAG: {
+            reader.readU64("replay from sequence");
+            const view = readView(reader);
+            const cursor = readCursor(reader);
+            message = { type: "sessionResumed", context, sequence, view, cursor };
+            break;
+        }
+        case SESSION_TERMINAL_TAG: {
+            const disposition = reader.readByte("terminal disposition");
+            const finalState = readState(reader, "final state nonce", "final state commitment");
+            const finalReceipt = readOption(reader, "final receipt option", () => readReceipt(reader));
+            const cursor = readCursor(reader);
+            message = {
+                type: "sessionTerminal",
+                context,
+                sequence,
+                disposition,
+                finalState,
+                cursor,
+                finalReceipt,
+            };
+            break;
+        }
+        default:
+            throw new Error(`unknown authority message tag ${tag}`);
+    }
+    reader.finish();
+    return message;
+}
+export function encodeSeatAuthSuccessFrame(context, actionId, signature) {
+    if (signature.length !== 64)
+        throw new Error("seat authorization signature must be 64 bytes");
+    const writer = new ByteWriter()
+        .pushU16(context.wireVersion)
+        .pushByte(SEAT_AUTHORIZATION_RESPONSE_TAG);
+    encodeContext(writer, context);
+    writer.pushFixed(actionId, 32, "action id").pushByte(0).pushBytes(signature);
+    return writer.bytes();
+}
+export function extractProtocolInput(payload) {
+    const reader = new ByteReader(payload);
+    const candidateLen = Number(reader.readU64("candidate length"));
+    reader.readFixed(candidateLen, "candidate transition");
+    reader.readU16("protocol input schema");
+    return reader.readLengthPrefixed("protocol input length", "protocol input");
+}
+export function takePrincipalProof(bytes) {
+    const reader = new ByteReader(bytes);
+    const principalTag = reader.readByte("authorization principal tag");
+    let seat;
+    let role;
+    if (principalTag === 0)
+        seat = reader.readU16("authorization seat");
+    else if (principalTag === 1)
+        role = reader.readFixed(32, "authorization role");
+    else
+        throw new Error(`invalid principal tag ${principalTag}`);
+    const generation = reader.readFixed(32, "runtime generation");
+    const scheme = reader.readByte("signature scheme");
+    const sigLen = reader.readU16("signature length");
+    const signature = reader.readFixed(sigLen, "signature bytes");
+    return {
+        principalTag,
+        seat,
+        role,
+        generation,
+        scheme,
+        signature,
+        rest: bytes.slice(reader.consumed()),
+    };
+}

package/dist/sessionWire.d.ts

@@ -0,0 +1,80 @@
+import { ByteWriter } from "./bytes.js";
+export interface SessionContext {
+    wireVersion: number;
+    sessionVersion: number;
+    /** 32 bytes */
+    sessionId: Uint8Array;
+    /** 32 bytes */
+    executionId: Uint8Array;
+    /** 32 bytes */
+    executionManifestDigest: Uint8Array;
+    /** 32 bytes */
+    protocolId: Uint8Array;
+    protocolVersion: number;
+    /** 32 bytes */
+    participantId: Uint8Array;
+    seat: number;
+}
+export declare function encodeContext(writer: ByteWriter, context: SessionContext): void;
+export declare function encodeSignature(signature: Uint8Array): Uint8Array;
+export declare function signedFrame(body: Uint8Array, signature: Uint8Array): Uint8Array;
+export interface JoinRequest {
+    wireVersion: number;
+    /** strictly ascending, the wire rejects any other ordering */
+    supportedSessionVersions: number[];
+    executionId: Uint8Array;
+    executionManifestDigest: Uint8Array;
+    participantId: Uint8Array;
+    seat: number;
+    /** 32 bytes */
+    clientNonce: Uint8Array;
+    /** 74 bytes, as issued by the authority's challenge */
+    challenge: Uint8Array;
+}
+export declare function joinBodyBytes(request: JoinRequest): Uint8Array;
+export declare function joinSigningBytes(request: JoinRequest): Uint8Array;
+export declare function encodeJoinFrame(request: JoinRequest, signature: Uint8Array): Uint8Array;
+export interface ArtifactReference {
+    kind: number;
+    schemaVersion: number;
+    /** 32 bytes */
+    digest: Uint8Array;
+    byteLength: number | bigint;
+}
+export interface ActionProposal {
+    context: SessionContext;
+    /** 32 bytes */
+    actionId: Uint8Array;
+    expectedStateNonce: number | bigint;
+    /** 32 bytes */
+    expectedStateCommitment: Uint8Array;
+    participantDeadlineMs: number | bigint;
+    payloadSchemaVersion: number;
+    payload: Uint8Array;
+    artifactReferences?: ArtifactReference[];
+}
+export declare function actionBodyBytes(proposal: ActionProposal): Uint8Array;
+export declare function actionSigningBytes(proposal: ActionProposal): Uint8Array;
+export declare function encodeActionFrame(proposal: ActionProposal, signature: Uint8Array): Uint8Array;
+export interface ResumeWitnessedReceipt {
+    /** 32 bytes */
+    digest: Uint8Array;
+    resultingState: {
+        nonce: number | bigint;
+        /** 32 bytes */
+        commitment: Uint8Array;
+    };
+}
+export interface ResumeRequest {
+    context: SessionContext;
+    cursorSequence: number | bigint;
+    /** the receipt the last acknowledged cursor witnessed; omit or null for None */
+    witnessedReceipt?: ResumeWitnessedReceipt | null;
+    /** 32 bytes */
+    clientNonce: Uint8Array;
+    /** 74 bytes */
+    challenge: Uint8Array;
+}
+export declare function resumeBodyBytes(request: ResumeRequest): Uint8Array;
+export declare function resumeSigningBytes(request: ResumeRequest): Uint8Array;
+export declare function encodeResumeFrame(request: ResumeRequest, signature: Uint8Array): Uint8Array;