Creare un criterio

Un criterio è un set di regole in grado di bloccare le richieste di firma. Le richieste di firma includono transazioni blockchain e richieste di firma dei dati, come i dati digitati EIP-712. Ogni regola memorizzata ha un ambito, condizioni e una risposta BLOCK. Le regole abilitate si applicano cumulativamente: se una regola applicabile corrisponde, la richiesta viene rifiutata.

Se la valutazione dei criteri viene completata correttamente e nessuna regola applicabile restituisce una risposta BLOCK, la richiesta può continuare dopo che UWaaS Wallet Manager (UWM) ha autenticato il chiamante, autorizzato il wallet e la chiave e convalidato la richiesta di firma.

Per informazioni su UWaaS Wallet Manager, vedere Universal Wallet as a Service (UWaaS). Per i campi e le operazioni di richiesta API, vedere API di Universal Wallet Manager, tra cui:

Definisci condizioni regola

Una regola combina le condizioni con all, any e not. È possibile nidificare questi gruppi per definire una restrizione:

all corrisponde a ogni condizione figlio.
any corrisponde quando almeno una condizione figlio corrisponde.
not corrisponde quando la relativa condizione figlio non corrisponde.

Definire i gruppi di condizioni in linea. I riferimenti alle condizioni denominate non sono supportati per le regole di firma UWM.

Una foglia condizione specifica un fact, un operatore e un valore. Utilizzare path per selezionare una proprietà nidificata da un fact. Vengono valutati prima i valori priority più alti.

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

L'operatore in corrisponde quando il fact è uguale a uno dei valori elencati. Utilizzare all per combinare questa condizione con una condizione operation. Utilizzare any quando una delle diverse condizioni può attivare la limitazione.

Operatori

Operatore	Utilizzalo quando
`equal`, `notEqual`	Un fatto scalare deve essere uguale o diverso da un valore dello stesso tipo.
`in`, `notIn`	Un dato fact scalare deve essere visualizzato o meno in un elenco di valori.
`contains`, `doesNotContain`	Un fact array deve contenere o non contenere un valore.
`lessThan`, `lessThanEquals` (`lessThanInclusive`)	Un fact numerico deve essere minore o minore o uguale a un valore numerico.
`greaterThan`, `greaterThanEquals` (`greaterThanInclusive`)	Un fact numerico deve essere maggiore o maggiore o uguale a un valore numerico.

I confronti ordinati in amount, amount_atomic e native_value_atomic utilizzano l'aritmetica decimale esatta sia in /evaluate che in /internal/v1/authorize.

Utilizzare stringhe decimali per quantità atomiche e soglie grandi. Ad esempio:

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

UWM fornisce amount_atomic in unità di base e non lo converte in decimali token. Il fact amount è supportato quando fornito da un chiamante di /evaluate; UWM non lo aggiunge ai fact di firma.

Sono accettati numeri JSON decimali compresi nell'intervallo numerico sicuro. Invia valori numerici più grandi come stringhe; i valori numerici più grandi vengono rifiutati. I nomi degli operatori greaterThanInclusive e lessThanInclusive rimangono supportati. Gli operatori equal e notEqual confrontano i valori per tipo. Altri fatti mantengono il loro comportamento di confronto esistente.

Array Decorator

Definire il prefisso di un operatore con un decoratore e due punti, ad esempio someFact:equal. I decoratori cambiano il modo in cui l'operatore gestisce gli array o i relativi risultati.

Decorator	Utilizzalo quando
`someFact`	Almeno un elemento in un fact array corrisponde.
`everyFact`	Ogni elemento in un fact array corrisponde.
`someValue`	Il fact corrisponde ad almeno un elemento in un valore di array.
`everyValue`	Il fact corrisponde a ogni elemento in un valore di array.
`swap`	Il confronto utilizza il valore come fact e il fact come valore.
`not`	Il risultato dell'operatore di base deve essere negativo.

Ad esempio, someFact:equal può corrispondere a un ID token nell'array token_ids fornito per una chiamata batch ERC-1155 decodificata:

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

Utilizzare il gruppo di condizioni not per la logica booleana e il decoratore not: per negare un singolo operatore. La condizione e le priorità della regola impostano l'ordine di valutazione. Non consentono a una regola di sostituire un'altra BLOCK corrispondente.

Imposta ambito regola

Impostare scopelevels e targets per specificare le richieste di firma coperte da una regola. Ogni ambito selezionato deve corrispondere. Gli obiettivi all'interno di un ambito sono alternative.

Ambito	Destinazione richiesta	Utilizzalo per
`global`	Nessuno; specificare `scopelevels: ["global"]` di se stesso.	Limitazione applicabile a ogni richiesta di firma.
`org`	`targets.orgIds`	Limitazione per una o più organizzazioni.
`wallet`	`targets.walletIds`	Limitazione per uno o più portafogli.
`instance`	`targets.instanceIds`	Limitazione per una o più istanze di rete.
`asset`	`targets.assetIds`	Regole esistenti con ambito asset; mantenute per compatibilità.

Combinare gli ambiti quando una regola dipende da più dimensioni. Di seguito sono riportati alcuni esempi.

scopelevels: ["org",
        "wallet"]

richiede la corrispondenza sia dell'organizzazione che delle destinazioni wallet. Una regola solo wallet non dispone di un limite di organizzazione implicito. Utilizzare gli ID restituiti da UWM, non i nomi visualizzati.

