diff --git a/es/solutions/builder/gas-sponsorship.mdx b/es/solutions/builder/gas-sponsorship.mdx index 7151588c..cf7fafc9 100644 --- a/es/solutions/builder/gas-sponsorship.mdx +++ b/es/solutions/builder/gas-sponsorship.mdx @@ -66,4 +66,65 @@ Patrocinar gas es sencillo y funciona en todas las redes que soportamos con un s ## Patrocinio de gas para ecosistemas -También ofrecemos la posibilidad de patrocinar todas las transacciones de su ecosistema, donde orquestamos varios signers a través de nuestro relayer a nivel de cadena. Esto significa que cualquier desarrollador que construya en su ecosistema, así como cualquier usuario de wallets Sequence, tendrá la mejor experiencia de incorporación y UX posible. No dude en [contactarnos](https://support.sequence.xyz) para configurar esto en su ecosistema. \ No newline at end of file +También ofrecemos la posibilidad de patrocinar todas las transacciones de su ecosistema, donde orquestamos varios signers a través de nuestro relayer a nivel de cadena. Esto significa que cualquier desarrollador que construya en su ecosistema, así como cualquier usuario de wallets Sequence, tendrá la mejor experiencia de incorporación y UX posible. No dude en [contactarnos](https://support.sequence.xyz) para configurar esto en su ecosistema. + +## Patrocinio condicional mediante Webhook +Si necesita tomar decisiones de patrocinio por transacción — por ejemplo, para aplicar límites de gasto por wallet, filtros KYC o reglas según el nivel de usuario — puede adjuntar un webhook a cualquier patrocinador de gas. Cuando llega una transacción patrocinada, el Relayer envía los detalles de la transacción a su endpoint mediante POST y solo la patrocina si usted la aprueba. + +### Configuración +Al crear o actualizar un patrocinador de gas, configure: +- `webhookUrl` — su endpoint HTTPS. Se requiere HTTPS. +- `webhookAuthToken` _(opcional, recomendado)_ — un secreto compartido de al menos 32 caracteres. El Relayer lo envía como `Authorization: Bearer ` en cada llamada. Sin un token, cualquiera que conozca la URL puede invocarla. + +### Solicitud +El Relayer envía un cuerpo JSON mediante POST a su `webhookUrl`: + +```json +{ + "chainId": 137, + "projectId": 12345, + "gasSponsorId": 678, + "walletAddress": "0x70236ffbAd7b70c2C65928c7Ca413AEa639FA0dE", + "transactions": [ + { "to": "0xA0b8...", "value": "0x0", "data": "0xa9059cbb..." } + ] +} +``` + +Encabezados enviados en cada llamada: +- `Content-Type: application/json` +- `Authorization: Bearer ` — solo si configuró un `webhookAuthToken` +- `X-Sequence-Request-Id: ` — identificador estable por llamada; úselo para registros o deduplicación + +`transactions[].value` y `data` están codificados en hexadecimal. Una sola decisión puede cubrir varias llamadas agrupadas — aplique sus reglas al arreglo completo. + +### Respuesta +Devuelva **HTTP 200** con exactamente este cuerpo JSON: + +```json +{ "sponsor": true } +``` + +o + +```json +{ "sponsor": false } +``` + + + **El código de estado HTTP es importante.** El Relayer solo considera `200 OK` como una decisión válida — cualquier otro estado (incluyendo `201`, `202`, `400`, `500`) se trata como un fallo de transporte y la transacción se patrocina (ver "Fail-open" abajo). + + No codifique una denegación como `400` ni una aprobación como `201`. Siempre devuelva `200` y coloque la decisión en el campo `sponsor`. + + +### Tiempo de espera y comportamiento fail-open +El Relayer espera hasta **2 segundos** por su respuesta. Si su endpoint es lento, inalcanzable, devuelve un estado distinto de 200, devuelve un JSON mal formado u omite el campo `sponsor`, el Relayer patrocina la transacción por defecto. + +Este comportamiento fail-open es intencional: un webhook defectuoso no debe interrumpir silenciosamente el patrocinio para sus usuarios. Para denegar una transacción, debe enviar explícitamente `{"sponsor": false}` con HTTP 200. + +### Seguridad + +- Se requiere HTTPS. El Relayer no sigue redirecciones, por lo que un endpoint HTTPS que redirige a `http://` será rechazado. +- Configure un `webhookAuthToken` a menos que su endpoint aplique autenticación en otra capa (lista de IP permitidas, proxy perimetral). +- El token se envía tal cual en el encabezado `Authorization` — no registre este encabezado. +- Para rotar el token, llame a `UpdateGasSponsor` con un nuevo valor. Para eliminar el control completamente, borre `webhookUrl`. \ No newline at end of file diff --git a/ja/solutions/builder/gas-sponsorship.mdx b/ja/solutions/builder/gas-sponsorship.mdx index 108041ee..b029ff01 100644 --- a/ja/solutions/builder/gas-sponsorship.mdx +++ b/ja/solutions/builder/gas-sponsorship.mdx @@ -66,4 +66,65 @@ sidebarTitle: ガススポンサーシップ ## エコシステム全体のガススポンサーシップ -また、エコシステム全体のトランザクションをスポンサーする機能も提供しています。これは、リレイヤーを通じて複数の署名者をチェーンレベルで調整する仕組みです。これにより、エコシステム上で開発する開発者やSequenceウォレットのユーザーが、最高のオンボーディングとUXを体験できます。ご希望の場合は、[こちらからお問い合わせ](https://support.sequence.xyz)ください。 \ No newline at end of file +また、エコシステム全体のトランザクションをスポンサーする機能も提供しています。これは、リレイヤーを通じて複数の署名者をチェーンレベルで調整する仕組みです。これにより、エコシステム上で開発する開発者やSequenceウォレットのユーザーが、最高のオンボーディングとUXを体験できます。ご希望の場合は、[こちらからお問い合わせ](https://support.sequence.xyz)ください。 + +## Webhookによる条件付きスポンサーシップ +取引ごとにスポンサーシップの判断が必要な場合（例：ウォレットごとの利用上限、KYC制限、ユーザー階層ルールなど）、任意のガススポンサーにWebhookを設定できます。スポンサー付き取引が届くと、Relayerが取引詳細をあなたのエンドポイントにPOSTし、あなたが承認した場合のみスポンサーします。 + +### 設定 +ガススポンサーを作成または更新する際、以下を設定してください： +- `webhookUrl` — あなたのHTTPSエンドポイント。HTTPSは必須です。 +- `webhookAuthToken` _(オプション、推奨)_ — 32文字以上の共有シークレット。Relayerは毎回 `Authorization: Bearer ` として送信します。トークンがない場合、URLを知っている誰でも呼び出せてしまいます。 + +### リクエスト +RelayerはJSONボディをあなたの`webhookUrl`にPOSTします： + +```json +{ + "chainId": 137, + "projectId": 12345, + "gasSponsorId": 678, + "walletAddress": "0x70236ffbAd7b70c2C65928c7Ca413AEa639FA0dE", + "transactions": [ + { "to": "0xA0b8...", "value": "0x0", "data": "0xa9059cbb..." } + ] +} +``` + +毎回送信されるヘッダー： +- `Content-Type: application/json` +- `Authorization: Bearer ` — `webhookAuthToken`を設定した場合のみ +- `X-Sequence-Request-Id: ` — 呼び出しごとに一意の識別子。ログや重複排除に利用できます。 + +`transactions[].value`と`data`は16進数でエンコードされています。1回の判断で複数のバッチ呼び出しをカバーできますので、配列全体にルールを適用してください。 + +### レスポンス +**HTTP 200**で、以下のJSONボディを正確に返してください： + +```json +{ "sponsor": true } +``` + +または + +```json +{ "sponsor": false } +``` + + + **HTTPステータスコードが重要です。** Relayerは`200 OK`のみを有効な判断として扱います。それ以外のステータス（`201`、`202`、`400`、`500`など）は通信エラーとみなし、取引はスポンサーされます（「フェイルオープン」参照）。 + + 拒否を`400`で返したり、承認を`201`で返したりしないでください。必ず`200`を返し、判断は`sponsor`フィールドに記載してください。 + + +### タイムアウトとフェイルオープン動作 +Relayerはあなたのレスポンスを**2秒間**待ちます。エンドポイントが遅い、到達できない、200以外のステータスを返す、不正なJSONを返す、または`sponsor`フィールドがない場合、Relayerは取引をスポンサーします。 + +このフェイルオープン動作は意図的です。Webhookの不具合でユーザーのスポンサーシップが静かに停止しないようにしています。取引を拒否するには、HTTP 200で明示的に`{"sponsor": false}`を返す必要があります。 + +### セキュリティ + +- HTTPSは必須です。Relayerはリダイレクトを追跡しないため、`http://`へリダイレクトするHTTPSエンドポイントは拒否されます。 +- エンドポイントで他の認証（IP許可リストやエッジプロキシなど）を強制していない限り、`webhookAuthToken`を設定してください。 +- トークンは`Authorization`ヘッダーにそのまま送信されます。このヘッダーはログに記録しないでください。 +- トークンをローテーションするには、新しい値で`UpdateGasSponsor`を呼び出してください。ゲートを完全に停止するには、`webhookUrl`を空にしてください。 \ No newline at end of file diff --git a/solutions/builder/gas-sponsorship.mdx b/solutions/builder/gas-sponsorship.mdx index c604062c..3bc8da59 100644 --- a/solutions/builder/gas-sponsorship.mdx +++ b/solutions/builder/gas-sponsorship.mdx @@ -48,8 +48,8 @@ Or, `Add Contract` to select a smart contract that you'd like to sponsor. ![select relayer network](/images/builder/builder_gas_sponsoring_add_contract.png) -Wallet sponsorship and contract sponsorship are scoped differently. Sponsoring a wallet can cover that wallet's relayed transactions across many contracts on the selected network. Sponsoring a contract can benefit many users, but only when they interact with that specific contract. - +Wallet sponsorship and contract sponsorship are scoped differently. Sponsoring a wallet can cover that wallet's relayed transactions across many contracts on the selected network. Sponsoring a contract can benefit many users, but only when they interact with that specific contract. + Now, we are going to add a payment method via a credit card in order to fund the sponsorship. Go to the [gas sponsorship configuration](https://sequence.build/project/default/relayer?view=gas-tank) and select Setup Payment Method. @@ -71,4 +71,72 @@ Do not use a Builder contract deployment as your sponsorship test, since deploym ## Ecosystem Gas Sponsorship -We also offer the capability to sponsor all transactions for your ecosystem where we orchestrate a number of signers through our relayer at the chain level. This means any developer building on your ecosystem as well as any user of Sequence wallets has the best onboarding and UX experience possible. Please feel free to [contact us](https://support.sequence.xyz) to set this up for your ecosystem. +We also offer the capability to sponsor all transactions for your ecosystem where we orchestrate a number of signers through our relayer at the chain level. This means any developer building on your ecosystem as well as any user of Sequence wallets has the best onboarding and UX experience possible. Please feel free to [contact us](https://support.sequence.xyz) to set this up for your ecosystem. + +## Conditional Sponsorship via Webhook + +If you need to make per-transaction sponsorship decisions — for example to apply per-wallet spend caps, KYC gates, or user-tier rules — you can attach a webhook to any gas sponsor. When a sponsored transaction arrives, the Relayer POSTs the transaction details to your endpoint and only sponsors it if you approve. + +### Configuration + +When creating or updating a gas sponsor, set: + +- `webhookUrl` — your HTTPS endpoint. HTTPS is required. +- `webhookAuthToken` *(optional, recommended)* — a shared secret of at least 32 characters. The Relayer sends it as `Authorization: Bearer ` on every call. Without a token, anyone who learns the URL can invoke it. + +### Request + +The Relayer POSTs a JSON body to your `webhookUrl`: + +```json +{ + "chainId": 137, + "projectId": 12345, + "gasSponsorId": 678, + "walletAddress": "0x70236ffbAd7b70c2C65928c7Ca413AEa639FA0dE", + "transactions": [ + { "to": "0xA0b8...", "value": "0x0", "data": "0xa9059cbb..." } + ] +} +``` + +Headers sent on every call: + +- `Content-Type: application/json` +- `Authorization: Bearer ` — only if you configured a `webhookAuthToken` +- `X-Sequence-Request-Id: ` — stable per-call identifier; use it for logging or deduplication + +`transactions[].value` and `data` are hex-encoded. A single decision can cover multiple batched calls — apply your rules to the array as a whole. + +### Response + +Return **HTTP 200** with exactly this JSON body: + +```json +{ "sponsor": true } +``` + +or + +```json +{ "sponsor": false } +``` + + +**The HTTP status code matters.** The Relayer treats only `200 OK` as a valid decision — any other status (including `201`, `202`, `400`, `500`) is treated as a transport-level failure and the transaction is sponsored (see "Fail-open" below). + +Do not encode a deny as `400` or an approve as `201`. Always return `200` and put the decision in the `sponsor` field. + + +### Timeout and fail-open behavior + +The Relayer waits up to **2 seconds** for your response. If your endpoint is slow, unreachable, returns a non-200 status, returns malformed JSON, or omits the `sponsor` field, the Relayer falls back to sponsoring the transaction. + +This fail-open behavior is deliberate: a broken webhook should not silently break sponsorship for your users. Denying a transaction requires an explicit `{"sponsor": false}` over HTTP 200. + +### Security + +- HTTPS is required. The Relayer will not follow redirects, so an HTTPS endpoint that redirects to `http://` is rejected. +- Configure a `webhookAuthToken` unless your endpoint enforces auth at a different layer (IP allowlist, edge proxy). +- The token is sent verbatim in the `Authorization` header — do not log this header. +- To rotate the token, call `UpdateGasSponsor` with a new value. To stop gating entirely, clear `webhookUrl`.