Add internal transaction events

pages/wallet-provider/nostr/_meta.json

@@ -4,6 +4,9 @@
   "inbound-transaction-start": "Inbound Transaction Start",
   "inbound-transaction-error": "Inbound Transaction Error",
   "inbound-transaction-ok": "Inbound Transaction Ok",
+  "internal-transaction-start": "Internal Transaction Start",
+  "internal-transaction-error": "Internal Transaction Error",
+  "internal-transaction-ok": "Internal Transaction Ok",
   "outbound-transaction-start": "Outbound Transaction Start",
   "outbound-transaction-error": "Outbound Transaction Error",
   "outbound-transaction-ok": "Outbound Transaction Ok"

pages/wallet-provider/nostr/internal-transaction-error.mdx

@@ -0,0 +1,71 @@
+# Internal Transaction Error
+
+This event is used to communicate errors encountered when trying to transfer tokens between pubkeys in the Ledger module.
+
+## Event Signature
+
+An _Internal Transaction Error_ event has the following form:
+
+```javascript
+{
+  "id": "{eventId}",
+  "pubkey": "{ledgerPubkey}",
+  "created_at": timestamp,
+  "kind": 1112,
+  "tags": [
+    ["p", "{senderPubkey}"],
+    ["p", "{receiverPubkey}"],
+    ["e", "{internalTransactionEventId}"],
+    ["t", "internal-transaction-error"],
+    ...,
+  ],
+  "content": "{internalTransactionErrorContent}",
+  "sig": "{signature}"
+}
+```
+
+Note:
+
+- the `.pubkey` is the [Ledger module's pubkey](../nostr#federation-public-keys),
+- the `.kind` field is `1112` (ie. a regular event),
+- the first `"p"` tag points to the _sender_ client's pubkey,
+- the second `"p"` tag points to the _receiver_ client's pubkey,
+- the `"t"` tag sub-kind is `internal-transaction-error`.
+
+The content itself is the JSON serialization of an object of the following form:
+
+```javascript
+{
+    "messages": [
+      "{errorMessage}"
+    ]
+}
+```
+
+An example TypeScript `type` definition for this event's content is:
+
+```typescript
+type InternalTransactionErrorContent = {
+    messages: [string],
+};
+```
+
+## Emitters
+
+This event is emitted by:
+
+- The Ledger module, when an [internal transaction](./internal-transaction-start) event fails for whatever reason.
+
+## Targets
+
+This event is targeted towards:
+
+- The _sender_ client.
+
+## Listeners
+
+This event is listened for by:
+
+- The _sender_ client.
+- The _receiver_ client.
+- Any other agent listening for this event will learn about failures to transfer funds between pubkeys.

pages/wallet-provider/nostr/internal-transaction-ok.mdx

@@ -0,0 +1,76 @@
+# Internal Transaction Ok
+
+This event is used to communicate the successful transference of tokens between pubkeys in the Ledger module.
+
+## Event Signature
+
+An _Internal Transaction Ok_ event has the following form:
+
+```javascript
+{
+  "id": "{eventId}",
+  "pubkey": "{ledgerPubkey}",
+  "created_at": timestamp,
+  "kind": 1112,
+  "tags": [
+    ["p", "{senderPubkey}"],
+    ["p", "{receiverPubkey}"],
+    ["e", "{internalTransactionEventId}"],
+    ["t", "internal-transaction-ok"],
+    ...,
+  ],
+  "content": "{internalTransactionOkContent}",
+  "sig": "{signature}"
+}
+```
+
+Note:
+
+- the `.pubkey` is the [Ledger module's pubkey](../nostr#federation-public-keys),
+- the `.kind` field is `1112` (ie. a regular event),
+- the first `"p"` tag points to the _sender_ client's pubkey,
+- the second `"p"` tag points to the _receiver_ client's pubkey,
+- the `"t"` tag sub-kind is `internal-transaction-ok`.
+
+The content itself is the JSON serialization of an object of the following form:
+
+```javascript
+{
+    "tokens": {
+        "{tokenName}": tokenAmount,
+        ...,
+    },
+    "memo": "{memoString}"
+}
+```
+
+An example TypeScript `type` definition for this event's content is:
+
+```typescript
+type InternalTransactionOkContent = {
+    tokens: Record<string, bigint>,
+    memo?: string,
+};
+```
+
+Not that both of these are equal to those for [Internal Transaction Start](./internal-transaction-start) events.
+
+## Emitters
+
+This event is emitted by:
+
+- The Ledger module, when an [internal transaction](./internal-transaction-start) event is successfully completed.
+
+## Targets
+
+This event is targeted towards:
+
+- The _sender_ client.
+
+## Listeners
+
+This event is listened for by:
+
+- The _sender_ client.
+- The _receiver_ client.
+- Any other agent listening for this event will learn about successfully completed transfers between pubkeys.

pages/wallet-provider/nostr/internal-transaction-start.mdx

@@ -0,0 +1,76 @@
+# Internal Transaction Start
+
+This event is used to transfer tokens between pubkeys in the Ledger module.
+
+## Event Signature
+
+An _internal Transaction Start_ event has the following form:
+
+```javascript
+{
+  "id": "{eventId}",
+  "pubkey": "{senderPubkey}",
+  "created_at": timestamp,
+  "kind": 1112,
+  "tags": [
+    ["p", "{ledgerPubkey}"],
+    ["p", "{receiverPubkey}"],
+    ["t", "internal-transaction-start"],
+    ...,
+  ],
+  "content": "{internalTransactionContent}",
+  "sig": "{signature}"
+}
+```
+
+Note:
+
+- the `.pubkey` is the _sender_ client's pubkey,
+- the `.kind` field is `1112` (ie. a regular event),
+- the first `"p"` tag points to the [Ledger module's pubkey](../nostr#federation-public-keys),
+- the second `"p"` tag points to the _receiver_ client's pubkey,
+- the `"t"` tag sub-kind is `internal-transaction-start`.
+
+The content itself is the JSON serialization of an object of the following form:
+
+```javascript
+{
+    "tokens": {
+        "{tokenName}": tokenAmount,
+        ...,
+    },
+    "memo": "{memoString}"
+}
+```
+
+Where the `.memo` entry is optional.
+Each `tokenAmount` must be positive, and each `tokenName` must exist in the Ledger module (notice that the `BTC` token **is expressed in milli-satoshis**).
+
+An example TypeScript `type` definition for this event's content is:
+
+```typescript
+type InternalTransactionStartContent = {
+    tokens: Record<string, bigint>,
+    memo?: string,
+};
+```
+
+## Emitters
+
+This event is emitted by:
+
+- The _sender_ client.
+
+## Targets
+
+This event is targeted towards:
+
+- The Ledger module.
+
+## Listeners
+
+This event is listened for by:
+
+- The Ledger module.
+- The _receiver_ client.
+- Any other agent listening for this event will learn about the cash flow between pubkeys.