Criar uma Política

Uma política é um conjunto de regras que pode bloquear solicitações de assinatura. As solicitações de assinatura incluem transações de blockchain e solicitações para assinar dados, como dados digitados EIP-712. Cada regra armazenada tem um escopo, condições e uma resposta BLOCK. As regras ativadas se aplicam cumulativamente: se alguma regra aplicável corresponder, a solicitação será negada.

Se a avaliação da política for concluída com sucesso e nenhuma regra aplicável retornar uma resposta BLOCK, a solicitação poderá continuar depois que o UWM (Wallet Manager) do UWaaS autenticar o chamador, autorizar a wallet e a chave e validar a solicitação de assinatura.

Para obter informações sobre o Gerenciador de Wallet UWaaS, consulte Wallet como Serviço Universal (UWaaS). Para campos e operações de solicitação de API, consulte as APIs do Universal Wallet Manager, incluindo:

Definir Condições da Regra

Uma regra combina condições com all, any e not. Você pode aninhar esses grupos para definir uma restrição:

all corresponde quando cada condição filha corresponde.
any corresponde quando pelo menos uma condição filha corresponde.
not corresponde quando sua condição filha não corresponde.

Definir grupos de condições em linha. As referências de condição nomeada não são suportadas para regras de assinatura de UWM.

Uma folha de condição especifica um fato, um operador e um valor. Use path para selecionar uma propriedade aninhada de um fato. Valores priority mais altos são avaliados primeiro.

{
  "fact": "to_address",
  "operator": "in",
  "value": ["<blocked-address>"]
}

O operador in corresponde quando o fato é igual a um dos valores listados. Use all para combinar essa condição com uma condição operation. Use any quando uma das várias condições puder acionar a restrição.

Operadores

Operador	Usá-lo quando
`equal`, `notEqual`	Um fato escalar deve ser igual ou diferente de um valor do mesmo tipo.
`in`, `notIn`	Um fato escalar deve aparecer ou não em uma lista de valores.
`contains`, `doesNotContain`	Um fato de matriz deve conter ou não um valor.
`lessThan`, `lessThanEquals` (`lessThanInclusive`)	Um fato numérico deve ser menor que, ou menor ou igual a um valor numérico.
`greaterThan`, `greaterThanEquals` (`greaterThanInclusive`)	Um fato numérico deve ser maior que, ou maior ou igual a um valor numérico.

As comparações ordenadas em amount, amount_atomic e native_value_atomic usam aritmética decimal exata em /evaluate e /internal/v1/authorize.

Use strings decimais para quantidades atômicas e limites grandes. Por exemplo:

{ "fact": "amount_atomic", "operator": "greaterThanEquals", "value": "1000000000000000000" }

O UWM fornece amount_atomic em unidades base e não o converte em decimais de token. O fato amount é suportado quando fornecido por um chamador do /evaluate; o UWM não o adiciona aos fatos de assinatura.

São aceitos números JSON decimais dentro do intervalo numérico seguro. Envie valores numéricos maiores como strings; literais numéricos maiores são rejeitados. Os nomes dos operadores greaterThanInclusive e lessThanInclusive permanecem suportados. Os operadores equal e notEqual comparam valores por tipo. Outros fatos mantêm seu comportamento de comparação existente.

Decoradores de matriz

Prefixe um operador com um decorador e dois-pontos, como someFact:equal. Os decoradores mudam a forma como o operador lida com matrizes ou seu resultado.

Decorador	Usá-lo quando
`someFact`	Pelo menos um item em um fato de matriz corresponde.
`everyFact`	Cada item em um fato de matriz corresponde.
`someValue`	O fato corresponde a pelo menos um item em um valor de matriz.
`everyValue`	O fato corresponde a cada item em um valor de matriz.
`swap`	A comparação usa o valor como fato e o fato como valor.
`not`	O resultado do operador base deve ser negado.

