Document the Midnight funnel

docs/home/100-state-machine/300-react-to-events/10-primitive-catalogue/40-midnight/10-contract-state.md

@@ -0,0 +1,33 @@
+# Contract state
+
+Midnight contracts have a publically-visible [ledger state](https://docs.midnight.network/develop/reference/compact/lang-ref#ledger-state-types).
+Once a [Midnight funnel](../../3-funnel-types/900-midnight-funnel.md) is configured,
+the `midnight-contract-state` primitive can be used to observe updates to this state.
+
+### Example configuration
+
+```yaml
+extensions:
+  - name: "my midnight extension"
+    type: midnight-contract-state
+    network: MidnightLocal
+    contractAddress: 010000c39bbf7ba21aa4c953e08412a8ff7ab1fab4a7cc11a00ad20eeb8050965ee838
+    startBlockHeight: 0
+    scheduledPrefix: myaction
+```
+
+## Concise format
+
+```
+midnightContractState = myaction|data
+```
+
+```ts
+const midnightContractState: ParserRecord<MidnightContractStateEvent> = {
+  data: PaimaParser.Json(),
+};
+```
+
+## JSON format
+
+The JSON blob within the concise payload conforms to the [EncodedStateValue](https://docs.midnight.network/develop/reference/midnight-api/onchain-runtime/type-aliases/EncodedStateValue) type.

docs/home/100-state-machine/300-react-to-events/10-primitive-catalogue/40-midnight/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Midnight Primitives"
+}

docs/home/100-state-machine/300-react-to-events/3-funnel-types/900-midnight-funnel.md

@@ -0,0 +1,43 @@
+# Midnight funnel
+
+Paima can observe [Midnight] contract states.
+
+[Midnight]: https://docs.midnight.network/learn/introduction/what-is-midnight/
+
+## Configuration
+
+Public devnet example:
+```yaml
+MidnightDevnet:
+  type: midnight
+  networkId: 1
+  indexer: https://indexer.devnet.midnight.network/api/v1/graphql
+  # indexerWS: wss://indexer.devnet.midnight.network/api/v1/graphql/ws
+  confirmationDepth: 2
+```
+
+[Standalone network] example:
+```yaml
+MidnightLocal:
+  type: midnight
+  networkId: 0
+  indexer: http://localhost:32807/api/v1/graphql
+  # indexerWS: ws://localhost:32807/api/v1/graphql/ws
+  confirmationDepth: 0
+```
+
+- `indexer` should be the full URL to the [indexer GraphQL] endpoint.
+- `indexerWs` can be used to manually override the [indexer WebSocket] URL if the default is insufficient.
+- `networkId` must match the network ID encoded into proofs on the chain associated with the indexer.
+  - `0` for a standalone test node.
+  - `1` for the public devnet.
+- `confirmationDepth` controls how many Midnight blocks behind the tip will be processed.
+  - Setting this to 0 will increase latency because the funnel will always have to wait for the newest Midnight block even if its timestamp would be higher than that of the main block being processed.
+
+[standalone network]: https://docs.midnight.network/develop/tutorial/creating/local-testing#run-the-dapp-in-standalone-mode
+[indexer GraphQL]: https://docs.midnight.network/develop/reference/midnight-api/pubsub-indexer/#queries
+[indexer WebSocket]: https://docs.midnight.network/develop/reference/midnight-api/pubsub-indexer/#subscriptions
+
+## Primitives
+
+* [Contract state](../10-primitive-catalogue/40-midnight/10-contract-state.md)