Per limitare un metodo di contratto, confrontare contract_address e function_selector nelle condizioni. Aggiungere l'ambito instance se lo stesso metodo richiede restrizioni diverse su reti diverse. L'ambito asset viene mantenuto per le regole esistenti; queste condizioni non lo richiedono.

Per targets.instanceIds, utilizzare il file instanceId pubblico visualizzato dal wallet o dall'API di rete di UWM. Si tratta del file infra_instance_id registrato, non della chiave di database numerica o dell'ID catena. Aggiorna le regole con ambito di istanza precedente che utilizzano una chiave di database; UWM ora invia solo l'identificativo di istanza pubblica.

Corrispondenza richiesta di firma

Le condizioni possono utilizzare solo i fatti forniti per operation della richiesta. Il fatto operation è disponibile per ogni richiesta di firma.

`operation`	Dati aggiuntivi
`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`

UWM riconosce le chiamate canoniche ERC-20 transfer(address,uint256) con zero valore nativo senza registrazione del token. UWM non legge più capability.approved-token-contracts.

Il profilo erc20-transfer fornisce anche native_value_atomic ("0"), function_selector ("0xa9059cbb") e calldata_hash. Questi fatti consentono alle regole contract-call esistenti di mantenere le loro restrizioni complete.

Un'operazione erc20-transfer è anche contract-call per le condizioni dell'operazione. Entrambi i tipi di regola possono corrispondere alla stessa richiesta e qualsiasi BLOCK corrispondente la nega. Questo comportamento si applica alle condizioni booleane nidificate equal, notEqual, in, notIn in entrambi gli endpoint di valutazione. Altri fatti mantengono la loro semantica di uguaglianza normale.

L'operazione erc20-transfer corrisponde ai metodi transfer, non transferFrom o ERC-1155. Includere sempre il file contract_address nelle regole del token.

Le chiamate Canonical ERC-20 transferFrom, ERC-1155 safeTransferFrom e ERC-1155 safeBatchTransferFrom forniscono ulteriori informazioni su contract-call:

Chiamata	Dati aggiuntivi
ERC-20 `transferFrom`	`owner_address`, `to_address`, `amount_atomic`
ERC-1155 `safeTransferFrom`	`owner_address`, `to_address`, `token_id`, `amount_atomic`
ERC-1155 `safeBatchTransferFrom`	array `owner_address`, `to_address`, `token_ids` e `amounts` paralleli

UWM decodifica solo le chiamate con un layout ABI canonico supportato. Altre chiamate conservano i fact generici contract-call.

owner_address è l'indirizzo di origine nei dati della chiamata, non il wallet di firma. Un selettore identifica il layout dei dati di chiamata, non il comportamento del contratto distribuito. ERC-20 e ERC-721 condividono il selettore transferFrom, quindi applicano condizioni di importo solo a un contratto noto per implementare ERC-20. Gli indirizzi e i selettori vengono normalizzati in minuscolo; utilizzare valori di condizione minuscoli. Per le chiamate batch, non calcolare gli importi totali per ID token diversi.

amount_atomic e native_value_atomic sono stringhe decimali in unità di base; il valore nativo è in wei. Anche i valori interi EIP-712 sono stringhe decimali. Per EIP-712, typed_data contiene il dominio e il messaggio firmati. Un valore path è relativo a tale fatto: utilizzare $.message.value per il valore del messaggio e $.domain.chainId per l'ID catena firmato.

Le restrizioni di wallet, organizzazione e rete appartengono agli ambiti wallet, org e instance. I metadati Signer, Gas e Nonce non sono fatti condizionali. La destinazione dell'ambito asset non aggiunge un fact condizione asset.

Prima di abilitare una regola di firma

Utilizzare solo i dati fact elencati per l'operazione in Corrispondenza richiesta di firma. Includere una condizione operation quando una regola utilizza fact specifici delle operazioni.

Il salvataggio di una regola non conferma che UWM possa valutarla durante la firma. Ad esempio, UWM non fornisce un fact tier. Una regola che controlla se tier è uguale a gold può causare la mancata firma con un errore generico 500.

Se la firma non riesce dopo aver abilitato una regola, esaminarne i fact, le condizioni e l'ambito. Correggere la regola o chiedere a un amministratore autorizzato di disabilitarla se si tratta di un segnaposto non previsto. La disabilitazione di una restrizione obbligatoria ne elimina la protezione.

Prima di abilitare la regola in produzione, abilitarla per l'ambito previsto in un contesto di test e verificare che le richieste di firma effettive siano consentite o bloccate come previsto al momento della sottomissione. L'endpoint /evaluate da solo non verifica il funzionamento durante la firma perché accetta i fact forniti dall'utente, che possono essere diversi da quelli forniti durante la firma.

Crea regola

In questo esempio vengono bloccati i trasferimenti nativi in un unico indirizzo per un'organizzazione. Sostituire gli ID e l'indirizzo di esempio con i valori dell'ambiente in uso. La regola è disabilitata e non bloccherà le richieste finché non viene abilitata. Esaminare l'ambito e le condizioni prima di abilitare la regola.

{
  "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"
    }
  }
}

Inserire prima la condizione operation e assegnarla a una priorità più alta rispetto ai fact specifici dell'operazione. Durante la firma dell'autorizzazione, la valutazione non riesce se legge un fatto mancante; la richiesta non è consentita in silenzio.

Le regole di controllo degli endpoint di valutazione rispetto ai fact sottomessi. La firma in tempo reale utilizza i fact della richiesta convalidata di UWM e gli obiettivi di ambito dal wallet risolto. Utilizzare la valutazione per ispezionare una condizione, quindi confermare il risultato mediante il flusso di firma previsto.