Por exemplo, o someFact:equal pode corresponder a um ID de token no array token_ids fornecido para uma chamada em batch ERC-1155 decodificada:

{
  "fact": "token_ids",
  "operator": "someFact:equal",
  "value": "42"
}

Use o grupo de condições not para lógica booliana e o decorador not: para negar um operador individual. A condição e as prioridades da regra definem a ordem de avaliação. Eles não permitem que uma regra substitua outra BLOCK correspondente.

Definir o Escopo da Regra

Defina scopelevels e targets para especificar quais solicitações de assinatura uma regra abrange. Cada escopo selecionado deve corresponder. Alvos dentro de um escopo são alternativas.

Escopo	Destino obrigatório	Use-o para
`global`	Nenhum; especificar `scopelevels: ["global"]` por si só.	Uma restrição que se aplica a cada solicitação de assinatura.
`org`	`targets.orgIds`	Uma restrição para uma ou mais organizações.
`wallet`	`targets.walletIds`	Uma restrição para uma ou mais carteiras.
`instance`	`targets.instanceIds`	Uma restrição para uma ou mais instâncias de rede.
`asset`	`targets.assetIds`	Regras existentes no escopo do ativo; mantidas para compatibilidade.

Combine escopos quando uma regra depender de mais de uma dimensão. Por exemplo,

scopelevels: ["org",
        "wallet"]

requer que os alvos da organização e da wallet correspondam. Uma regra somente wallet não tem um limite de organização implícito. Use os IDs retornados por UWM, e não os nomes para exibição.

Para restringir um método de contrato, corresponda a contract_address e function_selector nas condições. Adicione o escopo instance se o mesmo método exigir diferentes restrições em redes diferentes. O escopo asset é mantido para regras existentes; essas condições não o exigem.

Para targets.instanceIds, use o instanceId público mostrado pela wallet do UWM ou pela API de rede. Este é o infra_instance_id registrado, não a chave do banco de dados numérico ou o ID da cadeia. Atualize regras mais antigas no escopo da instância que usam uma chave do banco de dados; o UWM agora envia apenas o identificador de instância pública.

Corresponder à solicitação de assinatura

As condições podem usar somente fatos fornecidos para o operation da solicitação. O fato operation está disponível para cada solicitação de assinatura.

`operation`	Fatos adicionais
`native-transfer`	`amount_atomic`, `to_address`
`erc20-transfer`	`amount_atomic`, `to_address`, `contract_address`
`contract-deployment`	`amount_atomic`, `init_code_hash`
`contract-call`	`contract_address`, `native_value_atomic`, `function_selector`, `calldata_hash`
`eip712`	`primary_type`, `verifying_contract`, `typed_data`

O UWM reconhece chamadas ERC-20 transfer(address,uint256) canônicas com valor nativo zero sem registro de token. O UWM não lê mais capability.approved-token-contracts.

O perfil erc20-transfer também fornece native_value_atomic ("0"), function_selector ("0xa9059cbb") e calldata_hash. Esses fatos permitem que as regras contract-call existentes mantenham suas restrições completas.

Uma operação erc20-transfer também é uma contract-call para condições de operação. Ambos os tipos de regra podem corresponder à mesma solicitação, e qualquer BLOCK correspondente a nega. Esse comportamento se aplica às condições Boolianas equal, notEqual, in, notIn e aninhadas em ambos os pontos finais de avaliação. Outros fatos mantêm sua semântica de igualdade normal.

A operação erc20-transfer corresponde aos métodos transfer, não transferFrom ou ERC-1155. Sempre inclua o contract_address pretendido nas regras de token.

As chamadas Canonical ERC-20 transferFrom, ERC-1155 safeTransferFrom e ERC-1155 safeBatchTransferFrom fornecem fatos adicionais contract-call:

Chamada	Fatos adicionais
ERC-20 `transferFrom`	`owner_address`, `to_address`, `amount_atomic`
ERC-1155 `safeTransferFrom`	`owner_address`, `to_address`, `token_id`, `amount_atomic`
ERC-1155 `safeBatchTransferFrom`	`owner_address`, `to_address`, arrays `token_ids` e `amounts` paralelos

