TAP 聚合器

一个无状态的 JSON-RPC 服务，允许客户端从一系列单独收据中请求汇总收据。

设置

A JSON-RPC service for the Timeline Aggregation Protocol that lets clients request an aggregate receipt from a list of
individual receipts.

Usage: tap_aggregator [OPTIONS] --private-key <PRIVATE_KEY>

Options:
      --port <PORT>
          Port to listen on for JSON-RPC requests [env: TAP_PORT=] [default: 8080]
      --private-key <PRIVATE_KEY>
          Sender private key for signing Receipt Aggregate Vouchers, as a hex string [env: TAP_PRIVATE_KEY=]
      --max-request-body-size <MAX_REQUEST_BODY_SIZE>
          Maximum request body size in bytes. Defaults to 10MB [env: TAP_MAX_REQUEST_BODY_SIZE=] [default: 10485760]
      --max-response-body-size <MAX_RESPONSE_BODY_SIZE>
          Maximum response body size in bytes. Defaults to 100kB [env: TAP_MAX_RESPONSE_BODY_SIZE=] [default: 102400]
      --max-connections <MAX_CONNECTIONS>
          Maximum number of concurrent connections. Defaults to 32 [env: TAP_MAX_CONNECTIONS=] [default: 32]
  -h, --help
          Print help
  -V, --version
          Print version

有关收据汇总凭证签名密钥的更多信息，请参阅 timeline-aggregation-protocol-contracts。

操作建议

这只是一个关于安全运行 TAP 聚合器的非详尽提醒清单。作为一个 HTTP 服务，当向公众互联网提供 HTTP 服务时，请运用您的最佳判断并采用行业标准最佳实践。

• 通过安全的 DNS 服务（带有 DNSSEC 等）进行广告宣传
• 仅通过 HTTPS（通过反向代理）公开
• 使用 WAF，如果可用
  • DDoS 保护、速率限制等。
  • 根据运营商的司法管辖区进行地理围栏。
  • 检查 HTTP 响应。
  • 检查 JSON 请求和响应。为了验证输入，以及解析响应中的 JSON-RPC 错误代码。

还建议客户端使用 HTTP 压缩对 TAP 聚合器的 HTTP 请求进行压缩，因为 RAV 请求可能相当大。

JSON-RPC API

通用接口

请求格式

请求格式是标准的，如 官方规范 所述。

成功响应格式

如果调用成功，则响应格式如 官方规范 所述，并且此外 result 字段的形式为

{
    "id": 0,
    "jsonrpc": "2.0",
    "result": {
        "data": {...},
        "warnings": [
            {
                "code": -32000,
                "message": "Error message",
                "data": {...}
            }
        ]
    }
}

警告：务必检查警告！

警告对象格式（类似于标准JSON-RPC错误对象）

我们定义了以下警告代码

• -32051 API版本弃用

  此外，还返回一个对象，其中包含方法支持的版本，在data字段中。示例

  {
      "id": 0,
      "jsonrpc": "2.0",
      "result": {
          "data": {...},
          "warnings": [
              {
                  "code": -32051,
                  "data": {
                      "versions_deprecated": [
                          "0.0"
                      ],
                      "versions_supported": [
                          "0.0",
                          "0.1"
                      ]
                  },
                  "message": "The API version 0.0 will be deprecated. Please check https://github.com/semiotic-ai/timeline_aggregation_protocol for more information."
              }
          ]
      }
  }
  

错误响应格式

如果调用失败，错误响应格式如官方规范中所述。

除了官方规范之外，我们还定义了一些特殊错误

• -32001 无效API版本。

  此外，还返回一个对象，其中包含方法支持的版本，在data字段中。示例

  {
      "error": {
          "code": -32001,
          "data": {
              "versions_deprecated": [
                  "0.0"
              ],
              "versions_supported": [
                  "0.0",
                  "0.1"
              ]
          },
          "message": "Unsupported API version: \"0.2\"."
      },
      "id": 0,
      "jsonrpc": "2.0"
  }
  

• -32002 聚合错误。

  聚合函数返回错误。示例

  {
      "error": {
          "code": -32002,
          "message": "Signature verification failed. Expected 0x9858…da94, got 0x3ef9…a4a3"
      },
      "id": 0,
      "jsonrpc": "2.0"
  }
  

方法

api_versions()

source

返回此服务器实现的TAP JSON-RPC API版本。

示例

请求:

{
    "jsonrpc": "2.0",
    "id": 0,
    "method": "api_versions",
    "params": [
        null
    ]
}

响应:

{
    "id": 0,
    "jsonrpc": "2.0",
    "result": {
        "data": {
            "versions_deprecated": [
               "0.0"
            ],
            "versions_supported": [
                "0.0",
                "0.1"
            ]
        }
    }
}

aggregate_receipts(api_version,receipts,previous_rav)

source

将给定的收据聚合为收据汇总凭证。如果用户期望的API版本不受支持，则返回错误。

我们建议服务器设置最大HTTP请求大小为10MB，在这种情况下，我们保证aggregate_receipts至少支持每次调用15,000个收据。如果您要聚合的收据超过15,000个，我们建议多次调用aggregate_receipts。

示例

请求:

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "aggregate_receipts",
  "params": [
    "0.0",
    [
      {
        "message": {
          "allocation_id": "0xabababababababababababababababababababab",
          "timestamp_ns": 1685670449225087255,
          "nonce": 11835827017881841442,
          "value": 34
        },
        "signature": {
          "r": "0xa9fa1acf3cc3be503612f75602e68cc22286592db1f4f944c78397cbe529353b",
          "s": "0x566cfeb7e80a393021a443d5846c0734d25bcf54ed90d97effe93b1c8aef0911",
          "v": 27
        }
      },
      {
        "message": {
          "allocation_id": "0xabababababababababababababababababababab",
          "timestamp_ns": 1685670449225830106,
          "nonce": 17711980309995246801,
          "value": 23
        },
        "signature": {
          "r": "0x51ca5a2b839558654326d3a3f544a97d94effb9a7dd9cac7492007bc974e91f0",
          "s": "0x3d9d398ea6b0dd9fac97726f51c0840b8b314821fb4534cb40383850c431fd9e",
          "v": 28
        }
      }
    ],
    {
      "message": {
        "allocation_id": "0xabababababababababababababababababababab",
        "timestamp_ns": 1685670449224324338,
        "value_aggregate": 101
      },
      "signature": {
        "r": "0x601a1f399cf6223d1414a89b7bbc90ee13eeeec006bd59e0c96042266c6ad7dc",
        "s": "0x3172e795bd190865afac82e3a8be5f4ccd4b65958529986c779833625875f0b2",
        "v": 28
      }
    }
  ]
}

响应:

{
  "id": 0,
  "jsonrpc": "2.0",
  "result": {
    "data": {
      "message": {
        "allocation_id": "0xabababababababababababababababababababab",
        "timestamp_ns": 1685670449225830106,
        "value_aggregate": 158
      },
      "signature": {
        "r": "0x60eb38374119bbabf1ac6960f532124ba2a9c5990d9fb50875b512e611847eb5",
        "s": "0x1b9a330cc9e2ecbda340a4757afaee8f55b6dbf278428f8cf49dd5ad8438f83d",
        "v": 27
      }
    }
  }
}