O UWM decodifica somente chamadas com um layout ABI canônico suportado. Outras chamadas mantêm os fatos contract-call genéricos.

owner_address é o endereço de origem nos dados de chamada, não a wallet de assinatura. Um seletor identifica o layout de dados de chamada, não o comportamento do contrato implantado. O ERC-20 e o ERC-721 compartilham o seletor transferFrom, portanto, aplique condições de valor apenas a um contrato conhecido por implementar o ERC-20. Endereços e seletores são normalizados para letras minúsculas; use valores de condição em letras minúsculas. Para chamadas em batch, não totalize valores para IDs de token diferentes.

amount_atomic e native_value_atomic são strings decimais em unidades base; o valor nativo está em wei. Os valores inteiros EIP-712 também são strings decimais. Para EIP-712, typed_data contém o domínio assinado e a mensagem. Um path é relativo a esse fato: use $.message.value para o valor da mensagem e $.domain.chainId para o ID da cadeia assinada.

As restrições de wallet, organização e rede pertencem aos escopos wallet, org e instance. Metadados de signatário, gás e nonce não são fatos de condição. O destino do escopo asset não adiciona um fato de condição asset.

Antes de ativar uma regra de assinatura

Use apenas os fatos listados para a operação em Corresponder à solicitação de assinatura. Inclua uma condição operation quando uma regra usar fatos específicos da operação.

Salvar uma regra não confirma que o UWM pode avaliá-la durante a assinatura. Por exemplo, o UWM não fornece um fato tier. Uma regra que verifica se tier é igual a gold pode causar falha na assinatura com um erro genérico 500.

Se a assinatura falhar depois que você ativar uma regra, revise seus fatos, condições e escopo. Corrija a regra ou peça a um administrador autorizado que a desative se for um espaço reservado não intencional. A desativação de uma restrição necessária remove sua proteção.

Antes de ativar a regra em produção, ative-a para o escopo pretendido em um contexto de teste e verifique se as solicitações de assinatura reais são permitidas ou bloqueadas conforme pretendido quando são enviadas. O ponto final /evaluate sozinho não verifica o comportamento durante a assinatura porque aceita fatos fornecidos pelo usuário, que podem diferir dos fornecidos durante a assinatura.

Criar Regra

Este exemplo bloqueia transferências nativas para um endereço de uma organização. Substitua os IDs exemplo e o endereço pelos valores de seu ambiente. A regra é desativada e não bloqueará solicitações até que você a ative. Revise o escopo e as condições antes de ativar a regra.

{
  "name": "block-restricted-native-recipient",
  "description": "Block native transfers to the restricted recipient",
  "category": "transaction-policy",
  "enabled": false,
  "scopelevels": ["org"],
  "targets": {
    "orgIds": ["<organization-id>"]
  },
  "conditions": {
    "all": [
      {
        "fact": "operation",
        "operator": "equal",
        "value": "native-transfer",
        "priority": 100
      },
      {
        "fact": "to_address",
        "operator": "equal",
        "value": "0x3333333333333333333333333333333333333333",
        "priority": 1
      }
    ]
  },
  "response": {
    "type": "BLOCK",
    "params": {
      "reason": "restricted-recipient"
    }
  }
}

Coloque a condição operation primeiro e atribua a ela uma prioridade mais alta do que os fatos específicos da operação. Durante a autorização de assinatura, a avaliação falha se ler um fato ausente; a solicitação não é permitida silenciosamente.

Os pontos finais de avaliação verificam as regras em relação aos fatos que você envia. A assinatura ao vivo usa fatos da solicitação validada e dos alvos de escopo da UWM de sua carteira resolvida. Use a avaliação para inspecionar uma condição e, em seguida, confirme o resultado através do fluxo de assinatura pretendido.